wiki:eqverify
Last modified 8 years ago Last modified on 05/14/12 15:56:45

Earthworm Module: eqverify

Contributed by:

Function

Passes only events verified as earthquakes (part of mega-module)

Details

Eqverify is a sub-module in Earthworm's event-processing mega-module. It takes the output from eqcoda (TYPE_EVENT2K messages) and performs a number of tests to determine if the event looks like an earthquake or noise. Only those events verified to be earthquakes are passed along to the next sub-module. Eqverify starts the next sub-module specified in its "PipeTo" command (generally hypo_mgr) and communicates to it via a one-directional pipe. Eqcoda passes any messages other than TYPE_EVENT2K thru to the next link without modifying them in any way.

Eqverify can perform up to four different earthquake verification tests on each event. One of the tests analyzes the distribution of arrival times reported for the event; the remaining three analyze different coda characteristics of the arrivals. Each test can be turned on or off by a configuration-file switch. Bad test results (results that show that the event looks more like noise than an earthquake) add to a count of "demerit points" for the event. If the total number of demerits meets or exceeds a (configurable) threshold, the event is declared to be noise, the complete TYPE_EVENT2K message is written to eqverify's log file, and the event is withheld from any further processing. To avoid the big mistake of mis-identifying a large earthquake as noise and withholding it, there is a "force-thru" feature in eqverify. Any event with a minimum number of arrivals and a minimum duration magnitude (defaults are 17 arrivals, magnitude 2.0) will be passed through to the next processing sub-module, regardless of its test results. We'd rather report a few bogus events than drop "the big one!"

A brief description of each of the verification tests follows:

  1. Test on Arrival Time Distribution ("test_pgroup" command):
  • In this test, all arrivals within "MaxDeltaT" seconds (default = 30) of the first-arriving pick are examined to see if they belong to a glitch.
  • A glitch is defined as a certain number of picks within a given time interval (set by the "define_glitch" command; default is 4 picks within 0.03 seconds).
  • If 50% or more of these picks belong to glitches, the event is declared noise.
  • If 30-50% of the picks are glitch-picks, the event's demerit count is incremented by 1.
  1. Test on Coda Weight or Quality ("test_codawt" command):
  • This test, taken from Lindh and Hirshorn's program eqmeas, calculates a coda weight (0 is a good quality coda, 4 is poor) for each pick. It then finds the average of all coda weights for the event and adds this average value to the event demerit count.
  1. Test on RMS of slope fit to Coda Amplitudes ("test_freefitrms" command):
  • This test looks at the rms values from free-fit slopes to the coda average absolute values. This test, taken from Lindh and Hirshorn's program eqmeas, considers only the rms for each arrival where at least 3 coda average absolute values were used in determining the free-fit slope of the coda decay. Eqverify finds the median of all the rms values for such free-fit. If the median rms value is greater than 0.25 (bad fit to coda amplitudes), the event demerit count is incremented by 1. With default settings, this test by itself cannot cause an event to be declared noise.
  1. Test on Slope of Coda Decay vs Event Magnitude ("test_slopevsmag" command):
  • This test compares the median slope of coda decay (fit to the coda window average absolute values) to the magnitude calculated from the median coda duration for each event. This test, taken from Lindh and Hirshorn's program eqmeas, increments the event demerit count by the absolute value of the result of this equation:

<median slope> + 0.7*<magnitude from median duration> + 0.5

For a normal earthquake, the slope fit to the coda windows should be negative and the result from the above equation should be zero. For a noise event, the result from the above equation may be unbounded. This test alone may cause an event to be declared noise.

NOTE: If you are running eqverify as part of the preliminary-event-processing mega-module (started by eqprelim), you should use ONLY the test on arrival time distribution ("test_pgroup"). All coda tests should be turned off since the event will have incomplete coda information at the time eqverify tests it.

Configuration File Commands

On startup, eqverify reads the configuration file named on the command-line. Commands in this file set up all parameters used in verifying events to be earthquakes. In the control file, lines may begin with a valid eqverify command (listed below) or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).

