Earthworm Modules:
Pick_ew Configuration File Commands

(last revised Mar 28, 2008)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Station list format
5. Additional references on the picker algorithm

On startup, pick_ew reads the configuration file named on the command line. Commands in this file set up all parameters used in picking P-wave arrivals from Earthworm waveform data. In the control file, lines may begin with a valid pick_ew 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: @pick_ew.d).
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

1. EXAMPLE CONFIGURATION FILE

#
# Pick_ew's Configuration File
#
MyModId MOD_PICK_EW # This instance of pick_ew
StaFile
pick_ew.sta # File containing station name/pin# info
InRing WAVE_RING # Transport ring to find waveform data on,
OutRing PICK_RING # Transport ring to write output to,
HeartbeatInt 30 # Heartbeat interval, in seconds,
RestartLength 100 # Number of samples to process for restart
MaxGap 15 # Maximum gap to interpolate
Debug 0 # If 1, print debugging message

2. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by pick_ew, grouped by the function they influence. All of the commands are required; they must be specified in the control file (in any order) for pick_ew to operate.

	Earthworm system setup:
InRing Shared memory region for input
OutRing Shared memory region for output
MyModId Module id for pick_ew
HeartBeatInt Interval between heartbeats

Picking Parameters:
RestartLength Number of samples to process for restarts
MaxGap Maximum gap (#samples) to interpolate
StaFile File containing station names and picking parameters
NoCoda Optional to NOT do CODA PROCESSING (experimental)

Output Control:
Debug Debugging flag
PickIndexDir Directory where pick_ew_MMM.ndx files will be written (optional)

3. 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. None of the commands has any default value. The values used by Calnet are listed after each command description.


command arg1				processed by		function

Debug flag				GetConfig		output		
Sets a flag to control the volume of debugging information output by pick_ew. If flag is zero, no debug info is written. If flag is non-zero, debug information is written to the logfile and screen.

Default:  none				
Sample: Debug 0

HeartBeatInt nsec			GetConfig		Earthworm setup		
Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by pick_ew.

Default:  none				
Sample: HeartBeatInt 30

InRing ring				GetConfig		Earthworm setup		
Tells pick_ew which shared memory region to find its input waveforms on. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. By default, pick_ew processes all TYPE_TRACEBUF messages that reside on ring, regardless of their installation id or module id.

Default:  none				
Sample: InRing WAVE_RING

MaxGap maxgap				GetConfig		output		
Sets maxgap, the maximum length (in samples) of a data gap which pick_ew will allow without restarting the picking algorithm. When pick_ew detects a data gap less than or equal to maxgap samples on a given channel, it will do a simple linear interpolation across the gap and continue in the picking algorithm as if there were no data gap. If a gap is longer than maxgap samples, then pick_ew will drop all active pick and coda calculations for that channel and will enter the "restart" phase (see RestartLength command) of the algorithm.

Default:  none
Sample:   MaxGap 10
  

MyModId mod_id				GetConfig		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. If more than one pick_ew is running at the same time, they must be given different module ids! (If 2 pick_ew's are given the same module id, other modules that listen to pick_ew output may report many "missed message" errors).

Default: none
Sample: MyModId MOD_PICK_EW

Sample:   MaxGap 10


NoCoda flag				GetConfig		picking params		

This is an experimental feature that is off by default. It forces the coda termination checking to cease functioning if the flag is set to 1.
Default:  none				
Sample: NoCoda 1


OutRing ring				GetConfig		Earthworm setup		
Tells pick_ew which shared memory region to use for all its output (picks, codas, heartbeats and errors). ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

Default:  none				
Sample: OutRing PICK_RING



PickIndexDir dir				GetConfig		picking params		

This allows the pick_ew_MMM.ndx index files (used to track pick id's) to be placed in a different directory than the params directory. If this is a relative path, then the path should be relative to the params directory. In either case, the directory must already exist. This is an OPTIONAL FEATURE. If not set, then the pick_ew_MMM.ndx files will be written into the params directory as they have always been. For reference, the MMM refers to the module id.
Default:  none				
Sample: PickIndexDir pick_index



RestartLength nrestart			GetConfig		picking params		
Sets nrestart, the number of samples pick_ew will process on startup for each channel to obtain background values before entering the P-wave picking phase for that signal. Once running, any time pick_ew detects a data gap longer than MaxGap samples in a given channel's data, pick_ew will drop any active pick or coda calculations for that channel. It will then "restart" that channel by processing the next nrestart samples to reestablish baseline values, after which it will return to the picking phase of the algorithm.

Default:  none
Sample:   RestartLength 100
  

StaFile name				GetConfig		picking params		
Tells pick_ew the name of the file that contains the pick/don't pick flag, pin numbers, station code, and per-channel picking parameters. name is a character string; it may be enclosed in double-quotes, but it doesn't have to be. See section 4 below for the format of this file.

Default:  none
Sample:   StaFile "pick_ew.sta"
  

4. STATION LIST FORMAT

By default, pick_ew processes all TYPE_TRACEBUF messages (regardless of their installation id or module id) that reside on transport ring specified in the InRing command. All of the channels of trace data being processed by the Earthworm system should be described in pick_ew's station list file. This file contains one line per input channel. Each line contains 22 required fields used by pick_ew to identify the channel and set all the picking parameters for that channel. In v5.1 and higher an optional 23rd field was added for use by the module eqcoda. Pick_ew ignores this 23rd field if it exists. Upon retrieving a TYPE_TRACEBUF message from the ring, pick_ew finds the appropriate parameters for that message by matching the station, component, and network fields in the message header to a line from the station file. If it can't find a match, pick_ew won't process that tracebuf message.

A sample portion of a pick_ew station list file appears below.
Note that a comments are preceded by a #.

----------------------------------------------------

#
# This is a sample station list for the pick_ew program.
#
# MinBigZC RawDataFilt LtaFilt DeadSta PreEvent
# Pick Pin Station/ MinSmallZC MaxMint StaFilt RmavFilt AltCoda
# Flag Numb Comp/Net/Loc Itr1 MinPeakSize i9 CharFuncFilt EventThresh CodaTerm Erefs ClipCount
# ---- ---- -------- ---------------------------------------------------------------------------------------------
1 0 AAR VHZ NC -- 3 40 3 60 500 3 .985 3. .6 .03 5. .9961 1200. 49.14 .8 1.5 50000. 2048
1 1 AAS VHZ NC -- 3 40 3 60 500 3 .985 3. .6 .03 5. .9961 1200. 49.14 .8 1.5 50000. 2048
0 2 ABL VHZ CI -- 3 40 3 60 500 3 .985 3. .6 .03 5. .9961 1200. 49.14 .8 1.5 50000. 2048
1 3 ABR VHZ NC -- 3 40 3 60 500 3 .985 3. .6 .03 5. .9961 1200. 49.14 .8 1.5 50000. 2048
1 2005 KCPB BHZ NC -- 3 40 3 162 500 3 .939 3. .4 .015 5. .9961 1200. 132.7 .8 1.5 135000. 8388608
# end of station file
----------------------------------------------------

Each line in the station file contains the following 24 fields, separated by white space:

Channel Identification:

 1. Pick Flag	if Pick Flag is 0, pick_ew will not try to pick P-wave arrivals 
from this trace. If Pick Flag is 1, the trace will be picked.

2. Pin Numb this field is not used by pick_ew, but exists for posterity
and for potential use by other programs. Each input signal in a given
Earthworm system should have a pin number Pin Numb (2-byte integer)
that is unique across all data sources within the system. For example,
if we use two digitizers with 256 channels each, our pin numbers would
range from 0 to 511.

3. Station the first of 3 fields (Station-Comp-Net) that will uniquely identify
each trace of seismic data. Station is a string, up to 5 characters,
that identifies the physical site of the seismic instrument. This label
must be unique within a given network.

4. Comp a 3-character string to identify the component of motion
recorded by this seismic trace.

5. Net a 2-character string that identifies the network that
operates the seismic instrument.

6. Loc a 2-character string that identifies the location code that
describes the sensor location.
Event Termination/Evaluation Criteria:
 7. Itr1	(i5 in earlier code) Sets Itr1 which is used to calculate the 
zero-crossing termination count. The pick_ew calculates itrm, the
number of consecutive small-zero crossings (zero-crossings where the
short-term average is less than the critical termination level) to be
allowed before declaring the event over. itrm = Itr1 + m / Itr1
where m is the zero-crossing counter. itrm will start out quite small
at the beginning of an event and will increase during an event to a
maximum of 50.

8. MinSmallZC (i6 in earlier code) Defines the minimum number of zero-crossings for
a valid pick. An event is declared over and potentially valid after
MinSmallZC zero-crossings. Pick_ew then evaluates the event to determine
if it was a seismic event or noise.

9. MinBigZC (i7 in earlier code) Defines the minimum number of "big zero-crossings" for
a valid pick. No pick is reported unless at least MinBigZC big zero-crossings
occurred while the event was active. [A "big zero-crossing" amplitude
must exceed rbig, where rbig is (the largest amplitude of first 3 half-
cycles after event activation)/3. A "big zero crossing" must also
represent a crossing of opposite polarity to the previous crossing].

10. MinPeakSize (i8 in earlier code) Defines the minimum amplitude (digital counts) for
a valid pick. No pick is reported unless one of the first three peaks
of an event has an amplitude larger than MinPeakSize digital counts.

11. MaxMint (hard-wired at 500 in earlier code) Maximum interval (in samples) between
zero crossings. If no zero crossings occur within MaxMint data samples,
the pick event is terminated.

12. i9 (i9 in earlier code) Defines the minimum coda length (seconds) for a
valid pick. No pick is reported unless its coda is at least i9 seconds
long.
Waveform Filtering Parameters:
13. RawDataFilt	(c1 in earlier code) Sets the filter parameter RawDataFilt that is 
applied to the raw trace data. This is essentially a recursive highpass
filter that removes the DC offset from the data.

14. CharFuncFilt (c2 in earlier code) Sets the filter parameter CharFuncFilt that is
applied in the calculation of the characteristic function of the
waveform data.

15. StaFilt (c3 in earlier code) Sets the filter parameter (time constant) StaFilt
that is used in the calculation of the short-term average (STA)
of the characteristic function of the trace.

16. LtaFilt (c4 in earlier code) Sets the filter parameter (time constant) LtaFilt
that is used in the calculation of the long-term average (LTA)
of the characteristic function of the trace.

17. EventThresh (c5 in earlier code) Sets the STA/LTA event threshold. An event (a pick)
is declared when STA is larger than EventThresh*LTA. Once an event
is declared, pick_ew enters an event evaluation mode to determine if
the event is a P-wave arrival or noise.

18. RmavFilt Filter parameter (time constant) used
to calculate the running mean of the absolute value of the waveform data. Usually set to 0.9961.

19. DeadSta (c6 in earlier code) Sets the dead station threshold (counts).
If the running average of the absolute value (AAV) of a trace is
greater than DeadSta digital counts, the channel is considered
dead and the pick_ew does not attempt to pick arrivals.
Coda Termination Parameters:
20. CodaTerm	(c7 in earlier code) Sets the "normal" coda termination threshold (counts).  
Two methods are used to determine if the coda length calculation
is over. For quiet stations, the coda is "normally" terminated
when the AAV of a 2-second waveform window drops below CodaTerm digital
counts. For noisy stations, an alternate termination method is used
(see AltCoda & PreEvent, below). Pick_ew stops all coda calculations
144 seconds after event activation, even if the coda AAV hasn't reached
the termination value. In the Northern California Seismic Network's
convention, CodaTerm is the number of digital counts produced by a
discriminator output signal (input to the Earthworm A/D) of 60 mV.
The 2-bit Earthworm A/D has an input range of +/- 2.5 volts and an
output range of 0 to 4095 counts (-2048 to 2047 counts). For such a
system, a 60 mV input will produce a sample of 49.1 counts.

21. AltCoda (c8 in earlier code) Defines the "noisy station level" at which
pick_ew should use the alternate coda termination method. If the
AAV of a channel is greater than CodaTerm*AltCoda digital counts
when an event is declared, pick_ew uses the alternate coda termination
method.

22. PreEvent (c9 in earlier code) Defines the alternate coda termination threshold
for noisy stations. If the AAV of a channel is greater than
CodaTerm*AltCoda digital counts when an event is declared, the coda is
considered over when the AAV of a 2-second waveform window drops to
less than PreEvent*(pre-event signal amplitude). Pick_ew stops
all coda calculations 144 seconds after event activation, even if the
coda AAV hasn't reached the termination value.

23. Erefs (hard-wired at 50000. in earlier code) Used in calculating the increment
(crtinc) to be added to the criterion level (ecrit) at each zero crossing.
The criterion level is used to determine if the event is over.
crtinc = eref / Erefs
where eref is the current STA/LTA reference level. The smaller Erefs is,
the faster ecrit will increase, and the sooner the event will terminate.
Optional Parameters:
24. ClipCount	(added in v5.1 for use by eqcoda, ignored by pick_ew) Specifies 
the maximum absolute amplitude (in counts zero-to-peak) that can be
expected for this channel. Eqcoda calculates clipping thresholds for
P-amplitudes and coda-window average absolute amplitudes as a fraction
of ClipCount.

5. ADDITIONAL REFERENCES ON THE PICKER ALGORITHM

Allen, Rex V., Automatic Earthquake Recognition and Timing from Single Traces, 
Bull. Seism. Soc. Am., v. 68, pp 1521-1532, 1978.

Allen, Rex, Automatic Phase Pickers: Their Present Use and Future Prospects,
Bull. Seism. Soc. Am., v. 72, pp S225-S242, 1982.

Module Index | Pick_ew Overview | Picker Tuning

Contact:
Questions? Issues? Subscribe to the Earthworm Google Groups List.