wiki:glass
Last modified 8 years ago Last modified on 05/29/12 13:21:56

Earthworm Module: glass

Contributed by: Carl Johnson, Dave Kragness, Mitch Withers

Function

Carl Johnson's Global Associator. See the overview for the Glass Manual written for Hydra by Dave Kragness. (new in EW v7.0)

Manual

This is meant to be an informal document. As such it is not guaranteed to have been reviewed for things like accuracy, grammar, or spelling. (Take it with a grain of salt for good measure)

Initial Blame: David Kragness, Hydra Development Team

Mitch Withers converted to earthworm documentation with no significant changes from Dave's original word doc. The example configurations are found below though this "overview" does contain configuration advice. Carl Johnson's original edicts for earthworm are modularity and platform independence. Carl decided to focus on the science rather than the code for this module and it is currently hopelessly tied to the microsoft platform. It will not compile on any other.

Overview

Glass is a program designed and developed by Carl Johnson for the USGS NEIC, and is currently maintained by the Hydra development team. It is an earthquake Associator designed for a global(earth) environment. It has been integrated into Hydra, and is now an integral part of the Response Hydra system.

This informal document contains four(4) sections oriented at different individuals

  • The Seismologist/ Network Operator section contains information on tuning Glass for your seismic network.
  • The Hydra Administrator section provides information for the system administrator trying to configure Glass to run in an Hydra/ Earthworm environment.
  • The Programmer section contains information on the architecture of Glass code and notes for anyone looking to maintain/modify Glass.
  • The User section contains minimal information on the interactive use of the Glass GUI displays.

Seismologist/ Network Operator

Glass can be thought of as having four(4) major mechanisms for producing earthquake information (origins and associated phases): Nucleator, Associator, Locator, and Filter. The Nucleator creates new earthquake origins, the Associator associates picks with existing origins, the Locator refines origin hypocenters, and the Filter eliminates origins and origin-pick associations.

The Nucleator

Overview

