# Earthworm Modules:
Pick_FP Configuration File Commands

(last revised Nov 02, 2012)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Station list format
5. Standalone mode
6. Additional references on the picker algorithm

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:

>     #  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: @pick_FP.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

## 1. EXAMPLE CONFIGURATION 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

## 2. FUNCTIONAL COMMAND LISTING

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)

## 3. 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. 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).

>     Default:  none
>     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

## 4. STATION LIST FORMAT

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 appears below.
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).

## 5. STANDALONE MODE

Pick_FP can operate as a standalone module. Specify a tracebuf file as second command line argument (after the config file name) in order to run the picker on tracebuf data. A running Earthworm stack (i.e. startstop) is not necessary for standalone mode. Picks are written to the standard output.
Standalone mode allows to quickly test picking parameters without having to run a full Earthworm/tankplayer stack.

## 6. ADDITIONAL REFERENCES ON THE PICKER ALGORITHM

    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.

Module Index | Pick_FP Overview