Earthworm Quick Review

Programmer’s Guide

Lucky Vidmar

April 22, 2002

 

1. Objective

The objective of the Earthworm5 Quick Review (EQR) is to provide Earthworm with a remote, rapid event review capability. Its intended use is permit a duty seismologist to rapidly respond to a significant event. It was not designed to serve as a routine analysis facility.

Its features include:

            * Requires only browser access to the Internet.

            * Interacts with events via the Earthworm DBMS.

            * Viewing and editing of automatic event parameters.

            * Graphic re-picking.

            * Event relocation and re-insertion into DBMS.

            * Supports both low- and high-bandwidth connections.

            * Supports interlocks for concurrent reviewers.

 

2. System Overview

The EQR system works by allowing the analyst to retrieve an event from the DBMS, modify its parameters, relocate the event, and subsequently decide whether to reinsert the new solution or to delete the event from the DBMS. The system works in two modes: text-based and web-based.

In the text-based mode, the basic editing mechanism is the Hypoinverse Archive File (Arc) format. Retrieved events are written in Arc format on the WWW server’s local disk. The reviewer can then manually edit that file (e.g., with vi or textedit), then use hypoinverse to relocate the event. Finally, the user can re-insert the event into the database.

The web-based review system is also file-based. The system creates a temporary directory into which all available information about the event is retrieved, and which the system uses to relocate and re-insert the event.

The Text-based and Web-based review methods are based on the same suite of library routines. This enables the programmer to efficiently modify the review system, as change to a single routine affects both review methods.

 

 

 

3. Web-based review

 

3A. Configuration File

All programs in the web-based review system use the same configuration file named review_event.d. It has the following format:

 

#

# Configuration file for the review system

#

#

# Database connection parameters

#

DBuser      database_user

DBpassword  database_pwd

DBservice   database_service

Debug

Logfiledir ../log/

#

# NetworkCode: Two letter designation of this seismic network to

# be used in CUBE messages

#

NetworkCode UU

#

# hostname of the machine holding up web pages

#

WebHost     hostname.ext

#

# ReviewSource: One or more entries (max 10) denoting the

# author (Source) of the Origins which are allowed to review.

#

#

ReviewSource 014024021 # Source 1

ReviewSource 014024005 # Source 2

 

#

# Directory where temporary review files are written. This is

# where Arc files, as well as SAC files for each arrival are

# temporarily stored

#

# NOTE: this directory must be under the web's earthworm directory

# because this is where the review applet needs to find the

# SAC files

#

ReviewDir /home/earthworm/web/html/review

#

# WebDir: Web mapping of ReviewDir

#

WebDir                        /earthworm/review

 

####################################

# HYPOINVERSE REVIEW SECTION

####################################

#

# Full path to the hypoinverse program

#

PathToHypoBin           /home/earthworm/working/bin/hyp2000

 

#

# Full path to the hypoinverse directory

#

HypoinverseDir          /home/earthworm/web/params/hyp2000

#

# Name of the hypoinverse configuration file

#

HypoConfig        utah.hyp

 

####################################

# LOCALMAG REVIEW SECTION

####################################

#

# LM_progname: full path to the executable which computes

# local magnitudes (e.g., Pete's localmag)

#

LM_progname /home/earthworm/working/bin/localmag

#

# LM_writeWA_configfile: full path to the configuration file

# for the LM_progname executable which causes it to produce

# SAC files with Wood-Anderson traces.

#

#

LM_writeWA_configfile /home/earthworm/web/params/localmag_writeWA.d

#

# LM_review_configfile: full path to the configuration file

# for the LM_progname executable which causes it to

# recompute the local magnitude given the potentially reviewed

# information in the WA sac headers.

#

LM_review_configfile /home/earthworm/web/params/localmag_review.d

 

#

# LM_outputfile: name of the output file of the LM_progname

# executable. For localmag, this option must be set to the

# value of the filename for the outputFormat option.

#

LM_outputfile LocalMag.output

#

# LM_method: method used for computing the ML magnitude.

# Valid methods are Peak2Peak and Zero2Peak. Zero2Peak method

# uses one amplitude pick from zero to peak. Peak2Peak method

# uses two picks denoting the largest plus-to-minus or

# minus-to-plus swing in the sliding window whose length

# is determined by the value of slideLength in the

# LM_progname's configuration file.

#

# The choice of method is installation-specific, but it must

# be consistent over various modules dealing with local

# magnitude calculations. If LM_configfiles use slideLength

# greater than 0 then then method should be set to Peak2Peak.