The Nucleator is the portion of Glass that discovers new origins. The Nucleator is the core Glass technology. It is a method for associating a set of picks into an origin. The Nucleator is pick driven, meaning it is fired up whenever a new pick is introduced into Glass that cannot be associated with an existing origin. The new pick (the keystone pick), along with any other unassociated picks in a time window relative to the keystone, are thrown into the Nucleator together. The Nucleator calculates a number of trial origin depths/times (based on the time of the keystone pick) and iterates through them. For each prospective depth/time, the Nucleator obtains an epicentral distance for the keystone pick. The distance is obtained via a reverse lookup of traveltime tables, based on: 1) the delta between the origin time and keystone pick time, 2) the origin depth, and 3) a seismic phase type of P. Using the epicentral distance and the depth, the Nucleator calculates a linear distance. It uses this distance as the radius of a sphere centered at the location of the keystone pick. It then calculates the circle that is the intersection of the keystone sphere and the depth shell sphere (centered at the center of the earth, and radiating out (6371 depth km). This intersecting circle becomes The Ring. For each OTHER pick, the Nucleator calculates the intersection of that pick's sphere (as determined by depth, origin-pick delta time, and P phase) and The Ring. That intersection can be either one or two points (or zero if there is no intersection). The end result is a set of points (each resembling a potential origin location) scattered across the circumference of the Ring. The Nucleator then iterates through the points and for each point calculates the distance of the nth closest point. It then selects the point with the minimum nth-point-distance as the preferred origin location for that time/depth iteration.

Then, after it's computed the preferred origin location for each depth/time iteration, it compares the results from each location and selects the best one (as determined by nth-point-distance). Then if the resulting preferred (from all iterations for that keystone pick) location results in a sufficiently small nth-point-distance, the Nucleator declares a new origin with the determined parameters.

Parameters Tunable

With the exception of the travel time tables and the station list, all of the tunable parameters for the Nucleator are controlled via the glass_assoc.d configuration file.

There are 6 sets of key tunable parameters in the Nucleator:

  1. Location Points: number of and distance threshold.
  2. Time windows for potential origins and associable picks
  3. Size of the time iterations
  4. Depth iterations
  5. Travel time tables
  6. Station List

Location Points

A line similar to the following:

Cut 9 50

appears in the glass_assoc.d config file. The Cut command takes two arguments: number of location points, and distance threshold. When the Nucleator is evaluating potential origins, it calculates nth-point-distance for each potential origin for each time/depth iteration. The first argument defines n (the number of points), and the second argument defines the distance threshold of acceptable origins. So Cut 9 50.0, would instruct the Nucleator to require 9 points to be within 50km of a perspective origin on The Ring, in order for that origin to be deemed acceptable. Note that the Nucleator counts the central point in the 9, so there are only required to be 8 (n-1) other points within the distance. n in theory controls the number of points required in a proximate distance, but in practice, it can be used to determine the number of P-phases required to associate an origin.

Time Windows

A line similar to the following:

TimeRange -600.0 500.0 -820.0

appears in the glass_assoc.d config file. The Nucleator processing is concerned with 2 time windows. The first time window is processed outside of the Nucleator, and directly determines the inputs to the Nucleator. The first time window defines the unassociated picks that will be sent to the Nucleator as picks that are associable with the current pick. The second time window defines the range of potential origin times that should be used by the Nucleator for constructing trial origins. The TimeRange command takes three arguments: the start and end of the first time window (Pick times), and the start of the second time window (Origin times). For example, if the current pick came from station XYZ at 10:45:00, then the above TimeRange command would cause all unassociated picks between 10:35:00 (10:45:00 - 600) and 10:53:20 (10:45:00 + 500) to be sent to the Nucleator along with the current pick. The command would also instruct the Nucleator to try potential origins between 10:31:20 (10:45:00 - 820) and 10:45:00 (10:45:00 + 0).

Time Iterations

A line similar to the following:

TimeStep 5.0

appears in the glass_assoc.d config file. The Nucleator iterates through a set of trial origin times within the potential origin time window. The time delta between iterations in seconds is defined by the TimeStep command. So if TimeStep is 5.0, then the Nucleator will iterate between origins that are 5 seconds apart. The smaller the TimeStep value, the closer the Nucleator should be to the actual origin time and the more processing iterations that will have to be done, so there is a tradeoff between accuracy and processing effort. There are two factors that affect what the TimeStep value should be set to: residual distance limits and locator ability. Because the Nucleator fixes the origin time and depth, any residuals are distance based. If the TimeStep value is set too high, then it increases the artificial distance residual that may be imposed on an origin because the actual event time lay between two iterative steps. So if an event occurs at time 1232.5, TimeStep is set to 5, and the closest two origin time iterations are 1230.0 and 1235.0, then an artificial time residual of 2.5 seconds is being imposed on the nucleated origin. Because the Nucleator deals only in distance residuals, that 2.5 seconds becomes converted to a distance value. When that residual distance value gets to be too great then the Nucleator will no longer be able to associate the origin. The Nucleator is a tool to associate picks into an Origin, its association is not meant to be the Glass end-all final location answer. Within Glass there is a Locator that will refine solutions after they come out of the Nucleator. So a TimeStep value must be chosen that is not too processing intensive but is also not so wide as to preclude origins based on the artificial residuals between time iterations and actual event time. A TimeStep of 5.0, results in a maximum artificial window of 2.5 seconds, with a maximum P velocity of about 13km/sec, that ends up at a worst case artificial distance residual of 32km. If the distance Cut is set to 50km, this leaves only 18km available for anomalies due to actual vs. theoretical 1-d travel times, and depth iteration intervals.

Depth Iterations

Lines similar to the following:

# Shells
Shell 5.0
Shell 20.0
Shell 60.0
Shell 100.0
Shell 200.0
Shell 400.0
Shell 600.0

appear in the glass_assoc.d config file. Each one of these lines defines a depth iteration. The Nucleator iterates through a set of trial origin depths as defined by the Shell commands. Shells should be defined in order of increasing depth. The depth iteration considerations are similar to the time iteration considerations. The same rules hold true for residuals. With a small number of depth iterations defined, the depth residuals may be quite large, but depth and time tend to be somewhat interchangeable, especially if there are enough picks at a similar origin distance to the keystone pick. This allows depth residual to overflow into time residual and be mitigated by a small enough time iteration. (To the Nucleator, an event at time 1230 and depth 300km, will look a lot like an event at time 1235 and depth 400km). If the Nucleator ends up time/depth shifting an event to make the depth residual small enough to fit, then hopefully the Locator will be capable of re-shifting the event back into place with the use of other phase data.

Travel-time Tables

The Nucleator and the rest of Glass use the Hydra traveltime libraries to access data stored in traveltime tables. At this point Glass uses a special subset of traveltime tables that were generated based on empirical ad-hoc observations regarding the phases being picked by the Hydra picker. The actual traveltime tables used by Glass are defined in the tt_tables.d config file in the Hydra params directory. The individual traveltime files must be generated by a separate program. See Generating Traveltime Tables in the Programmer section of this document, or find a developer to do it for you.

The parameters that control the generation of the Glass specific traveltime tables are defined in a set of files tt_*_Glass.txt in the earthworm CVS tree under src/seismic_processing/glass/run/params/ttt.

Each traveltime table entry contains the following information:

  • Traveltime
  • Depth
  • Distance
  • Take Off Angle
  • Time residual window half-width
  • Horizontal Slowness of the phase (dtdx)
  • Vertical Slowness of the phase (dtdz)
  • Association Strength (Pick Probability Density - not currently used)
  • Location Weight (used by the Glass Locator, not by the Hydra Locator)
  • Mag. Threshold (not currently used)
  • Phase Name

The Nucleator makes use of only P phases from the crust/mantle. The current list includes (Pg, Pb, Pn, p, P, Pdif), and only the Traveltime, Depth, and Distance information. Under the current code, there is probably not much that should/could be altered in the traveltime tables that would affect the Nucleator.

Station List

The Nucleator is fairly sensitive to the affects of noisy stations. If you have stations that consistently generate non-relative picks, you may wish to remove them from the station list. Noisy stations will often generate picks that are ripe for coincidental associations which can corrupt origin parameters, causing false or mislocated earthquakes.

Glass currently uses the list of stations specified in the Glass_data\stalist.hinv file (a list of stations in HypoInverse station list format). The lower the number of Cut points, the more sensitive the Nucleator will be to noise picks. Glass must be restarted in order for station list file changes to take effect. There is no way to adjust the station list on the fly during runtime. Glass will ignore all picks received from channels that are not in the station list

Parameters Untunable

The Nucleator only uses mantle/crust P phases for association. It does not use any other kind including PKP. This is hardwired into the code. This could easily be changed in a later release with potential consequences.

The Associator

Overview

The Associator is the portion of Glass that associates picks with existing origins. The Associator is a simple tool that compares a pick with origins using traveltime tables. The Associator is pick based. For each pick that comes into the Associator, the Associator compares the pick to a list of origins known to it, and matches the pick up with the origin for which it has the best fit (as determined by an affinity statistic). If the affinity statistic is above a certain threshold then the pick is associated with that origin, otherwise it gets passed to the Nucleator where it will attempt to associate it as the keystone pick. The affinity statistic is generated based upon certain origin and origin-pick parameters:

  • Number of phases already associated with the origin;
  • Azimuthal gap between associated P-phases;
  • Residual for the current phase;
  • Distance of the current phase relative to the median distance for the phases already associated with the origin.

At the core of the Associator is the simple task of evaluating the likelihood that a pick associates with an origin as a certain phase. The Associator also runs in a separate fashion, where it reevaluates how all of the relevant picks associate with an origin after that origin has been modified. In this case there are 3 groups of picks (that are time relevant):

  • Picks already assigned to the origin
  • Picks not assigned to any origin
  • Picks assigned to a different origin

For each pick currently assigned to the modified origin, the Associator reevaluates the association in order to recalculate the residuals and re-evaluate the best phase match (sometimes the picks will associate as a slightly different phase pP vs. P or Pg vs. Pb). Here the Associator is acting as a catalyst to the origin refinement process.

For each pick that IS NOT associated with any origin (but is still time relevant), the Associator attempts to associate the pick with the origin. Here, the Associator is acting as a reassociator to associate picks that couldn't originally be assigned because of the poor quality of the initial hypocenter location.

For each pick that is assigned to a DIFFERENT origin, the Associator attempts to associate the pick with the modified origin. The Associator compares the association quality of the pick with its existing origin and the modified origin and if the pick now associates better with the modified origin, it reassigns the pick from its current origin to the modified one. At this point the Associator is tasked with resolving splits that may have occurred due to errors in early estimates of the origin hypocenter. The Associator should be taking picks away from a weaker origin and adding them to a stronger origin, until the stronger origin finally eats the weaker one.

Parameters Tunable

There are three sets of parameters that affect the Associator:

  1. The traveltime tables
  2. The station list
  3. The affinity statistic coefficients

The traveltime tables and station list are currently tunable. The affinity statistic coefficients defined in the traveltime tables are tunable, but the others that are hardcoded within the Glass program are not.

Travel-time Tables

Please see Travel-time Tables under The Nucleator for an overview of the traveltime tables. At this point Glass uses a special subset of traveltime tables that were generated based on empirical ad-hoc observations regarding the phases being picked by the Hydra picker.

In addition to an origin, the Associator requires two sets of inputs in order to perform an association: a traveltime table for the appropriate distance/time, and a pick. If there are no traveltime tables then there are no associations. If there are no traveltime tables for a depth/distance/phase type, then there will be no associations made for that depth/distance/phase type. So associations can be limited by limiting the available traveltime tables. At the very least you want to limit the traveltime tables to the phases that are actually observed by the picker that is generating input to Glass. If the picker doesnÆt pick a phase at a distance, then there shouldn't be a Glass traveltime table entry for that phase at that distance. What to do about phases that periodically appear is a more difficult question. They can either be excluded, or can be included and an attempt can be made to rig the affinity statistic coefficients in order to limit their use to where they will likely be seen. Examples of this problem include PKKP, P'P', ScP.

Station List

The Associator requires two sets of inputs in order to perform an association: a traveltime table for the appropriate distance/time, and a pick. If there are no picks, there will be no associations. So associations can be limited by limiting the available picks. Whether or not to limit legitimate energy picks in order to get better answers out of Glass is a question that's above my position on the seismology scale; however, limiting noisy stations that do not contribute picks that are relative to your end goal is a recommended activity. For example, if you are interested in locating medium to large global earthquakes, then you probably do not want to include stations with faulty electronics, stations with a lot of non-seismic noise (traffic, oceans, ice breaking), or stations that are located close to an active seismic source that constantly releases energy in small magnitudes. Noisy stations will often generate picks that are ripe for coincidental associations. This can corrupt origin parameters, causing false or mislocated earthquakes.

Tunable Affinity Statistics Traveltime Tables

Traveltime tables are generated by a separate program, which is not currently setup for seismologist operation. There are a number of configuration files that are used as input to the traveltime table generation program, that can be edited by a seismologist. These input files currently live in hydra_proj\params\resp\seismic\ttt\glass\*.txt. In these files, a configuration paragraph similar to the following appears for each traveltime table.

Phase	PKKPbc	PKKP
DistRange	 85	 125
DistDelta	 2.5
DepthRange	 0	 800
DepthDelta	 25
TimeDelta	 10
RayParam	 2.0	 4.112
LocWeight	 0.05
ResWinWidth	 15.0

The above paragraph tells the program that generates the traveltime tables to generate one for the phase PKKP, to be named PKKPbc, to generate it over the distance range of 85 to 125 degrees with an entry every 2.5 degrees, for a depth range of 0 to 800 with an entry every 25km; it also tells it to generate a reverse lookup table based on time/depth, with entries every 10 seconds / 25km. It tells it to only use PKKP phases with ray params between 2 and 4.112 (the bc branch but not the ab). The LocWeight entry is not important to the Associator but effects the weight given to this phase by the Glass Locator. The last entry is SIGNIFICANT with respect to the Residual affinity statistic. It tells the Associator to use a 15 second residual window (half-width) for this phase, instead of the default of 10. The residual affinity statistic is calculated based on the ratio of the residual to the allowable residual window.

The generation program will generate a table for each configuration paragraph. Actually two tables get generated: one based on time/depth and one on distance/depth. Each entry in these tables will contain the following information:

  • Traveltime
  • Depth
  • Distance
  • Take Off Angle
  • Time residual window half-width
  • Horizontal Slowness of the phase (dtdx)
  • Vertical Slowness of the phase (dtdz)
  • Association Strength (Pick Probability Density - not currently used)
  • Location Weight (used by the Glass Locator, not by the Hydra Locator)
  • Mag. Threshold (not currently used)
  • Phase Name
Parameters - Untunable

Affinity Statistic

Most of the components of the affinity statistic generated for an origin-pick association are not tunable. The composite affinity statistic is generated via the following equation:

Affinity = Origin.Gap_Affinity * Origin.Number_of_Arrivals_Affinity *
           Pick.Residual_Affinity * P.Distance_Affinity * Pick.PPD_Affinity

Certain components of the affinity statistic can be turned on and off via the OPCALC_fAffinityStatistics variable. (This variable is currently hardcoded and cannot be changed in a config file.)

The component affinity statistics are generated in the following manner

Origin.Gap_Affinity
Value:          Origin.Gap_Affinity = 4 * Bellcurve_Value(Origin.Gap / 360)
Description:	Origin.Gap is the maximum azimuthal gap between P phases
                associated with the origin.  If the number of existing
                associations is too small (currently defined as less than
                OPCALC_nMinStatPickCount = 10), then Origin.Gap_Affinity
                is set to 1.0.
Range:	        Artificially limited to 0.5 û 2.0.  (If the gap is
                EXCRUSIATINGLY BAD (more than 325 degrees) then it is not
                artificially limited.)
Reason:	        Gap is a crude measurement of the quality of the epicentral
                location.  An origin with an azimuthal gap of 90 will generally
                produce a more accurate location than an origin with a gap of
                270, even if the number of phases associated with each origin
                is the same.

Origin.Number_of_Arrivals_Affinity
Value:          Origin.Number_of_Arrivals_Affinity = log10(Origin.NumberOfPhases)
Description:	DescOrigin.NumberOfPhases is the number of phases that were
                used by the Locator to generate the latest hypocenter for this
                Origin.  The affinity value is limited to a minimum of 1.0.
Range:	        Artificially limited to 1.0+ (Under the current NEIC network
                2.5 is the realistic maximum based on 300 phase picks).
Reason:	        The number of arrivals associated with an origin is a crude
                measurement of the magnitude of the quake.  This allows larger
                quakes an improved chance of associating more phases.  This
                aids in preventing splits where larger quakes can associate
                phases even though they have large residuals, and in resolving
                splits where larger origins can steal phases from smaller ones.

Pick.Residual_Affinity
Value:         Pick.Residual_Affinity =
               2 * Bellcurve_Value(Pick.Residual / PhaseResidualWindowWidth)
Description:   Breakeven point is one half the residual window width.  For the
               default 10 second window, a residual of 5 seconds would net a
               Residual_Affinity of 1.
Range:         The range is 0 to 2, with no artificial limits.
Reason:        The residual is the most key requirement in the association of
               a Pick to an Origin.  You cannot associate a Pick as a P phase
               if the pick delta time is not close to the theoretical
               traveltime.  The affinity statistic allows picks that are
               closer to the theoretical traveltime to garner an improved
               affinity.

Pick.Distance_Affinity
Value:         Pick.Distance_Affinity =
               Bellcurve_Value(Pick.Distance/(Median_Distance_Estimate*4))
Description:   Distance based filtering is a decent mechanism for excluding
               coincidental picks that arenÆt generated by energy released by
               a quake.  The distance affinity statistic prevents picks outside
               of four(4) times the median distance from being associated with
               this origin.  The value 4 is hardcoded as OPCALC_dCutoffMultiple.
               The breakeven point is twice the median distance estimate;
               however the median distance estimate is fudged for very small
               earthquakes as well as for some larger ones.  For very small
               earthquakes the median distance is multiplied by 1.5.  For
               certain earthquakes that are located near the heart of the
               network such that the median distance is kept low by the
               non-uniformity of the network (for the NEIC, imagine a M5.0+
               earthquake located anywhere in the contiguous US), the median
               distance is artificially inflated relative to the number of
               phases associated with the origin.  This allows for PKP and
               other associations that would otherwise be disallowed because
               the median distance is only 15 degrees.
Range:         The range is 0 to 2, with no artificial limits.
Reason:        Distance is used as a sanity factor to prevent local or regional
               quakes from associating with coincidental picks across the
               globe, which have no energy from the quake associated with their
               pick, and may corrupt the origin parameters.

Composite Affinity

Because the composite affinity statistic is a product of all the components,
any affinity with a value of 0 automatically nixes the association.  The
residual, dip, and distance affinity components can potentially have a value
of 0.  So an association can be precluded because 1)the residual is too great;
2) the distance is too great; 3) all of the picks are coming from a single
direction(azimuthal gap).