@  allows control files to be nested; one control file can be
   accessed from another with the command "@" followed by
   a string representing the path name of the next control file
   (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

EXAMPLE CONFIGURATION FILE

 #
# This is eqverify's parameter file
#
MyModuleId  MOD_EQPROC  # module id to label logfile  with.
                        # Note: eqverify is part of a mega-module which is
                        # ultimately started by the program eqproc.  All
                        # child processes of this mega-module need to use the
                        # same module id (thus use eqproc's module id).
LogFile       1         # 0=no log; 1=log errors

# send output to the following command:
# PipeTo "log_everything"
PipeTo "hypo_mgr hypo_mgr.d ncal.hyp"

# Required commands to turn glitch tests on (>0) or off (=0)
test_slopevsmag  1
test_freefitrms  1
test_codawt      1
test_pgroup      1

# Optional commands that change eqverify test defaults
# force_report  18 2.0    # report events with more than 18 picks
#                         # and mag>=2.0 regardless of event weight
# define_glitch  4 0.035  # a glitch is at least 4 picks within
                          # 0.035 seconds
# EventThreshold     3    # event weight at which event is "noise"
# MaxDeltaT         30.   # consider arrival times within this many
#                         # seconds of the 1st arriving pick
# coda_clip        820    # level at which a coda-avg-absolute-value
#                         # is clipped (see notes in eqcoda.command)

FUNCTIONAL COMMAND LISTING

Below are the commands recognized by eqverify, grouped by the function they influence. Some of the commands are marked "required"; these commands must be specified in the control file in order for eqverify to operate. Other commands have default values which are over-ridden when a command is given.

	Earthworm System Setup:
 		MyModuleId	required
                PipeTo          required

        Event Verification:
		test_codawt	required
		test_freefitrms required
		test_pgroup 	required
		test_slopevsmag required
		coda_clip
 		define_glitch
		EventThreshold
		force_report
		MaxDeltaT

	Output Control:
		LogFile		required

ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and the values used by Calnet are listed after each command description.

The following list is organized by:

command [argument here]

coda_clip [klipc]
Processed by: eqverify_config
Function: verification

Define the number of counts klipc above which a 2-second trace data window's average absolute amplitude should be considered clipped. Eqcoda also uses the "coda_clip" command; make sure that both eqcoda and eqverify are using the same value for klipc! Eqverify uses klipc in calculating an eqmeas-style coda weight that is used in the coda weight test (see "test_codawt" command). This coda weight is slightly different than that calculated by eqcoda.

Default:  coda_clip 820			Calnet:  coda_clip 820

define_glitch [npick nsec]
Processed by: eqverify_config
Function: verification

Defines a glitch as at least npick arrivals within nsec seconds. This definition is used in the test on the temporal distribution of P-arrivals (see "test_pgroup" command for an explanation).

Note: nsec should be set slightly larger than an integer multiple of the pick-timing resolution to avoid missing glitches due to round-off errors in floating point arithmetic (for example, our picks are reported to the nearest 0.01 seconds, so we set nsec to 0.035 sec instead of 0.03 sec).

Default:  define_glitch 4 0.035		Calnet:  define_glitch 4 0.035

EventThreshold [thresh]
Processed by: eqverify_config
Function: verification

Sets the event weight thresh below which an event is a verified earthquake. Each event begins with an event weight of zero (perfect event). Up to four tests (see "test_*" commands) may be performed to verify that the event has the characteristics of a real earthquake. Three of the tests evaluate coda characteristics, and the other evaluates the temporal distribution of P-arrivals. Each test increments the event weight if non-earthquake characteristics are detected. If the event weight is equal to or greater than thresh after all the tests are performed, the event is declared noise and is written to eqverify's log file. Events with weights less than thresh are piped to the next process.

Default:  EventThreshold 3		Calnet:  EventThreshold 3

force_report [npick mag]
Processed by: eqverify_config
Function: verification

Sets a safety-valve to force large events to be reported regardless of their final event weight. An event with more than npick arrivals and a magnitude of at least mag will always be sent along to the next process, even if its event weight exceeds the event threshold thresh. The event's magnitude is calculated from its median coda duration. This safety-valve is necessary for large events because the picker terminates coda calculations at 144 seconds, before the coda begins to decay. This causes the test described in the "test_slopevsmag" command to yield results that would call the event noise. And we don't want a real large earthquake to be thrown away! Note: defaults were taken from Lindh and Hirshorn's program, eqmeas.

Default:  force_report 17 2.0		Calnet:  force_report 17 2.0

LogFile [switch]
Processed by: eqverify_config
Function: output

Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, eqverify will write daily log file(s) called eqverifyxx.log_yymmdd where xx is eqverify's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

Default:  none

MaxDeltaT [sec]
Processed by: eqverify_config
Function: verification

Defines the time interval for studying the temporal distribution of P-arrivals (see "test_pgroup" command). Only picks within sec seconds of the first-arriving pick are considered in the test.

Default:  MaxDeltaT 30.0		Calnet:  MaxDeltaT 30.0

MyModuleId [mod_id]
Processed by: eqverify_config
Function: Earthworm setup

Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number.

NOTE: eqverify is part of a mega-module which is ultimately started by the program eqproc. All sub-modules of this megamodule should be given the same module id.

Default:  none				Calnet:  MyModuleId MOD_EQPROC

PipeTo [cmdstring]
Processed by: eqverify_config
Function: Earthworm setup

Sets the command to which eqverify will pipe a hypoinverse-format archive (with shadow cards) event for the next step in earthquake processing. Blank spaces are allowed in cmdstring as long as the entire command is enclosed in double-quotes.

Default:  none
Calnet:   PipeTo "hypo_mgr hypo_mgr.d ncal.hyp"

test_codawt [switch]
Processed by: eqverify_config
Function: verification

Sets the switch for performing the coda weight test on each event. If switch is non-zero, the test will be performed; if switch is zero, it will not be performed. This test, taken from Lindh and Hirshorn's program eqmeas, calculates a coda weight for each pick in the manner of eqmeas. It then finds the average of all coda weights for the event and adds this average value to the event weight.

Default:  none				Calnet:  test_codawt 1

test_freefitrms [switch]
Processed by: eqverify_config
Function: verification

Sets the switch for performing a test on the rms values from free-fit slopes to the coda average absolute values. If switch is non-zero, the test will be performed; if switch is zero, it will not be performed. This test, taken from Lindh and Hirshorn's program eqmeas, considers only the rms for each arrival where at least 3 coda window average absolute values were used in the free-fit. It finds the median of all such free-fit rms's for the event. If the median rms value is greater than 0.25 (bad fit to coda amplitudes), the event weight is incremented by 1. Otherwise (good fit), the event weight remains the same. With default settings, this test by itself cannot cause an event to be declared noise.

Default:  none				Calnet:  test_freefitrms 1

test_pgroup [switch]
Processed by: eqverify_config
Function: verification

Sets the switch for performing a test the temporal distribution of P-arrivals for each event. If switch is non-zero, the test will be performed; if switch is zero, it will not be performed. In this test, all arrivals within "MaxDeltaT" seconds (default = 30) of the first-arriving pick are examined to see if they belong to a glitch as defined by default settings (at least 4 picks within 0.03 seconds) or by the "define_glitch" command. If 50% or more of all picks belong to glitches, the event is declared noise. If 30-50% of the picks are glitch-picks, the event weight is incremented by 1.

Default:  none				Calnet:  test_pgroup 1

test_slopevsmag [switch]
Processed by: eqverify_config
Function: verification

Sets the switch for performing a test on the median slope (fit to the coda window average absolute values) versus the magnitude calculated from the median coda duration for each event. If switch is non-zero, the test will be performed; if switch is zero, it will not be performed. This test, taken from Lindh and Hirshorn's program eqmeas, increments the event weight by the absolute value of the result of this equation:

median-slope + 0.7*magnitude-from-median-duration + 0.5

For a normal earthquake, the slope fit to the coda windows should be negative and the result from the above equation should be zero. For a noise event, the result from the above equation may be unbounded. This test alone may cause an event to be declared noise.

Default:  none				Calnet:  test_slopevsmag 1

NOTES ON EQVERIFY'S DEFAULT VALUES FOR ITS CONSTANTS

For historical perspective, much of the verification source code was originally written to work on Rex Allen RTP digitizer data which had an output range of +/- 2500 counts for an input signal of +/- 2.5 Volts. The Earthworm system uses a 12-bit A/D; so its output ranges from +/- 2048 counts for the same input signal of +/- 2.5 Volts.

   For Allen RTP digitizers,      1 mV = 1.0  counts
   For Earthworm digitizers,      1 mV = 0.82 counts

Many constants used here were originally defined for the RTP data to be "nice round numbers" corresponding to some number of mV. The defaults for these constants have been converted for the Earthworm data; they still correspond to the same mV values (they just aren't "nice round numbers" any more).

Helpful Hints