LM_method Peak2Peak

#

# MakeLMPreferred: If set, the local magnitude computed,

# if any, will be set as preferred. Otherwise, the coda

# magnitude is preferred

MakeLMPreferred

 

####################################

# SEISGRAM2K APPLET SETUP SECTION

####################################

#

# Name of the file containing Lomax javascript.

# NOTE: It must exist under ReviewDir/lomax

#

#

JavascriptFile          LomaxApplet.js

#

# OPTIONAL: ShowArrivalPicks

# How many of the closest arrival picks will be displayed

# by the Lomax applet. If this option is not specified,

# the multi-channel applet display will not be available.

#

ShowArrivalPicks 20

 

 

 

 

 

 

 

#

# OPTIONAL: ShowAmplitudeStas

# How many of the closest stations with amplitude picks

# will be displayed by the Lomax . If this option is not

# specified, the multi-channel applet display of amplitude

# picks will not be available.

# Note: Both horizontal components for a station will be displayed.

#

ShowAmplitudePicks 6

#

# Output format (platform): sparc or intel

#

SacFormat         sparc

 

####################################

# ALARMS SECTION

####################################

#

# EwParams -- directory where earthworm configuration lives. This is

# needed to acesss earthworm.d and its mappings between names and Ids.

#

EwParams /home/earthworm/runUtah-alarms/params

#

# AlarmRing: name of the ring where alarm processors are waiting

#

AlarmRing ALARM_RING

#

# MyModuleID: name of the module issuing alarms

#

MyModuleID MOD_ALARM

#

# MyInstID: Installation name

#

MyInstID INST_UTAH

 

###################################################

# Waveform display links to show in the format:

# WaveformLinks PROGRAM_NAME DESCRIPTION OPEN_IN_NEW_WINDOW WINDOW_NAME

WaveformLinks "ora2rsec_gif" "60 seconds aligned on pick time" 1 "60 secs"

WaveformLinks "ora2rsec_gif_two" "200 secs aligned on pick time" 1 "200 secs"

 

 

 

 

 

3B. PROGRAMS

The following programs make up the web-based EQR. The source code is located in:

$EW_HOME/$EW_VERSION/src/oracle/apps/src/review/web

The default location for compiled binaries is:

$EW_HOME/web/bin

 

The configuration files must be located in:

$EW_HOME/web/params

 

review EVENTS

Review_event is a cgi program very similar to eqparam2html. When first invoked from getlist, it runs in the GetFromDB mode where creates a review directory for this event under the directory specified by the parameter ReviewDir/tmp. The event’s review directory is named after the event’s database OriginID.

Into the newly created event review directory, review_event writes:

Then, review_event produces HTML to display the parameters of the event, such as location and magnitude, as well as detailed parameters for each arrival and amplitude pick. The resulting page allows the user to:

When first invoked, only the traces with picks are displayed.  If the user clicks on “Retrieve Unpicked” all trace snippets are saved in the review directory and another section is displayed on the page allowing graphical review on unpicked traces.

For each available trace snippet, picked or unpicked, the user is able to invoke the SeisGram2K applet (written by Anthony Lomax) by clicking on the hyperlink over the name of the channel. See Section 4.1.1.1 below for more information on the SeisGram2K applet. If review_event was able to retrieve all three components of a particular channel, then the applet will be given all three. Otherwise, only the current component is shown.

 

SeisGram2K Applet

SeisGram2K is a Java applet written by Anthony Lomax. The applet is invoked by clicking on an HTML link which formats the command line and passes along the name of the SAC file containing the trace and parametric data for a channel. Review_event produces HTML code necessary to invoke the applet. The necessary Java code to run the applet is in the JAR file. Some additional Javascript code needs to be incorporated into the HTML code in order to invoke the applet.

To that end, the review_event.d configuration file parameter JavascriptFile should contain the name of the file with the javascript code. Within the javascript code the name and location of the JAR file must be specified.

SeisGram2K makes web requests to the server to retrieve the SAC file and also to send back to the server the modified pick information. To accomplish this, the parameter WebHost must be set to the name of the web server running the review system, and WebDir must be the top level of the review directory tree as it is mapped by the web server.

In order to support repacking of amplitude picks, the web server makes available to SeisGram2K response information in the files with the extension .pz. SeisGram2K can transfer a trace into Wood-Anderson, automatically generate amplitude picks, and send them back to the server.