Assuming that none of those components preclude the association, then the
composite affinity for the pick/origin must be above a minimum affinity
threshold in order to be eligible for association.  That threshold value is
hardcoded to 0.9 ( as OPCALC_dAffMinAssocValue).
Note that to allow quakes to properly build, exceptions are made to how
affinity statistics are computed for small earthquakes.  Currently small
quakes are defined as those with less than 10 phases (hardcoded as
OPCALC_nMinStatPickCount).



Two examples:


SNZO BHZ IU 00 reports a pick 329.1 seconds after an existing origin.  The
origin has 138 phases, an azimuthal gap of 54 degrees, and a median distance
of 83 degrees.  54 degrees results in a Gap_Affinity of 2.0.  138 phases
results in a Number_of_Arrivals_Affinity of 2.14.  The theoretical traveltime
for a P phase at SNZOÆs distance and the originÆs depth is 324.9 seconds,
resulting in a residual of 4.25, resulting in a Residual_Affinity of 1.2.
The distance of 24.9 degrees relative to the median distance of 83 results in
a Distance_Affinity of 2.0.  The PPD is fixed at 1.0.  The composite affinity
for this pick relative to the origin is 10.3 (2.0 * 2.14 * 1.2 * 2.0 * 1.0).
It is greater than the minimum affinity requirement of 0.9, so it would be
eligible for assignment to this origin and would very likely be assigned to
it as the affinity is quite high.



