NCSS Wiki

The NCSS uses a spreadsheet to drive the configuration of its alarm system. The spreadsheet is a format that is easy for seismologists to handle; in CSV format it is a convenient input for scripts. The spreadsheet and scripts for this configuration system are kept /home/u2/ncss/AlarmConfig/.

There are two sheets to the spreadsheet, with meaningful names: Alarm Rules and Regions. The Regions sheet is basically free-form, and provides the latitude and longitude of the various geographic regions used by the alarm rules. Currently the only way to get from the Regions sheet to the alarmdec_regions.cfg is by manual copy. Since the regions change very infrequently, there has been no effort to automate this process.

The Alarm Rules sheet is where the action is. It contains information and comments about all the alarm rules, for both the real-time and post-processing systems. In CSV format, it gets processed by the perl script genAlarmConf. This script expects several conventions to be followed by the Alarm Rules sheet.

• Comment lines in the first column should end with a colon. Since these comments introduce the sections below them, this makes sense to the human reader.

• The first row of should contain a field with the date of the current revision of the rules. This will be used for a comment in each alarm configuration file. For example:

Revised 2018/02/23

• The first row which DOES NOT contain a comment in the first column must contain the names of each column. These column names are used by the script to identify the column contents. Thus the order of spreadsheet columns does not matter.

• Spaces within column names are permitted to improve readability. They will be ignored by the script.

• Empty rows are ignored by the script.

The following columns are required by genAlarmConf:

• Name The alarm name is used within alarmdec to identify the list of criteria. This name is sent to alarmact, where the name is mapped into one or more alarm actions.

• Region The name of a geographic region for which the given alarm rule applies. This region name must be present in alarmdec_regions.cfg file, which is copied by hand from the Regions sheet of this spreadsheet. It is helpful to users if the region name is descriptive.

• Actions The list of one or more actions that are to be performed when an events meets the listed criteria. The action names here MUST match the names of alarm actions. See alarmdist for more info. If more than one action is to be performed for this alarm rule, separate the action names with a plus (+) character, with optional spaces for human readability.

• Alarmdec Module Part of the name of the alarmdec module that is to test events against this list of alarm criteria. The configuration file for this model will have this module name prefixed by alarmdec- and followed by _alarms.cfg. That is, a module name of tm will result in file named alarmdec-tm_alarms.cfg.

The remaining column names are optional, although several of them are used in pairs: if one of a pair is present the other must also be present. These must correspond to the available alarm criteria in alarmdec. The genAlarmConf script does not check this. But you will get an error from alarmdec if you include criteria names it does not understand. For any criteria (or pair) where no value is given in the spreadsheet, that criteria will not be used to evaluate the event; effectively all values are allowed.

• MinDepth, MaxDepth Specify the depth range that the event must have to be accepted by this alarm rule.

• min RecPhases, max RecPhases Specify the range of “number of recording phases. This is the number of phase picks associated with the event origin, even if they were weighted out of the solution.

• min LocRms, max LocRMS Specify the range of values for the origin RMS traveltime residual. This is a measure of location quality.

• min Max Gap, max Max Gap Specify the range of “maximum azimuthal gap”, i.e. the largest gap in azimuth for all stations used in the origin location. A large azimuthal gap may indicate that the event location is outside the NCSS network, so that stations used for the location are only on one side of the event. Origin solutions with large azimuthal gap often under-estimate the distance to the earthquake location.

• ReviewFlags Specify the origin review flags that are acceptable for this alarm rule. Multiple values should be separated by commas, without spaces. Allowed values and their meanings are:
  • A Automatic; no human review
  • H Human Review; i.e. accepted on the DRP page.
  • I Intermediate: event is in the process of being timed using jiggle. The location or magnitude may be intentionally offset to help with event waveform collection. Therefore the event generally should NOT be published in this state.
  • F Final: event has been finalized in jiggle and is ready to be published.
  • C Canceled: a seismologist has reviewed the event and found its location and/or magnitude to be significantly in error, and should not be published in its current state.

• MagTypes Specify the type(s) of magnitude acceptable to this alarm rule. Omit the 'M': an M_d is identified as type d. Separate multiple values with a comma. Allowed values are un,n,a,b,e,l,l1,l2,lg,c,s,w,z,B,d,h, where 'n' means no magnitude.

• min Mag, max Mag Specify the range of magnitude values acceptable to this alarm rule.

• min MagStations, max MagStations Specify the range of number of distinct stations used for the magnitude for this alarm rule.

• min MagRms, max MagRMS Specify the range of magnitude RMS values acceptable to this alarm rule.

• min MagQuality, max MagQuality Specify the range of magnitude quality values acceptable to this alarm rule.

• EventAge Specify the maximum event age, in hours since origin time, for this alarm rule.

• start TimeOfDay, end TimeOfDay Specify the time of day range in hours in minutes (HH:MM) during which the alarm rule can be met. This applies to the clock time of day when the alarm is considered, not to the origin time.

Once the alarm spreadsheet has been approved by seismologists and appropriate management, it should be saved in /home/u2/ncss/AlarmConfig/. Be sure to set the revision date (first row in the spreadsheet) to the correct date. Save the Alarm Rules sheet as a CSV (comma-separated-values) file.

If any existing alarm configuration files are in the above directory, move them aside or they will be overwritten. Note that files with names starting with SAVE should not be removed or renamed: they are not created by the genAlarmConf script.

Run the genAlarmConf script to generate the new configuration files as follows:

genAlarmConf -b bp_comments <CSV FILE>

This command will report any errors it encounters, and a summary of its results. If all goes OK, the complete set of alarmdec rules files as well the alarmact_actions.cfg file will be generated.

In the current alarm spreadsheet, rules files named alarmdec-pp*.cfg are for the post-processing alarm systems; all other alarmdec-*.cfg files are for the real-time alarm systems; and alarmact_actions.cfg is for both real-time and post-processing alarm systems.

All these configuration files should be copied to the /home/ncss/run/params directories on the appropriate systems. Then alarmact and each of the alarmdec programs should be restarted.