After the user is finished repicking a channel using SeisGram2K, the user can send back the updated information. SeisGram2K is passed the name of the CGI program on the review server – retrieve_pick – which updates the event binary file and the SAC files on the server with the new pick information (See section 4.1.6 for more details).

 

Buttons

The web page produced by review_event contains four buttons: Refresh, Cancel, Retrieve Unpicked,and Done. They are implemented as a web-form which invokes the program review_next_action with appropriate arguments.

 

Operating Modes

Review_event operates in several modes:

  1. GetFromDB. Retrieves event information from the database, saves it in the binary event file and SAC files for picked traces, saves the original author of the event in the file Author, and continues in the Refresh mode.
  2. GetUnpicked: Retrieves trace snippets which have no arrival or amplitude picks associated with them, and continues in the Refresh mode.
  3. Override. If the temporary event directory already exists, someone else might be reviewing that event, or the directory was left over from an abnormal termination of the review process. In this mode, the user is told about the conflict and allowed to click on a link which causes the offending directory to be removed. From there on, review_event proceeds as if it were in GetFromDB mode.
  4. Relocate. Invokes the hypoinverse program which must be located in the place specified by the PathToHypoBin parameter. Review_event produces a hypoinverse Arc file and then runs hypoinverse to relocate the event based on the information in the ArcFile, and based on the hypoinverse parameters specified by the HypoConfig parameter. Then, the local magnitude recalculation is performed by executing the localmag program with the configuration file specified by LM_review_configfile. The new local magnitude is given the output of hypoinverse as the new location of the event. The archive file resulting from the relocation is copied over the original ArcFile, converted back into the EWEventInfo structure, reconciled with the output of localmag, and written to the binary event file so that review_event can continue in the Refresh mode.
  5. Refresh. This is the default mode where eqreview reads the binary event file and produces HTML with modifiable event information based on the event file.

 

Review_next_action

review_next_action is an intermediate processing step. It is called from review_event and passed a series of arguments:

 

Cancel

If the user pressed Cancel in review_event, review_next_action removes the temporary review directory for this event and displays HTML explaining this operation to the user. This is the end of the review chain for this event. The local disk has been cleaned up, and no changes to the event were made in the database.

 

Refresh

Clicking Refresh in review_event causes review_next_action to invoke review_event in the Refresh mode.

 

Retrieve Unpicked

Clicking Refresh in review_event causes review_next_action to invoke review_event in the GetUnpicked mode.

 

Done

If the user clicked Done in review_event, review_next_action reads the original binary event file and updates it with the new magnitude and pick information. Then, the user is presented with three buttons allowing the user to chose what to do with the modified event. The buttons are: Relocate, Delete, and Reinsert.

Clicking on Relocate invokes review_event in Relocate mode.

Clicking on Delete or Reinsert invokes the program review_confirm with the appropriate parameters.

 

review_confirm

This is a very simple program which merely puts up HTML to prompt the user to confirm the choice to delete or re-insert the event, made in review_next_action. Review_confirm may be invoked in two modes, Delete or Reinsert. In either case, the user is presented with three buttons: one to cancel the operation, one to continue with the operation without computing and executing the alarms, and the third to confirm the operation and enter the Earthworm Alarms system.

If the user clicks Cancel, review_eventis invoked in the Refresh mode. This shows the user the original page with modifiable event information. From here the user can either continue the review process, or terminate it by clicking Cancel.

If the user clicks on Confirm With Alarms button, the program review_process_alarms is invoked. Otherwise, clicking on Confirm Without Alarms invokes the program review_process_event.

 

Review_process_alarms

This program retrieves the list of alarm rules from the database and applies them against the current event. The user is shown the list of alarms that should be executed given the event’s parameters. The list includes the type of alarm (email, pager) as well as the text of the alarm message which the user can modify by clicking on a link which fires the review_alarms_msg program.

By default, all alarms in the list will be issued unless the user explicitly de-selects any of the alarms. Review_process_alarms writes a binary file which contains the array of alarms to be sent. When the user clicks Continue, the information from the web form is passed to review_process_event.

 

review_process_event

This is where the real work of deleting or inserting the event is done. review_process_event can be invoked in two modes: with or without alarms. There are also two operating types: Insert or Delete.

In the Insert mode, review_process_event reads the binary event file and makes the appropriate API calls to insert the information about the event into the database. Note that the author field of the new Origin is created by prepending the string REV_ to the original author field, saved in the file Author, to signify that this event is being re-inserted into the database after it was reviewed by a human.

In the Delete mode, review_process_event makes the appropriate API calls to delete the event from the database.