MTE BHZ GE --  reports a pick 1223.4 seconds after the same origin
(138 phases, gap of 54 degrees, and median distance of 83 degrees).
54 degrees results in a Gap_Affinity of 2.0.  138 phases results in an
Number_of_Arrivals_Affinity of 2.14.  The theoretical traveltime for a
PKPab phase at MTEÆs distance and the originÆs depth is 1215.0 seconds,
resulting in a residual of 8.4, resulting in a Residual_Affinity of 0.14.
The distance of 155.3 degrees relative to the median distance of 83 results
in a Distance_Affinity of 1.1.  The PPD is fixed at 1.0.  The composite
affinity for this pick relative to the origin is 0.66
(2.0 * 2.14 * 0.14 * 1.1 * 1.0).  Because the affinity is below 0.90, this
pick would not be eligible for assignment to the origin.

Relevant Origin Time Range

In it's primary role of trying to assign a new pick to its most likely origin,
the Associator grabs only the origins that are time relevant to the pick.  The
relevant origin time window relative to the pick time is hard coded.  It
starts 2400 seconds pick (hardcoded as OPCALC_dSecondaryAssociationPrePickTime)
prior to the pick and ends at the time of the pick.

Relevant Pick Time Ranges For An Origin

When the Associator runs in it's alternate scope of reevaluating how all of
the time relevant picks associate with an origin after that origin has been
modified, it uses various time windows.  (this is a bug/feature).

