On startup, pick_FP 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_FP 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
# # # Pick_FP's Configuration File # MyModId MOD_PICK_FP # This instance of pick_FP StaFile "pick_FP.sta" # File containing station name/pin# info InRing WAVE_RING # Transport ring to find waveform data on, OutRing PICK_RING # Transport ring to write output to, HeartbeatInt 30 # Heartbeat interval, in seconds, RestartLength 100 # Number of samples to process for restart MaxGap 15 # Maximum gap to interpolate Debug 0 # If 1, print debugging message WeightTable 0.02 0.05 0.50 1.00 # Pick weight table (maximum error in seconds # for weight 0 up to weight 3) # Specify which messages to look at with Getlogo commands. # GetLogo
# The message_type must be either TYPE_TRACEBUF or TYPE_TRACEBUF2. # Use as many GetLogo commands as you need. # If no GetLogo commands are given, pick_FP will look at all # TYPE_TRACEBUF and TYPE_TRACEBUF2 messages in InRing. #----------------------------------------------------------------- GetLogo INST_WILDCARD MOD_WILDCARD TYPE_TRACEBUF2
Below are the commands recognized by pick_FP, 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_FP to operate.
Earthworm system setup: InRing Shared memory region for input OutRing Shared memory region for output MyModId Module id for pick_FP HeartBeatInt Interval between heartbeats Picking Parameters: RestartLength Number of samples to process for restarts MaxGap Maximum gap (#samples) to interpolate StaFile File containing station names and picking parameters Debug Debugging flag PickIndexDir Directory where pick_FP_MMM.ndx files will be written (optional) WeightTable Pick weight table (maximum error in seconds for weight 0 up to weight 3)
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. None of the commands has any default value. The values used by Calnet are listed after each command description.
command arg1 processed by function
Debug flag GetConfig output
Sets a flag to control the volume of debugging information output by pick_FP. If flag is zero, no debug info is written. If flag is non-zero, debug information is written to the logfile and screen.Default: none
Sample: Debug 0
HeartBeatInt nsec GetConfig Earthworm setup
Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by pick_FP.Default: none
Sample: HeartBeatInt 30
InRing ring GetConfig Earthworm setup
Tells pick_FP 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_FP processes all TYPE_TRACEBUF or TYPE_TRACEBUF2 messages that reside on ring, regardless of their installation id or module id.Default: none
Sample: InRing WAVE_RING
MaxGap maxgap GetConfig output
Sets maxgap, the maximum length (in samples) of a data gap which pick_FP will allow without restarting the picking algorithm. When pick_FP 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_FP will drop all active pick and coda calculations for that channel and will enter the "restart" phase (see RestartLength command) of the algorithm.Default: none Sample: MaxGap 10
MyModId mod_id GetConfig 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. If more than one pick_FP is running at the same time, they must be given different module ids! (If 2 pick_FP's are given the same module id, other modules that listen to pick_FP output may report many "missed message" errors).
Sample: MyModId MOD_PICK_FP
Sample: MaxGap 10
OutRing ring GetConfig Earthworm setup
Tells pick_FP 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.Default: none
Sample: OutRing PICK_RING
PickIndexDir dir GetConfig picking params
This allows the pick_FP_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_FP_MMM.ndx files will be written into the params directory as they have always been. For reference, the MMM refers to the module id.Default: none
Sample: PickIndexDir pick_index
RestartLength nrestart GetConfig picking params
Sets nrestart, the number of samples pick_FP 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_FP detects a data gap longer than MaxGap samples in a given channel's data, pick_FP 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.Default: none Sample: RestartLength 100
StaFile name GetConfig picking params
Tells pick_FP 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.Default: none Sample: StaFile "pick_FP.sta"
WeightTable w0 w1 w2 w3 GetConfig picking params
Defines a table for associating picking errors (in seconds) calcuated by the FilterPicker algorithm and pick weights (w0 w1 w2 w3) needed by binder_ew. w0 w1 w2 w3 are expressed in seconds.Default: 0.02 0.05 0.50 1.00 Sample: WeightTable 0.02 0.05 0.50 1.00
By default, pick_FP processes all TYPE_TRACEBUF or TYPE_TRACEBUF2 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_FP's station list file. This file contains one line per input channel. Each line contains 11 required fields used by pick_FP to identify the channel and set all the picking parameters for that channel. Upon retrieving a TYPE_TRACEBUF or TYPE_TRACEBUF2 message from the ring, pick_FP 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_FP won't process that tracebuf message.
A sample portion of a pick_FP station list file
Note that comments are preceded by a #.
# Do not leave any blank lines in this file. # # # Note: use negative values for filterWindow, longTermWindow # and tUpEvent to let the code autoset them. # # threshold1 # Pick Pin Sta/Comp longTermWindow tUpEvent # Flag Numb Net/Loc filterWindow threshold2 # ---- ---- -------- ----------------------------- 1 00 AVG3 C00 IN LF -1 -1 8.6 17.2 -1 1 01 AVG3 C03 IN LF -1 -1 8.6 17.2 -1 1 02 BEL3 C00 IN LF -1 -1 8.6 17.2 -1 1 03 BEL3 C03 IN LF -1 -1 8.6 17.2 -1 1 04 SCL3 C00 IN LF -1 -1 8.6 17.2 -1 1 05 SCL3 C03 IN LF -1 -1 8.6 17.2 -1 1 06 STN3 C00 IN LF -1 -1 8.6 17.2 -1 1 07 STN3 C03 IN LF -1 -1 8.6 17.2 -1 1 08 PGN3 C00 IN LF -1 -1 8.6 17.2 -1 1 09 PGN3 C03 IN LF -1 -1 8.6 17.2 -1 1 10 VDP3 C00 IN LF -1 -1 8.6 17.2 -1 1 11 VDP3 C03 IN LF -1 -1 8.6 17.2 -1 1 12 CMP3 C03 IN -- -1 -1 8.6 17.2 -1----------------------------------------------------
Each line in the station file contains the following 11 fields, separated by white space:Channel Identification:
1. Pick Flag if Pick Flag is 0, pick_FP will not try to pick P-wave arrivals from this trace. If Pick Flag is 1, the trace will be picked. 2. Pin Numb this field is not used by pick_FP, 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, if we use two digitizers with 256 channels each, our pin numbers would range from 0 to 511. 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. 4. Comp a 3-character string to identify the component of motion recorded by this seismic trace. 5. Net a 2-character string that identifies the network that operates the seismic instrument. 6. Loc a 2-character string that identifies the location code that describes the sensor location.Waveform Filtering Parameters:
7. filterWindow (in seconds) determines how far back in time the previous samples are examined. The filter window will be adjusted upwards to be an integer N power of 2 times the sample interval (delta). Then N + 1 "filter bands" are created. For each filter band n = 0,N the data samples are processed through a simple recursive filter backwards from the current sample, and picking statistics and characteristic function are generated. Picks are generated based on the maximum of the characteristic funciton values over all filter bands relative to the threshold values threshold1 and threshold2. If -1, then filterWindow is autoset to 300 * delta. 8. longTermWindow (in seconds) determines: a) a stabilisation delay time after the beginning of data; before this delay time picks will not be generated. b) the decay constant of a simple recursive filter to accumlate/smooth all picking statistics and characteristic functions for all filter bands.Event Evaluation Criteria:
9. threshold1 sets the threshold to trigger a pick event (potential pick). This threshold is reached when the (clipped) characteristic function for any filter band exceeds threshold1. 10. threshold2 sets the threshold to declare a pick (pick will be accepted when tUpEvent is reached). This threshold is reached when the integral of the (clipped) characteristic function for any filter band over the window tUpEvent exceeds threshold2 * tUpEvent (i.e. the average (clipped) characteristic function over tUpEvent is greater than threshold2). 11. tUpEvent determines the maximum time for which the integral of the (clipped) characteristic function is accumlated after threshold1 is reached (pick event triggered), to then check for this integral exceeding threshold2 * tUpEvent (pick declared).
Lomax, A., C. Satriano and M. Vassallo (2012), Automatic picker developments and optimization: FilterPicker - a robust, broadband picker for real-time seismic monitoring and earthquake early-warning, Seism. Res. Lett. , 83, 531-540, doi: 10.1785/gssrl.83.3.531. Vassallo, M., C. Satriano and A. Lomax, (2012), Automatic picker developments and optimization: A strategy for improving the performances of automatic phase pickers, Seism. Res. Lett. , 83, 541-554, doi: 10.1785/gssrl.83.3.541.