Changes between Version 1 and Version 2 of pick_ew


Ignore:
Timestamp:
05/06/12 08:41:58 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pick_ew

    v1 v2  
    55 
    66== Function == 
     7Picks P-arrivals and makes coda measurements 
    78 
    89== Details == 
     10This is the Earthworm picker. Pick_ew gets real-time data in the form of demultiplexed Earthworm waveform messages (TYPE_TRACEBUF messages). The program picks each channel independently, and produces pick messages, which are sent to an Earthworm transport ring. Pick messages are produced within two seconds of the pick time. Pick_ew also measures the length of the waveform coda following a pick and coda-length messages are also sent to a transport ring. Coda lengths are used by the "eqproc" program to assign a coda magnitude to an event. Pick_ew makes two types of coda measurements: The picker 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, the picker times out, reporting the observed amplitude and a "truncated" coda duration of 144 seconds. For traces with high pre-event noise levels, the picker reports a negative or "noisy" coda duration. In addition to the duration, the picker reports the average absolute amplitudes of up to six pre-determined 2-second trace windows. Pick_ew does not start searching for new picks until the coda calculation is complete. 
     11The pick is released by pick_ew within 3 sec (or whatever the MinCodaTerm value is, most default to 3 seconds), but it doesn't go back to looking for new picks until it reaches the coda termination point.  Pick_ew cannot/will not produce any new picks between the pick time and the coda termination time for the given channel that is in coda determination mode.  
     12 
     13If the coda termination is set to a very small value, that means  the measured coda duration will be longer, and if a new event happens to occur to boost the signal again during this time, pick_ew assumes the energy belongs to the original pick and the coda gets extended.  The longest that pick_ew will sit waiting for the signal to reach the coda termination value is 144 sec, after which the picker releases the  coda message with 6 time/amplitude pairs and leaves it to eqcoda to extrapolate the duration time.  
     14If the data has time gaps, pick_ew can be set up, using configuration parameters, to either interpolate through the gaps or restart itself. For time gaps up to several samples long, it is probably best to interpolate. For longer gaps, it is better to restart. The drawback to interpolating is that the data is somewhat corrupted. The drawback to restarting is that the picker will not start picking again for about one second after a restart. 
     15 
     16Picks times are calculated using an algorithm developed by Rex Allen, in the late 1970's and early 1980's. The algorithm works well for short-period data (frequencies > 1 Hz) and has been tested extensively using data from the Northern California Seismic Network. The program tends to miss picks from teleseismic and volcanic events. S waves are occasionally picked, but most of the picks are first-arrival P waves. If the program is used in regions other than Northern California, pick parameters may need to be modified, or another algorithm may be needed. For more information about the picking algorithm used by pick_ew, see the following articles: 
     17 
     18Allen, R.V., Automatic Earthquake Recognition and Timing From Single Traces, Bull. Seism. Soc. Am. 68, Oct 1978, pp. 1521-1532. 
     19 
     20Allen, R.V., Automatic Phase Pickers: Their Present Use and Future Prospects, Bull. Seism. Soc. Am. 72, Oct 1982, pp. S225-S242. 
     21 
     22In addition, Jim Pechmann of the University of Utah has run extensive tests of the earthworm picker. He has written up some suggested picker parameter changes for use with analog and broadband data streams (see below: Tuning: Suggested Picker Parameter Changes). 
    923 
    1024== Configuration File Commands == 
     25On 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: 
     26{{{ 
     27#  marks the line as a comment (example: # This is a comment). 
     28    
     29@  allows control files to be nested; one control file can be  
     30   accessed from another with the command "@" followed by  
     31   a string representing the path name of the next control file  
     32   (example: @pick_ew.d). 
     33}}} 
     34Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). 
     35 
     36=== EXAMPLE CONFIGURATION FILE === 
     37{{{ 
     38# 
     39#                     Pick_ew's Configuration File 
     40# 
     41MyModId        MOD_PICK_EW     # This instance of pick_ew 
     42StaFile        pick_ew.sta     # File containing station name/pin# info 
     43InRing           WAVE_RING     # Transport ring to find waveform data on, 
     44OutRing          PICK_RING     # Transport ring to write output to, 
     45HeartbeatInt            30     # Heartbeat interval, in seconds, 
     46RestartLength          100     # Number of samples to process for restart 
     47MaxGap                  15     # Maximum gap to interpolate 
     48Debug                    0     # If 1, print debugging message 
     49}}} 
     50 
     51=== FUNCTIONAL COMMAND LISTING === 
     52Below 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. 
     53{{{ 
     54        Earthworm system setup: 
     55                InRing          Shared memory region for input 
     56                OutRing         Shared memory region for output 
     57                MyModId         Module id for pick_ew 
     58                HeartBeatInt    Interval between heartbeats 
     59 
     60        Picking Parameters: 
     61                RestartLength   Number of samples to process for restarts 
     62                MaxGap          Maximum gap (#samples) to interpolate 
     63                StaFile         File containing station names and picking parameters 
     64                NoCoda          Optional to NOT do CODA PROCESSING (experimental) 
     65 
     66        Output Control: 
     67                Debug           Debugging flag 
     68                PickIndexDir    Directory where pick_ew_MMM.ndx files will be written (optional) 
     69}}} 
     70 
     71=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     72In 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. 
     73 
     74The following list is organized by: 
     75 
     76command [argument here] 
     77 
     78Debug flag                              GetConfig               output           
     79Sets 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. 
     80 
     81Default:  none                           
     82Sample:   Debug 0 
     83 HeartBeatInt nsec                      GetConfig               Earthworm setup          
     84Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by pick_ew. 
     85 
     86Default:  none                           
     87Sample:   HeartBeatInt 30 
     88 InRing ring                            GetConfig               Earthworm setup          
     89Tells 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. 
     90 
     91Default:  none                           
     92Sample:   InRing WAVE_RING 
     93 MaxGap maxgap                          GetConfig               output           
     94Sets 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. 
     95 
     96Default:  none 
     97Sample:   MaxGap 10 
     98   
     99 MyModId mod_id                         GetConfig               Earthworm setup          
     100Sets 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). 
     101 
     102Default:  none                           
     103Sample:   MyModId  MOD_PICK_EW 
     104 
     105Sample:   MaxGap 10 
     106 
     107 
     108NoCoda flag                             GetConfig               picking params           
     109 
     110This 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. 
     111Default:  none                           
     112Sample:   NoCoda  1 
     113 
     114 OutRing ring                           GetConfig               Earthworm setup          
     115Tells 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. 
     116 
     117Default:  none                           
     118Sample:   OutRing PICK_RING 
     119 
     120 
     121PickIndexDir dir                                GetConfig               picking params           
     122 
     123This 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. 
     124Default:  none                           
     125Sample:   PickIndexDir  pick_index 
     126 
     127 
     128 RestartLength nrestart                 GetConfig               picking params           
     129Sets 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. 
     130 
     131Default:  none 
     132Sample:   RestartLength 100 
     133   
     134 StaFile name                           GetConfig               picking params           
     135Tells 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. 
     136 
     137Default:  none 
     138Sample:   StaFile "pick_ew.sta" 
     139 
     140=== STATION LIST FORMAT === 
     141By 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. 
     142 
     143A sample portion of a pick_ew station list file appears below.  
     144Note that a comments are preceded by a #. 
     145 
     146{{{ 
     147# 
     148#  This is a sample station list for the pick_ew program. 
     149# 
     150#                                 MinBigZC       RawDataFilt    LtaFilt         DeadSta          PreEvent 
     151# Pick  Pin    Station/      MinSmallZC   MaxMint           StaFilt       RmavFilt           AltCoda 
     152# Flag  Numb   Comp/Net/Loc   Itr1   MinPeakSize  i9  CharFuncFilt  EventThresh          CodaTerm         Erefs   ClipCount 
     153# ----  ----   --------   --------------------------------------------------------------------------------------------- 
     154    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 
     155    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 
     156    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 
     157    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 
     158    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 
     159# end of station file 
     160}}} 
     161 
     162Each line in the station file contains the following 24 fields, separated by white space: 
     163 
     164'''Channel Identification:''' 
     165 
     166 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. 
     167 
     168 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,  
     169if we use two digitizers with 256 channels each, our pin numbers would range from 0 to 511. 
     170 
     171 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. 
     172    
     173 4. Comp: a 3-character string to identify the component of motion recorded by this seismic trace. 
     174    
     175 5. Net: a 2-character string that identifies the network that operates the seismic instrument. 
     176 
     177 6. Loc: a 2-character string that identifies the location code that describes the sensor location. 
     178 
     179'''Event Termination/Evaluation Criteria:''' 
     180 
     181 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. 
     182    
     183 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. 
     184  
     185 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]. 
     186 
     18710. 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. 
     188  
     18911. 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. 
     190  
     19112. 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. 
     192 
     193'''Waveform Filtering Parameters:''' 
     194 
     19513. 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. 
     196 
     19714. CharFuncFilt: (c2 in earlier code) Sets the filter parameter CharFuncFilt that is applied in the calculation of the characteristic function of the waveform data. 
     198  
     19915. 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. 
     200  
     20116. 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. 
     202    
     20317. 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. 
     204    
     20518. RmavFilt: Filter parameter (time constant) used to calculate the running mean of the absolute value of the waveform data. Usually set to 0.9961. 
     206 
     20719. 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. 
     208 
     209'''Coda Termination Parameters:''' 
     210 
     21120. 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. 
     212 
     21321. 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. 
     214    
     21522. 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. 
     216 
     21723. 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. 
     218 
     219'''Optional Parameters:''' 
     220 
     22124. 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.    
     222 
     223=== ADDITIONAL REFERENCES ON THE PICKER ALGORITHM === 
     224Allen, Rex V., Automatic Earthquake Recognition and Timing from Single Traces, Bull. Seism. Soc. Am., v. 68, pp 1521-1532, 1978. 
     225 
     226Allen, Rex, Automatic Phase Pickers:  Their Present Use and Future Prospects, Bull. Seism. Soc. Am., v. 72, pp S225-S242, 1982. 
    11227 
    12228=== Tuning: Suggested Picker Parameter Changes ===