* Picks not assigned to any origin

The Associator uses a pick time range of (Origin_Time - 2400 seconds to
Origin_Time) (2400 seconds is hardcoded as
OPCALC_dSecondaryAssociationPrePickTime)

* Picks assigned to a different origin

The Associator uses a pick time range of (Origin_Time - 2000 seconds to
Origin_Time)  (2000 seconds is hardcoded)

The Locator

Overview
The Locator refines Origin parameters based on a least-squares inversion of
the residual vectors for associated phases.  (or something like that)  The
residual vectors are calculated based on the residual and azimuth from each
pick along with the dtdx(horizontal slowness) and dtdz (vertical slowness)
for the phase association.
Parameters Tunable
The Locator has two tunable parameters: the location weight of each phase
(set in the traveltime tables), and the number of iterations it will run
each time it is invoked.

Location Weight

The Location Weight is set in the traveltime tables.  See Tunable Affinity
Statistics Traveltime Tables under the Associator section for a description
of traveltime table parameters.  Setting !LocWeight to a value will cause the
Locator to apply that weight to picks of that phase.  The default weight
is 1.0.

Number of Iterations

A line similar to the following

NumLocatorIterations 3

Can be placed in the glass_assoc.d config file. This line would cause the
locator to be run for three iterations each time the Locator is invoked.
The default is 1.
Parameters Untunable

The Locator has no untunable parameters.

The Filter

Overview
The Filter is the portion of Glass that eliminates origins or pick-origin
associations because they don't pass certain validity tests.  The Filter
consists of a conglomeration of filters that are split into different portions
of Glass.  They attempt to filter coincident origins and coincident
pick-associations from the Glass output.  The filters can be thought of as
falling into 3 groups:  core, network specific, and output.

Core Filters

The Core filters are very simple.  They ensure that existing origins and
origin/pick associations don't violate the original association requirements.
They are used to remove origins that don't have enough pick associations
because the location has changed or because its picks have been stolen by
another origin.  They are used to remove assigned picks because their affinity
has dropped due to changes in the parameters of the origin.

