wiki:pkfilter.designspecs.txt
Last modified 8 years ago Last modified on 03/25/12 16:57:18
Design Requirements for a Pick Filter

1. The purpose of the pick filter is to reduce the number of "duplicate" picks
   from a given "station". For the pick filter, all components which have
   matching station code and network code are considered to be the from the
   same "station". The rules for what are considered "duplicate" picks are
   given below.

2. For each "station", the pick filter will maintain a history list of picks
   that have been allowed through the filter. The size of these lists will be
   limited by a configurable number (count) of picks.
 
   LDD: Added the "PickHistory" command to specify the number (count) of
   picks that will be maintained in the list for each "station".  
   Only picks which pass the filter rules are added to the list. Once 
   the list is full, old picks are removed in a simple first-in, first 
   overwritten manner.

3. The pick filter can optionally be configured to pass picks from only
   certain component codes.
  
   LDD: Added "AllowComponent" command. If no "AllowComponent" command is 
   used, ALL components will be allowed to pass. If one or more "AllowComponent"
   commands are used, the pick filter will only pass picks from the listed
   components.

4. The following rules may be used to determine if a pick is allowed through
   the filter. Any pick that fails these rules is considered a "duplicate" and
   is rejected by the filter.

   A new pick is considered to "match" a pick in the history list if the two
   pick times are within "pick tolerance" of each other. That is, a new pick
   within "pick tolerance" before or after a listed pick is considered to
   match the listed pick.
   
   LDD: Set with original "PickTolerance" command.

   a. A pick that is more than "pick tolerance" newer than the most recent
      listed pick is always passed by the filter.

   b. "Allow higher quality matches": A pick that "matches" a listed pick and
      has a higher quality than that matching pick is optionally passed by the
      filter.

      LDD: Set with original "DuplicateOnQuality" and "QualDiffAllowed" commands.

   c. "Allow older": A pick that is more than "pick tolerance" older than the
      older listed pick is optionally passed by the filter.

      LDD: Added two new commands to control this feature.
      "OlderPickAllowed" has 3 possible values:
        0=pass no non-duplicate picks older than the youngest passed
          pick for this station.
        1=pass older picks, but set a limit on how old they can be.
        2=pass all non-duplicate picks older than the youngest pick
          for this station. 
      "OlderPickLimit" is used only if OlderPickAllowed=1. If a 
       non-duplicate pick is older than they youngest-passed pick by 
       more than OlderPickLimit seconds, the pick will be rejected.  

       I included the "OlderPickLimit" option because I noticed in CI data, 
       that some channels at a station can arrive many minutes later than 
       another channel at the same station.  I assume that this is due to
       recovery on a bad telemetry link.  If we want to keep the pick history
       relatively short and still let older picks thru, we need to set a time 
       limit on the oldest picks we'll accept. Otherwise we could still end up 
       with lots of duplicates in the system.  And if new picks exist, the older
       ones won't really help binder at all.

5. Coda messages can also be filtered by the pick filter. The options should
   include "allow all", "allow none", and "allow matching". Codas are
   considered to match picks for a given "station" if the pick and coda have
   the same serial number, installation and module IDs. The Earthworm picker
   assigns serial numbers to picks and codas; the installation and module IDs
   are part of the "logo" assigned to all Earthworm messages.

   LDD: Added "CodaFilter" command for this feature. 
        It has 3 possible values:
        0=allow no codas
        1=allow matching codas
        2=allow all codas