Changes between Version 2 and Version 3 of eqcoda


Ignore:
Timestamp:
05/28/12 07:58:03 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • eqcoda

    v2 v3  
    1919 
    2020== Configuration File Commands == 
     21On 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: 
     22{{{ 
     23#  marks the line as a comment (example: # This is a comment). 
     24 
     25@  allows control files to be nested; one control file can be 
     26   accessed from another with the command "@" followed by 
     27   a string representing the path name of the next control file 
     28   (example: @model.d). 
     29}}} 
     30Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). 
     31 
     32=== EXAMPLE CONFIGURATION FILE === 
     33{{{ 
     34 # 
     35# This is eqcoda's parameter file 
     36# 
     37MyModuleId  MOD_EQPROC  # module id to label logfile  with. 
     38                        # Note: eqcoda is part of a mega-module which is 
     39                        # ultimately started by the program eqproc.  All 
     40                        # child processes of this mega-module need to use the 
     41                        # same module id (thus use eqproc's module id). 
     42 
     43LogFile       1         # 0=log to stderr/stdout only 
     44                        # 1=log to disk and stderr/stdout 
     45                        # 2=log to disk only 
     46 
     47LabelAsBinder 0         # 0=label phases as generic P and S; 
     48                        # non-zero = label phases as binder did 
     49 
     50LabelVersion  0         # Optional command; default LabelVersion=1 
     51                        # 0 = write a blank in the version field of the 
     52                        #   summary line of the TYPE_HYP2000ARC msg 
     53                        # non-zero = use the version number passed from 
     54                        #   eqproc,eqprelim on the summary line. 
     55 
     56LogArcMsg      0        # optional set to 1 to log the HYP2000ARC message to the logfile 
     57ForceExtrapolation 0    # optional set to 1 to force extrapolation of the coda computation 
     58                        # for all picks (not just those truncated or noisy) 
     59 
     60# PipeTo sends eqcoda's output to one of these three modules: 
     61#   eqverify        performs some tests to determine if the event 
     62#                   is noise or a real earthquake. 
     63#   hyp2000_mgr     locates event and calculates coda duration mag. 
     64#   log_everything  debug tool which writes all of eqcoda's 
     65#                   output to the screen and to a file 
     66#                   in the EW_PARAMS directory named "junkfile". 
     67#-------------------------------------------------------------- 
     68# PipeTo "eqverify eqverify.d" 
     69PipeTo "hyp2000_mgr hyp2000_mgr.d ncal2000.hyp" 
     70# PipeTo "log_everything" 
     71 
     72 
     73# StaFile loads per-channel parameters (added in v5.1). 
     74# Use same station list as pick_ew.  eqcoda uses only the 
     75# SCN, CodaTerm and ClipCount fields and ignores the rest. 
     76#-------------------------------------------------------------- 
     77StaFile   pick_ew.sta 
     78 
     79 
     80# Obsolete commands (in v5.1 and higher) 
     81#-------------------------------------------------------------- 
     82# Define the coda termination level (counts) and clipping 
     83# levels for all channels.  Default values are appropriate for 
     84# Earthworm 12-bit data. 
     85# coda_term     49.14   # same as CodaTerm in pick_ew stationfile 
     86# coda_clip       820 
     87# p_clip1         984 
     88# p_clip2        1148 
     89}}} 
     90 
     91=== FUNCTIONAL COMMAND LISTING === 
     92 
     93Below 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. 
     94{{{ 
     95        Earthworm system setup: 
     96                MyModuleId      required 
     97                PipeTo          required 
     98 
     99        Constants: 
     100                coda_cutoff     obsolete 
     101                coda_clip       obsolete 
     102                p_clip1         obsolete 
     103                p_clip2         obsolete 
     104                pi.c7           obsolete 
     105                StaFile 
     106                ForceExtrapolation      optional 
     107 
     108        Output Control: 
     109                LabelAsBinder   required 
     110                LabelVersion 
     111                LogArcMsg       optional 
     112                LogFile         required 
     113}}} 
     114 
     115 
     116=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     117 
     118In 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. 
     119 
     120The following list is organized by: 
     121 
     122command [argument here] 
     123 
     124'''coda_cutoff [cutoff]'''[[BR]] 
     125Processed by: eqc_config[[BR]] 
     126Function: constants 
     127 
     128Obsolete in v5.1 and higher 
     129 
     130Define 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. 
     131{{{ 
     132Default:  coda_cutoff 49.15 
     133}}} 
     134 
     135'''coda_clip [klipc]'''[[BR]] 
     136Processed by: eqc_config[[BR]] 
     137Function: constants 
     138 
     139Obsolete in v5.1 and higher 
     140 
     141Define 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. 
     142{{{ 
     143Default:  coda_clip 820                 Calnet:  coda_clip 820 
     144}}} 
     145 
     146'''!ForceExtrapolation [switch]'''[[BR]] 
     147Processed by: eqc_config[[BR]] 
     148Function: output 
     149 
     150Turns on forcing of extrapolation for all picks if switch is set to 1, default is off. 
     151 
     152'''!LabelAsBinder [switch]'''[[BR]] 
     153Processed by: eqc_config[[BR]] 
     154Function: output 
     155 
     156Sets 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: 
     157{{{ 
     158   ------------------------------------------------------ 
     159     LabelAsBinder        Station Archive Line 
     160        switch        cols. 5-6         cols. 37-38 
     161   ------------------------------------------------------ 
     162          0           " P"              " S" 
     163       non-zero       "P ","Pn","Pg"    "S ","Sn","Sg" 
     164   ------------------------------------------------------ 
     165}}} 
     166 
     167Hypoinverse does not use the phase label; it just passes the label along into its output archive file. 
     168{{{ 
     169Default:  none                          Calnet:  LabelAsBinder 0 
     170}}} 
     171 
     172!LabelVersion [switch] 
     173Processed by: eqc_config 
     174Function: output 
     175 
     176Determines 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. 
     177{{{ 
     178Default:  LabelVersion 1 
     179}}} 
     180 
     181'''!LogArcMsg [switch]'''[[BR]] 
     182Processed by: eqc_config[[BR]] 
     183Function: output 
     184 
     185Sets 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. 
     186{{{ 
     187Default:  0 
     188}}} 
     189 
     190'''!LogFile [switch]'''[[BR]] 
     191Processed by: eqc_config[[BR]] 
     192Function: output 
     193 
     194Sets 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. 
     195{{{ 
     196Default:  none 
     197}}} 
     198 
     199'''!MyModuleId [mod_id]'''[[BR]] 
     200Processed by: eqc_config[[BR]] 
     201Function; Earthworm setup 
     202 
     203Sets 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. 
     204 
     205NOTE: 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. 
     206{{{ 
     207Default:  none                          Calnet:  MyModuleId MOD_EQPROC 
     208}}} 
     209 
     210'''p_clip1 [klipP1]'''[[BR]] 
     211Processed by: eqc_config[[BR]] 
     212Function: constants 
     213 
     214Obsolete in v5.1 and higher 
     215 
     216Define 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. 
     217{{{ 
     218Default:  p_clip1 984                   Calnet:  p_clip1 984 
     219}}} 
     220 
     221'''p_clip2 [klipP2]'''[[BR]] 
     222Processed by: eqc_config[[BR]] 
     223Function: constants 
     224 
     225Obsolete in v5.1 and higher 
     226 
     227Define 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. 
     228{{{ 
     229Default:  p_clip2 1148                  Calnet:  p_clip2 1148 
     230}}} 
     231 
     232'''pi.c7 [cutoff]'''[[BR]] 
     233Processed by: eqc_config[[BR]] 
     234Function: constants 
     235 
     236Obsolete in v5.1 and higher 
     237 
     238The "coda_cutoff" and "pi.c7" commands are interchangeable. See above description for the "coda_cutoff" command. 
     239{{{ 
     240Default:  coda_cutoff 49.15             Calnet:  coda_cutoff 49.15 
     241}}} 
     242 
     243'''!PipeTo [cmdstring]'''[[BR]] 
     244Processed by: eqc_config[[BR]] 
     245Function: Earthworm setup 
     246 
     247Sets 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: 
     248{{{ 
     249  eqverify        performs some tests to determine if the event 
     250                  is noise or a real earthquake. 
     251 
     252  hyp2000_mgr     locates event and calculates coda duration mag 
     253                  using hypoinverse. 
     254 
     255  log_everything  debug tool which writes all of eqcoda's 
     256                  output to the screen and to a file in 
     257                  the EW_PARAMS directory named "junkfile". 
     258}}} 
     259 
     260Blank spaces are allowed in cmdstring as long as the entire command is enclosed in double-quotes. 
     261{{{ 
     262Default:  none 
     263Calnet:   PipeTo "eqverify eqverify.d" 
     264}}} 
     265 
     266'''!StaFile [stationfile]'''[[BR]] 
     267Processed by: eqc_config[[BR]] 
     268Function: constants 
     269 
     270Gives 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. 
     271 
     272If 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. 
     273 
     274Pick_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. 
     275 
     276Pick_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). 
     277 
     278For 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. 
     279 
     280{{{ 
     281Default:  none 
     282Example:  StaFile pick_ew.sta 
     283}}} 
     284 
     285=== NOTES ON EQCODA'S DEFAULT VALUES FOR ITS CONSTANTS === 
     286 
     287For 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. 
     288{{{ 
     289   For Allen RTP digitizers,  1 mV = 1.0  counts 
     290   For Earthworm digitizers,  1 mV = 0.82 counts 
     291}}} 
     292 
     293The 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. 
     294{{{ 
     295   Original constants for Rex Allen RTP data: 
     296    KlipC  = 1000 count = 0.40 max zero-to-peak amplitude 
     297    KlipP1 = 1200 count = 0.48 max zero-to-peak amplitude 
     298    KlipP2 = 1400 count = 0.56 max zero-to-peak amplitude 
     299 
     300   Eqcoda's constants for 12-bit Earthworm data: 
     301    KlipC  =  820 count 
     302    KlipP1 =  984 count 
     303    KlipP2 = 1148 count 
     304}}} 
     305Originally, 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. 
    21306 
    22307== Helpful Hints ==