If review_process_event was invoked directly by review_confirm (i.e., no alarms mode), it prompts the user for the next course of action. In the Insert mode, it puts up two buttons allowing the user to either Finish or Continue reviewing the current event. In the Delete mode only the Finish button is presented given that the event has just been irretrievably deleted from the database. Clicking on either button will invoke the review_finish program.

If review_process_event was invoked by review_process_alarms, it will read the binary file containing the list of alarms, reconcile that list with the information retrieved by the web server (possibly canceling one of more alarms, as well as modifying the text of alarm messages) and execute all alarms in the reconciled list. If there are any alarms of the type Phone, review_process_event will produce a web form containing all Phone alarms allowing the user to check-off after each phone call has been made. Finally, the Finish and Continue buttons are presented as described above.

 

Review_finish

Review_finish is invoked by review_process_event which passes to it a list, possibly empty, of Phone alarms issued, as well as the next desired action. If there are any Phone alarms to be updated, review_finish updates the audit entries for those alarms.

When invoked in Continue mode, review_finish calls review_event in the Refresh mode, allowing the user to continue reviewing the event once it has already been updated in the database and all relevant alarms have been sent.

When invoked in Finish mode, review_finish deletes the temporary review directory and informs the user that the review process is completed.

 

Review_alarms_msg

This program is called either from review_process_alarms or review_process_event. It opens a new browser window allowing the user to modify the automatically generated text of the alarm message. If the user clicks the Submit button, the program review_update_alarms_msg is invoked.

 

Review_update_alarms_msg

Invoked by review_alarms_msg, it replaces the automatically generated text of the alarm message with the text supplied by the user through the web-server.

 

RETRIEVE_PICK

This program is called by the SeisGram2K applet in order to send the modified pick information back to the server. retrieve_pick reads from standard input a single line formatted in the modified NON_LIN_LOC format. The input contains the information about the picks that the user defined for the given channel of data.

After the input line is parsed, retrieve_pick updates the information in the appropriate SAC file associated with that channel, and also in binary event file. If an amplitude pick is retrieved, then Wood-Anderson SAC file is updated. Otherwise, the SAC file containing the trace in counts in over-written.

 

Review_get_alarms

Opens a new browser window in which all alarms that have been issued for an event are displayed. Review_get_alarms displays the type of alarm (e.g., email, pager), the recipient’s address or phone number, as well as the time when the alarm was issued and the time when the alarm was executed. The Declaration Time corresponds with the time that review_process_event executed the alarms. The Execution Time is the time that the alarm was picked up by the appropriate processing module and actually executed.

See the Alarms Programmers Guide for more information.

 

4. text-based review

 

configuration and Directory Structure

Text-based EQR needs a single configuration file with the following parameters:

 

 

# configuration file for text based event review

 

#

# Database connection parameters

#

#

DBuser p3_main

DBpassword main

DBservice eqsg.usgs

#

# Logfiledir - where log files are written

#

Logfiledir ./log/

#

# Debug (OPTIONAL)

#

Debug 1

#

# ArcFileName: Full path to the name of the Hypoinverse ARC file

# in which the event info is written

#

ArcFileName /tmp/ArcFile

 

Besides the typical Earthworm% directory structure, no further special directories are needed, except for the directory where the ArcFileName file is located. Note that the directory where the Arc file will be written must exist and must be writeable to the user operating EQR.

 

Commands

The following programs make up the text-based EQR. The source code is located in:

$EW_HOME/$EW_VERSION/src/oracle/apps/src/review/text

The default location for compiled binaries is:

$EW_HOME/$EW_VERSION/bin

 

 

db2file

db2file retrieves an event from the database and writes it to the local disk in the hypoinverse archive format in the file specified by the ArcFileName parameter.

Usage:

db2file configuration_file event_id

 

delete_event

delete_event deletes the event from the database.

Usage:

delete_event configuration_file event_id

 

file2db

file2db inserts the information about the event described by the hypoinverse archive file arc_file into the database. Note that the event_id of the event to be inserted should be in the Arc file.

 

Usage:

file2db configuration_file arc_file

 

typical review sequence

To review the event with event_id 1001, using the parameters in the configuration file text_review.d above:

# db2file text_review.d 1001 (retrieve event information)

# vi /tmp/ArcFile (edit the pick parameters)

# hyp2000 (run hypoinverse to relocate the event)

# ls hypo.arc (output Arc file from hypoinverse)

# file2db text_review.d hypo.arc (insert event info into DBMS)

Questions? Issues? Subscribe to the Earthworm List (earthw).