# 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