Changes between Version 2 and Version 3 of pick_ew


Ignore:
Timestamp:
05/06/12 09:33:01 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pick_ew

    v2 v3  
    99== Details == 
    1010This 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. 
    11 The 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.  
     11 
     12The 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.  
    1213 
    1314If 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.  
     
    7677command [argument here] 
    7778 
    78 Debug flag                              GetConfig               output           
     79'''Debug [flag]'''[[BR]] 
     80Processed by: !GetConfig[[BR]] 
     81Function: output 
     82 
    7983Sets 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  
     84{{{ 
    8185Default:  none                           
    8286Sample:   Debug 0 
    83  HeartBeatInt nsec                      GetConfig               Earthworm setup          
     87}}} 
     88 
     89'''!HeartBeatInt [nsec]'''[[BR]] 
     90Processed by: !GetConfig[[BR]] 
     91Function: Earthworm setup 
     92 
    8493Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by pick_ew. 
    85  
     94{{{ 
    8695Default:  none                           
    8796Sample:   HeartBeatInt 30 
    88  InRing ring                            GetConfig               Earthworm setup          
     97}}} 
     98 
     99'''!InRing [ring]'''[[BR]] 
     100Processed by: !GetConfig[[BR]] 
     101Function: Earthworm setup 
     102 
    89103Tells 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  
     104{{{ 
    91105Default:  none                           
    92106Sample:   InRing WAVE_RING 
    93  MaxGap maxgap                          GetConfig               output           
     107}}} 
     108 
     109'''!MaxGap [maxgap]'''[[BR]] 
     110Processed by: !GetConfig[[BR]] 
     111Function: output 
     112 
    94113Sets 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  
     114{{{ 
    96115Default:  none 
    97116Sample:   MaxGap 10 
    98    
    99  MyModId mod_id                         GetConfig               Earthworm setup          
     117}}} 
     118 
     119'''!MyModId [mod_id]'''[[BR]] 
     120Processed by: !GetConfig[[BR]] 
     121Function: Earthworm setup 
     122 
    100123Sets 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  
     124{{{ 
    102125Default:  none                           
    103126Sample:   MyModId  MOD_PICK_EW 
    104127 
    105128Sample:   MaxGap 10 
    106  
    107  
    108 NoCoda flag                             GetConfig               picking params           
     129}}} 
     130 
     131'''!NoCoda [flag]'''[[BR]] 
     132Processed by: GetConfig[[BR]] 
     133Function: picking params 
    109134 
    110135This 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. 
     136{{{ 
    111137Default:  none                           
    112138Sample:   NoCoda  1 
    113  
    114  OutRing ring                           GetConfig               Earthworm setup          
     139}}} 
     140 
     141'''!OutRing [ring]'''[[BR]] 
     142Processed by: !GetConfig[[BR]] 
     143Function: Earthworm setup 
     144 
    115145Tells 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  
     146{{{ 
    117147Default:  none                           
    118148Sample:   OutRing PICK_RING 
    119  
    120  
    121 PickIndexDir dir                                GetConfig               picking params           
     149}}} 
     150 
     151'''!PickIndexDir [dir]'''[[BR]] 
     152Processed by: !GetConfig[[BR]] 
     153Function: picking params 
    122154 
    123155This 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. 
     156{{{ 
    124157Default:  none                           
    125158Sample:   PickIndexDir  pick_index 
    126  
    127  
    128  RestartLength nrestart                 GetConfig               picking params           
    129 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. 
    130  
     159}}} 
     160 
     161'''!RestartLength [nrestart]'''[[BR]] 
     162Processed by: !GetConfig[[BR]] 
     163Function: picking params 
     164 
     165Sets 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. 
     166{{{ 
    131167Default:  none 
    132168Sample:   RestartLength 100 
    133    
    134  StaFile name                           GetConfig               picking params           
     169}}} 
     170 
     171'''!StaFile [name]'''[[BR]] 
     172Processed by: !GetConfig[[BR]] 
     173Function: picking params 
     174 
    135175Tells 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  
     176{{{ 
    137177Default:  none 
    138178Sample:   StaFile "pick_ew.sta" 
     179}}} 
    139180 
    140181=== STATION LIST FORMAT === 
    141 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. 
     182By 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. 
    142183 
    143184A sample portion of a pick_ew station list file appears below.  
     
    166207 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. 
    167208 
    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,  
     209 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,  
    169210if we use two digitizers with 256 channels each, our pin numbers would range from 0 to 511. 
    170211 
     
    177218 6. Loc: a 2-character string that identifies the location code that describes the sensor location. 
    178219 
    179 '''Event Termination/Evaluation Criteria:''' 
     220'''Event Termination/ Evaluation Criteria:''' 
    180221 
    181222 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. 
     
    185226 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]. 
    186227 
    187 10. 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   
    189 11. 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   
    191 12. 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. 
     228 10. 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. 
     229  
     230 11. 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. 
     231  
     232 12. 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. 
    192233 
    193234'''Waveform Filtering Parameters:''' 
    194235 
    195 13. 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  
    197 14. 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   
    199 15. 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   
    201 16. 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     
    203 17. 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     
    205 18. 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  
    207 19. 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. 
     236 13. 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. 
     237 
     238 14. CharFuncFilt: (c2 in earlier code) Sets the filter parameter CharFuncFilt that is applied in the calculation of the characteristic function of the waveform data. 
     239  
     240 15. 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. 
     241  
     242 16. 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. 
     243    
     244 17. 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. 
     245    
     246 18. RmavFilt: Filter parameter (time constant) used to calculate the running mean of the absolute value of the waveform data. Usually set to 0.9961. 
     247 
     248 19. 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. 
    208249 
    209250'''Coda Termination Parameters:''' 
    210251 
    211 20. 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  
    213 21. 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     
    215 22. 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  
    217 23. 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. 
     252 20. 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. 
     253 
     254 21. 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. 
     255    
     256 22. 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. 
     257 
     258 23. 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. 
    218259 
    219260'''Optional Parameters:''' 
    220261 
    221 24. 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.    
     262 24. 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.    
    222263 
    223264=== ADDITIONAL REFERENCES ON THE PICKER ALGORITHM ===