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:
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).# 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).
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.
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.
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.
----------------------------------------------------
Each line in the station file contains the following 23 fields, separated by white space:
Channel Identification:
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
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
Output Control:
Debug Debugging flag
3. ALPHABETIC COMMAND LISTING & 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
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
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
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 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
----------------------------------------------------
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.
Event Termination/Evaluation Criteria:
6. 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.
7. 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.
8. 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].
9. 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.
10. 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.
11. 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:
12. 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.
13. CharFuncFilt (c2 in earlier code) Sets the filter parameter CharFuncFilt that is
applied in the calculation of the characteristic function of the
waveform data.
14. 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.
15. 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.
16. 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.
17. RmavFilt (hard-wired at 5.0 in earlier code) Filter parameter (time constant) used
to calculate the running mean of the absolute value of the waveform data.
18. 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:
19. 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.
20. 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.
21. 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.
22. 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:
23. 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.
Contact: Questions? Issues? Subscribe to the Earthworm List (earthw).