Validate Origin

A filter will delete an origin if it discovers any of the following 3
conditions:
  
Number of phases associated with the origin dropped below the number
  of points required by the Nucleator to create a new origin.

Number of phases used by the locator to compute the latest hypocenter
  for the origin dropped below the number of points required by the Nucleator
  to create a new origin.
  
Number of P phases associated with the origin drops below (number of
  points required to nucleate - 1).  The -1 is added as a bit of a buffer
  against excessive origin deletion.

Validate Associations

A filter will delete an origin / pick association (unassign the pick from the
origin) if it discovers that the pick / origin affinity drops enough below the
minimum association value to exceed a slop buffer (hardcoded as
(OPCALC_dAffMinAssocValue - OPCALC_dAffinitySlop = 0.9 - 0.5 = 0.4 )  The
substantial slop buffer was added for two reasons:  to prevent association
oscillations for borderline picks (picks with affinity near the minimum
association value); to encourage associated picks to stay associated even if
the locator swings the origin in some direction that is not favorable to the
pick.

Network Specific Filters

Glass contains several origin oriented network specific filters that are
capable of invalidating a given origin.  The key reason for these filters is
to overcome anomalies in network uniformity and density.  In the NEIC Hydra
network, the lion's share of sensors are located in North America, such that
tuning Glass to preclude coincident events in North America would also
preclude many valid medium sized earthquakes in the rest of the world;
tuning Glass to include those medium sized events would also cause many
coincident/noise events in North America to be produced.

The current set of filters defines 5 regions:
 
The Inter-mountain West region (46,-104   -  37.5,-113)

Western hemisphere (85,-140  -  45,-40)
  
Northwest quadrant (85,-170  -  0,-40)
  
North polar region (Lat > 70)
  
Rest of the world

For each of these regions the filter checks for a minimum number of quality
P phases.  The criteria for a quality phase is a residual within 2 seconds
of the predicted arrival time.  In regions 2 - 4, phases from the networks
UU, IW, and MB are not allowed to count towards the minimum requirement.

If the epicenter of the origin falls in regions 1 - 4, then the origin will
be invalidated unless one of the following criteria is met: 

10 quality P phases are associated with the origin. (10 is hardcoded
  as MIN_QLTY_ARR)

4 quality short-range P phases are associated with the origin, where
  short-range is defined as distance less than 10 degrees. (4 is hardcoded
  as MIN_QLTY_CLOSEIN_ARR)

If the epicenter of the origin falls outside regions 1-4 (inside region 5),
then the origin will be invalidated unless there are at least x quality
arrivals, where x = number of points required to nucleate / 2
This is an integral equation, so if number of points is 8 then you need 5,
if 9 then 5, if 10 then 6, in order to avoid invalidation.

Output Filters

Glass contains one final set of filters that do not have a dramatic effect
on the world of Glass, but affect what information that Glass exports to the
outside world.  There are several filters that run in the publishing module
that periodically exports event messages to the rest of Hydra.

Minimum Number of Phases

A filter prevents the publication of origins that have fewer than the minimum
number of associated phases, as defined by the MinNumPhases is the
glass_pub_params.d config file.  Events that don't reach the threshold are not
deleted inside of Glass, but they are never published by Glass to the outside
world.

Ancillary Phases

A filter tries to prevent certain coincidental associations with an origin,
by requiring a minimum number of a certain phase type before phases of that
type are published.  The current hardcoded limit is 3, and S phases closer
than 10 degrees and all P phases are immune to this restriction.  For example,
if there are two PKPab phases (VLC and MTE), and 4 PKPdf phases (MORC, PSZ,
WLF, and CSS) with an origin, then there will be NO PKPab phases published
for that origin, but all 4 of the PKPdf phases will be published.

Pdif Phases

A filter prevents Pdif phases > 110 degrees from being published.  I
don't think there is a GOOD reason for this;  however Pdif phases beyond 110
degrees for the current picker are almost always coincidental associations.

Old Events

A filter prevents quakes older than a threshold number of days from being
published.  A command OldestEventToPublish in the glass_pub_params.d config
file controls the length of the threshold in days.  For example: a quake
occurs on 09/01/05 at 11:00 UTC, and OldestEventToPublish is set to 5.0.
The quake is not picked up until some late arriving data enters the system
on 09/06/05 and 12:00 UTC.  Glass now associates the quake, but does not
publish it because it has been 5.04 days since the origin time, which is
beyond the 5.0 day threshold.

Dead Events

A filter prevents an origin from being published once it is dead.  The
publishing module tracks an origin through its life cycle in Glass, publishing
it over and over again as it changes.  At some point the Publisher deems the
Origin stale and marks it as dead.  This was done with the idea that Glass has
a certain scope of time within which it operates, and at some point in time
Glass should acknowledge that the quake has gone out of time scope for
automatic processing and is being handled further down the processing stream.

Publication Rate

The publication module controls how often glass updates the outside world on
how an origin is progressing.  Publication rate is potentially affected by
both the amount of change an Origin is going through and the amount of time
that has occurred after the origin.  Publication in general is controlled by
the glass_pub_params.d config file, and the controlling parameters are
documented within that file.

Other Stuff

There are several other mechanisms within Glass that affect processing, but do
not affect output to the degree of the major four.  The Depth Refocus module
attempts to discover alternate hypocenter depths that elude the Locator.  The
State Processing orchestrates how origins and picks are processed by Glass.
Depth Refocus
Depth Refocus is a module that searches for an improved origin depth and
time that cannot be discovered by the Locator.  Refocus assumes a correct
epicenter, and does a depth/time grid search for a potentially better
depth/time combination.  Refocus module utilizes all time-relative picks as
input, regardless of their origin assignment status.  It attempts to associate
each pick as either a P or pP phase for the origin at each point in the
time/depth grid.  It was created to get the Locator out of local residual
minima.  Currently there are no tunable parameters in the Focus module.
State Processing
Glass contains a state processing engine that controls how picks and origins
are processed.  The engine is entity oriented where an entity is either a
pick or an origin.  It's operation is configured by Tran commands in the
glass_assoc.d config file.  At this point State Processing configuration is
considered to be an engineering issue and is not meant to be modified by a
seismologist/network operator.

Hydra Administrator

This section to be filled in later with information regarding how to configure
Glass to run in a Hydra/Earthworm near real-time environment.

Configuring Glass

glass.d

Error Reporting

Glass, by default writes 3 levels of status messages:

MAJOR ERROR
  There are 39 Major Errors.  They include things like:
    
Can't open config file.
    
Can't load DLL (Module)
    
Can't allocate memory

Can't load traveltime tables
  
Can't get EW message types
   
Can't  access required module
   
Can't attach to shared memory

Can't create internal messages
    
Can't parse config file command
    
Can't write to temporary files.
  
MAJOR WARNING
  There are 3 Major Warnings
  They are reserved for times when glass gets "CONFUSED" internally.  It
  continues to operate, but wants you to know that you may regret it in the
  morning.

MINOR ERROR
  There are somewhere around 90 Minor Errors.  They cover everything under the
  sun, including Missed Messages, and so forth so on, and are a general catch
  all for stuff that the operator or programmer may want to know about.

To make matters more complicated, while the internal error levels are
hardcoded in the code, the way glass reacts to them (i.e. what glass reports
and how) is completely configurable via the .d files.  So you could (while not
recommend it) configure glass via the .d file, to issue status messages for
each DEBUG/INFO message and not issue them for any of the Major Errors.

From the default glass.d file:

#  DebugLevel commands
#  CatalogDebugLevel | EarthwormDebugLevel | GlassDebugLevel | GlintDebugLevel | LocatorDebugLevel | PublisherDebugLevel
#    Level:  0-9
#           MAJOR_ERROR 0
#           MAJOR_WARNING 1
#           MAJOR_INFO 2
#           MINOR_ERROR 3
#           MINOR_WARNING 4
#           MINOR_INFO 5
#           FUNCTION_TRACE 9
#
#    OTF : OutputToFile
#    OTD : OutputToDebugger
#    OTE : OutputToError
#    OTS : OutputTimeStamp
#    OSM : OutputStatusMessage
#
#  Format:
#  DebugLevel I:Level={0-9} I:OTF={0|1} I:OTD={0|1} I:OTE={0|1} I:OTS={0|1} I:OSM={0|1}
#
#  Default values:  {OTF,OTD,OTE,OTS,OSM}
#  {1,1,1,1,1},  // MAJOR ERROR
#  {1,1,1,1,1},  // MAJOR WARNING
#  {1,1,0,0,0},  // MAJOR INFO
#  {1,1,1,1,1},  // MINOR ERROR
#  {1,1,1,0,0},  // MINOR WARNING
#  {0,0,0,0,0},  // MINOR INFO
#  {0,0,0,0,0}   // FUNCTION TRACE

#
#  Example:
#  EarthwormDebugLevel  I:Level=2 I:OTF=1 I:OTD=0 I:OTE=0 I:OTS=0 I:OSM=0

User

This section to be filled in later with information regarding how to operate
the Glass displays including the ManQuake display for manually testing a
hypothetical hypocenter.

Programmer

This section to be filled in later with information regarding the
architectural layout of Glass, along with notes on how to maintain/modify it.

Configuration File Commands

Example glass.d

 # Directory section  - allows you to select which directory glass will
#  look in for particutlar files.
# DLLs   - directory where glass will look for the Module DLLs specified below
#  This should not be needed if you put the bin directory in your "PATH"
#$ DLLs j:\src\usgs\home\earthworm\v6.2\bin\
$ DLLs e:\ew\v7.0beta\bin\

# DATA   - directory where glass will look for DATA files
$ DATA glass_data\

# Module load section (load all modules before initializing parameters)
mod {DLLs}Network.dll
mod {DLLs}Flinn.dll
mod {DLLs}Earth.dll
mod {DLLs}Glint.dll
mod {DLLs}Glass.dll
mod {DLLs}Glock.dll
mod {DLLs}Solve.dll
mod {DLLs}ManQuake.dll
mod {DLLs}Grok.dll
mod {DLLs}Catalog.dll
mod {DLLs}Earthworm.dll
mod {DLLs}Summary.dll
mod {DLLs}Residuals.dll
mod {DLLs}Refocus.dll
#mod {DLLs}FocusGUI.dll
#mod {DLLs}FocusGUI_DP.dll
mod {DLLs}Publisher.dll


# enables nexus traffic monitor
DISPLAY

# Means: messages go to all modules
BROADCAST

# Processed by nexus.dll
Initialize

DISPATCH
# Turns on glass status window(glass.dll)
GlassMonitor

# associator param file (glass.dll)
GlassParams S:File={DATA}glass_assoc.d

# Hypo station list (network.dll)
HypoLoad S:File={DATA}glass.hinv

# Init file for earth module (tt code) (earth.dll)
TTInit S:File=tt_tables.d

# map base (grok.dll)
World S:Base={DATA}World.bmp

# glass pub params
PubAlgParams S:File={DATA}glass_pub_params.d

# Reporting params (glass.dll)
ReportInterval I:Interval=20

# Earthworm params (earthworm.dll)
RingIn S:Name=PICK_RING
RingOut S:Name=ASSOC_RING
HeartBeat I:Interval=30
ModuleId S:Module=MOD_GLASS_EW
LogFile

# NoFlushInput  - uncomment this line to prevent glass from flushing
#                 the earthworm input RING.  - not recommended
                                               for normal operation
#NoFlushInput


# LOG_PICKS  -  Log picks to the glass_pick_log.txt file in EW_LOG dir.
LOG_PICKS

# LOG_ORIGINS - Log origins to the glass_origin_log.txt file in EW_LOG dir.
LOG_ORIGINS

# SHOW_PICKS -  Display new picks in the Map window (grok.dll)
SHOW_PICKS

# TERMINATE - uncomment this line to have glass terminate immediately after
#             processing the config file.
# TERMINATE


# Flinn Engdahl Regions
FlinnEngdahlLoad S:Dir={DATA}

#  DebugLevel commands
#  CatalogDebugLevel | EarthwormDebugLevel | GlassDebugLevel | GlintDebugLevel | LocatorDebugLevel | PublisherDebugLevel
#    Level:  0-9
#           MAJOR_ERROR 0
#           MAJOR_WARNING 1
#           MAJOR_INFO 2
#           MINOR_ERROR 3
#           MINOR_WARNING 4
#           MINOR_INFO 5
#           FUNCTION_TRACE 9
#
#    OTF : OutputToFile
#    OTD : OutputToDebugger
#    OTE : OutputToError
#    OTS : OutputTimeStamp
#    OSM : OutputStatusMessage
#
#  Format:
#  DebugLevel I:Level={0-9} I:OTF={0|1} I:OTD={0|1} I:OTE={0|1} I:OTS={0|1} I:OSM={0|1}
#
#  Default values:  {OTF,OTD,OTE,OTS,OSM}
#  {1,1,1,1,1},  // MAJOR ERROR
#  {1,1,1,1,1},  // MAJOR WARNING
#  {1,1,0,0,0},  // MAJOR INFO
#  {1,1,1,1,1},  // MINOR ERROR
#  {1,1,1,0,0},  // MINOR WARNING
#  {0,0,0,0,0},  // MINOR INFO
#  {0,0,0,0,0}   // FUNCTION TRACE

#
#  Example:
#  EarthwormDebugLevel  I:Level=2 I:OTF=1 I:OTD=0 I:OTE=0 I:OTS=0 I:OSM=0
EarthwormDebugLevel  I:Level=4 I:OTF=1 I:OTD=1 I:OTE=1 I:OTS=1 I:OSM=1
GlassDebugLevel  I:Level=5 I:OTF=1 I:OTD=1 I:OTE=1 I:OTS=1 I:OSM=1

Example glass_assoc.d

 Cut 9 50.0 # Empirical Params
TimeRange -600.0 500.0 -820.0
TimeStep 5.0

# Shells
Shell	  5.0
Shell	 20.0
Shell	 60.0
Shell	100.0
Shell	200.0
Shell	400.0
Shell	660.0


# Glass State - Transition Rules
Tran	Unassigned_Pick			1	Assign		100
Tran	Unassignable_Pick			1	Associate		100

Tran	Changed_Origin			1	Locate		100
Tran	Origin_w_Changed_Assocs		1	Locate		100
Tran	Located_Origin			1	Prune			100
Tran	Located_Origin			1	Focus			 50
Tran	Located_Origin			1	Waif			100
Tran	Located_Origin			1	Scavenge		100
Tran	Stabilized_Origin			1	Validate_Origin	100
Tran	Validated_Origin			1	Update_GUI		100
Tran	Invalidated_Origin		1	Delete		100
Tran	Deleted_Origin			1	Update_GUI		100

# Uncomment the next lines for more GUI updates / slower performance
#  Not currently supported
#Tran	STATE_PICK_ASSOCIATED	1	Update_GUI		100
#Tran	Unassociable_Pick		1	Update_GUI		100


## Old
#Tran	Assign		0	Associate	100
#Tran	Locate		1	Focus		100
#Tran	Locate		1	Waif		20
#Tran	Locate		1	Prune		100
#Tran	Locate		1	Scavenge	20
##Tran	Focus		1	Locate		100
#Tran	Waif		1	Locate		100
#Tran	Prune		1	Locate		100
#Tran	Scavenge	1	Locate		100
#Tran	Assign		1	Locate		100
#Tran	Associate	1	Locate		100
#Tran	Scavenged	1	Locate		100

Helpful Hints