wiki:eqcoda

Version 4 (modified by branden, 8 years ago) (diff)

--

Earthworm Module: eqcoda

Contributed by:

Function

Performs coda calculations (part of mega-module)

Details

Eqcoda is a sub-module in Earthworm's event-processing mega-module. It processes the event messages output by either eqproc or eqprelim, and writes its own output in a format that can be read by either eqverify or hyp2000_mgr. Eqcoda is often the third link in the mega-module, started by eqbuf. It could, however, be started directly by eqprelim or eqproc. Eqcoda in turn starts the next link specified in its "PipeTo" command (generally eqverify) and communicates to the next link via a one-directional pipe.

Once the next link is started, eqcoda's job is to read the TYPE_EVENT2K messages produced by either eqprelim or eqproc, perform some coda envelope calculations, build a TYPE_HYP2000ARC message, and pass it on to the next link in the mega-module. Eqcoda passes all message types other than TYPE_EVENT2K directly to the next link without modifying them in any way.

Eqcoda's calculations produce a coda duration and coda weight for each arrival in the event. These numbers will be used by hypoinverse to calculate duration magnitude. Eqcoda considers binder_ew's event location and pick_ew's coda amplitude and duration information in its calculations. Pick_ew reports the 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 "cutoff" digital counts, where "cutoff" is specified for each channel in the station file (for the Northern California Seismic Network, this cutoff value is defined as the counts equivalent to a discriminator output of 60 mV). Pick_ew reports a "normal" coda if the amplitude decays to "cutoff" in less than 144 seconds after the P-wave arrival. If the coda does not decay to "cutoff" within 144 seconds, pick_ew times out, reporting the observed amplitude and a "truncated" coda duration of 144 seconds. For traces with high pre-event noise levels, pick_ew reports a negative or "noisy" coda duration. In addition to the coda duration, pick_ew reports the average absolute amplitudes (in digital counts) of up to six pre-determined 2-second trace windows.

Eqcoda finds the rate of the coda decay by performing an L1 fit to the coda amplitudes reported by pick_ew. Any coda amplitudes that precede the predicted S-wave arrival time or that exceed the coda clipping threshold are not included in this L1 fit. Eqcoda arrives at a quality or "coda weight" for this seismogram by comparing the calculated decay rate to the rate expected for real earthquake signals and by analyzing the quality of the fit to the observed data.

For "normal" codas, eqcoda reports the coda duration observed by pick_ew. For "truncated" and "noisy" codas, eqcoda reports an extrapolated coda duration, using the calculated coda decay rate to estimate the time at which the signal's amplitude would have reached the coda cutoff level. For extrapolated coda lengths to be consistent with "normal" coda lengths reported by pick_ew, be sure that both eqcoda and pick_ew read the same station file.

Configuration File Commands

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:

#  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 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

FUNCTIONAL COMMAND LISTING

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.

	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

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_cutoff [cutoff]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: output

Turns on forcing of extrapolation for all picks if switch is set to 1, default is off.

LabelAsBinder [switch]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_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: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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]
Processed by: eqc_config
Function: 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.

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.

Default:  none
Example:  StaFile pick_ew.sta

NOTES ON EQCODA'S DEFAULT VALUES FOR ITS CONSTANTS

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.

   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

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.

Helpful Hints