On startup, eqcoda reads the configuration file named on the command-line. Commands in this file set up all parameters used in extrapolating coda durations. In the control file, lines may begin with a valid eqcoda 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: @model.d).
Below are the commands recognized by eqcoda, grouped by the function they
influence. Some of the commands are marked "required"; they describe the
Earthworm system setup. These commands must be specified in the control
file in order for eqcoda 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. Default values
and the values used by Calnet are listed after each command description.
If the StaFile command is omitted, eqcoda will use
the original global defaults (appropriate for 12-bit Earthworm analog data) for
all channels. If a channel is not listed in stationfile, eqcoda will use
the default parameters (appropriate for 12-bit Earthworm
analog data) for that channel. If a channel is listed in
stationfile, but the ClipCount field
is missing, eqcoda will use DefaultClipCount=2048 (also appropriate for 12-bit Earthworm
analog data) for that channel. On startup, eqcoda logs the parameters it will use
for each channel, with an asterisk denoting default values.
Pick_ew reports the first three peaks of the P-wave arrival. Eqcoda computes
the average for its output message. If the first (of 3) P-amplitude
exceeds KlipP1 counts, eqcoda considers it to be clipped. If the second or
third P-amplitude exceed KlipP2, they are considered to be clipped. Eqcoda
excludes any clipped values when calculating the average P-amplitude.
Pick_ew reports coda duration as the time from the P-arrival to the time when the
average absolute
amplitude of a 2-second trace data window reaches CodaTerm counts.
Pick_ew also reports the average absolute amplitudes of up to six
2-second coda windows. Eqcoda finds the slope of the coda decay by performing an
L1 fit to the coda amplitudes, ignoring any coda amplitudes that precede the predicted
S-wave arrival or that exceed that channel's coda clipping (KlipC) threshold.
Eqcoda extrapolates the coda decay to a level of CodaTerm counts,
estimating the coda duration for those picks that pick_ew has
timed-out on (pick_ew waits a maximum of 144 seconds for the coda
to reach the CodaTerm value).
For extrapolated coda lengths to be
consistent with "normally-terminating" (<144 sec) coda lengths
reported by pick_ew, be sure that both modules read the same station file.
For historical perspective, most of eqcoda's code was originally
written to handle 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.
Originally, eqcoda used a set of global constants for all
channels because all data in the system was produced by
the Earthworm digitizer. In Earthworm versions v5.1 and higher, eqcoda
can be configured to use per-channel constants instead of the original
global constants. To set per-channel constants, eqcoda must read
a station list file, the same file that is read by pick_ew. Eqcoda
uses 5 fields: station, component, network, CodaTerm, and ClipCount.
The ClipCount field (added specifically for eqcoda, ignored by pick_ew)
specifies the maximum amplitude (counts zero-to-peak) that can be
expected for each channel. Eqcoda calculates each channel's three
clipping constants by multiplying its ClipCount by the fractions
used in the original definitions (see above).
If the ClipCount field is omitted from the station file, eqcoda
assumes the channel is a standard Earthworm analog channel from a 12-bit
digitizer and it assigns a DefaultClipCount = 2048.
1. EXAMPLE CONFIGURATION FILE
#
# This is eqcoda's parameter file
#
MyModuleId MOD_EQPROC # module id to label logfile with.
# Note: eqcoda 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=log to stderr/stdout only
# 1=log to disk and stderr/stdout
# 2=log to disk only
LabelAsBinder 0 # 0=label phases as generic P and S;
# non-zero = label phases as binder did
LabelVersion 0 # Optional command; default LabelVersion=1
# 0 = write a blank in the version field of the
# summary line of the TYPE_HYP2000ARC msg
# non-zero = use the version number passed from
# eqproc,eqprelim on the summary line.
LogArcMsg 0 # optional set to 1 to log the HYP2000ARC message to the logfile
ForceExtrapolation 0 # optional set to 1 to force extrapolation of the coda computation
# for all picks (not just those truncated or noisy)
# PipeTo sends eqcoda's output to one of these three modules:
# eqverify performs some tests to determine if the event
# is noise or a real earthquake.
# hyp2000_mgr locates event and calculates coda duration mag.
# log_everything debug tool which writes all of eqcoda's
# output to the screen and to a file
# in the EW_PARAMS directory named "junkfile".
#--------------------------------------------------------------
# PipeTo "eqverify eqverify.d"
PipeTo "hyp2000_mgr hyp2000_mgr.d ncal2000.hyp"
# PipeTo "log_everything"
# StaFile loads per-channel parameters (added in v5.1).
# Use same station list as pick_ew. eqcoda uses only the
# SCN, CodaTerm and ClipCount fields and ignores the rest.
#--------------------------------------------------------------
StaFile pick_ew.sta
# Obsolete commands (in v5.1 and higher)
#--------------------------------------------------------------
# Define the coda termination level (counts) and clipping
# levels for all channels. Default values are appropriate for
# Earthworm 12-bit data.
# coda_term 49.14 # same as CodaTerm in pick_ew stationfile
# coda_clip 820
# p_clip1 984
# p_clip2 1148
2. FUNCTIONAL COMMAND LISTING
Earthworm system setup:
MyModuleId required
PipeTo required
Constants:
coda_cutoff obsolete
coda_clip obsolete
p_clip1 obsolete
p_clip2 obsolete
pi.c7 obsolete
StaFile
ForceExtrapolation optional
Output Control:
LabelAsBinder required
LabelVersion
LogArcMsg optional
LogFile required
3. ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 processed by function
coda_cutoff cutoff eqc_config constants
Obsolete in v5.1 and higher
Define default coda termination level (counts). The "coda_cutoff"
and "pi.c7" commands are interchangeable. Coda duration is reported
as the time from the P-arrival to the time when the average absolute
amplitude of a 2-second trace data window reaches cutoff counts.
Eqcoda extrapolates the coda decay to a level of cutoff counts,
estimating the coda duration for those picks that pick_ew has
timed-out on (pick_ew waits a maximum of 144 seconds for the coda
to reach the cutoff value). For extrapolated coda lengths to be
consistent with "normally-terminating" (<144 sec) coda lengths
reported by pick_ew, be sure that both modules are configured
with the same coda-termination value. Traditionally, codas have
been "terminated" when the average absolute amplitude in a 2 second
window reaches 60 mV.
Default: coda_cutoff 49.15
coda_clip klipc eqc_config constants
Obsolete in v5.1 and higher
Define the number of counts KlipC above which a 2-second trace data
window's average absolute amplitude should be considered as clipped.
Clipped values will not be used in coda fitting and extrapolation.
Default: coda_clip 820 Calnet: coda_clip 820
ForceExtrapolation switch eqc_config output
Turns on forcing of extrapolation for all picks if switch is set to 1, default is off.
LabelAsBinder switch eqc_config output
Sets the switch for how phases are labeled in the archive message
that will be sent to the next process. If switch is 0, phases
are labeled as generic P or S. If switch is non-zero, each phase
will be labeled with the phase descriptor attached to that pick by
binder. The table below lists possible phase labels:
------------------------------------------------------
LabelAsBinder Station Archive Line
switch cols. 5-6 cols. 37-38
------------------------------------------------------
0 " P" " S"
non-zero "P ","Pn","Pg" "S ","Sn","Sg"
------------------------------------------------------
Hypoinverse does not use the phase label; it just passes the label
along into its output archive file.
Default: none Calnet: LabelAsBinder 0
LabelVersion switch eqc_config output
Determines whether eqcoda will write a version number on the summary line
of the TYPE_HYP2000ARC message that it outputs. If switch
is 0, the version field will remain blank.
If switch is non-zero, the version number passed from
eqproc or eqprelim will be written into the hypoinverse version field.
Default: LabelVersion 1
LogArcMsg switch eqc_config output
Sets the on-off switch for writing HYP2000ARC messages to the log. If switch
is 0, (the default) then no HYP2000ARC message is written to the log.
Default: 0
LogFile switch eqc_config output
Sets the on-off switch for writing a log file to disk and/or screen. If switch
is 0, no log file will be written, but messages may go to stderr and/or stdout.
If switch is 1, eqcoda will write daily log file(s) called
eqcodaxx.log_ccyymmdd where xx is eqcoda's module id (set with "MyModuleId" command)
and ccyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will
be written in the EW_LOG directory (environment variable). Messages may also go to stderr
and/or stdout. If switch
is 2, the log file will be written, but no messages will go to stderr or stdout.
Default: none
MyModuleId mod_id eqc_config 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: eqcoda 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
p_clip1 klipP1 eqc_config constants
Obsolete in v5.1 and higher
Define the number of counts KlipP1 above which the first P-amplitude
(of 3) reported by pick_ew should be considered to be clipped.
Clipped values will not be used in calculating the average P-amplitude.
Default: p_clip1 984 Calnet: p_clip1 984
p_clip2 klipP2 eqc_config constants
Obsolete in v5.1 and higher
Define the number of counts KlipP2 above which the 2nd and 3rd
P-amplitudes (of 3) reported by pick_ew should be considered to
be clipped. Clipped values will not be used in calculating the
average P-amplitude.
Default: p_clip2 1148 Calnet: p_clip2 1148
pi.c7 cutoff eqc_config constants
Obsolete in v5.1 and higher
The "coda_cutoff" and "pi.c7" commands are interchangeable.
See above description for the "coda_cutoff" command.
Default: coda_cutoff 49.15 Calnet: coda_cutoff 49.15
PipeTo cmdstring eqc_config Earthworm setup
Sets the command to which eqcoda will pipe its output for the next step in
earthquake processing. Eqcoda produces a TYPE_HYP2000ARC message, in the format
of a hypoinverse archive file (with shadow cards), for each event.
One of these modules should be used to process eqcoda's output:
eqverify performs some tests to determine if the event
is noise or a real earthquake.
hyp2000_mgr locates event and calculates coda duration mag
using hypoinverse.
log_everything debug tool which writes all of eqcoda's
output to the screen and to a file in
the EW_PARAMS directory named "junkfile".
Blank spaces are allowed in cmdstring as long as
the entire command is enclosed in double-quotes.
Default: none
Calnet: PipeTo "eqverify eqverify.d"
StaFile stationfile eqc_config constants
Gives the name of the stationfile eqcoda must read to
set per-channel parameters; see pick_ew's station list format for
field descriptions and examples. Eqcoda should read the same station file as pick_ew.
Eqcoda uses only five of the fields of the station file:
Station, Comp, Net (#3,4,5), CodaTerm (#19),
and ClipCount (#23).
The Station, Comp, Net fields identify the Station, Component, and Network
codes of each channel.
The CodaTerm field defines the coda
termination level (counts) for each channel. The ClipCount
field (added specifically for eqcoda, ignored by pick_ew)
specifies the maximum amplitude (counts zero-to-peak) that can be
expected for each channel. Eqcoda calculates clipping thresholds for P-amplitudes (KlipP1, KlipP2)
and coda-window average absolute amplitudes (KlipC) as a fraction
of ClipCount. See Notes on eqcoda's
default values for its constants below for details.
Default: none
Example: StaFile pick_ew.sta
4. NOTES ON EQCODA'S DEFAULT VALUES FOR ITS CONSTANTS
For Allen RTP digitizers, 1 mV = 1.0 counts
For Earthworm digitizers, 1 mV = 0.82 counts
The constants used in eqcoda were originally defined for the RTP data
to be "nice round numbers" of mV input to the digitizer. In eqcoda,
the defaults for these constants have been converted for use with
analog Earthworm data. They still correspond to the same input values;
they just aren't "nice round numbers" any more.
Original constants for Rex Allen RTP data:
KlipC = 1000 count = 0.40 max zero-to-peak amplitude
KlipP1 = 1200 count = 0.48 max zero-to-peak amplitude
KlipP2 = 1400 count = 0.56 max zero-to-peak amplitude
Eqcoda's constants for 12-bit Earthworm data:
KlipC = 820 count
KlipP1 = 984 count
KlipP2 = 1148 count
Contact: Questions? Issues? Subscribe to the Earthworm Google Groups List.