Earthworm Urban Hazards Project

User's Guide

Lucky Vidmar

Barbara Bogaert

April 15, 2002

OBJECTIVE

The objective of the Earthworm Urban Hazards Project ("UH") is to support experimental deployments by the Urban Hazards Project at the USGS, Golden, CO. These experiments consist of deploying K2s in the field and periodically collecting .evt files from them. The desire is to associate the triggers from the .evt files with events from a known catalog.

Once the entire experiment is completed and all triggers associated, the data set should be made available to the scientific and engineering community for downloading over the internet.

To support these requirements, the UH project consists of two main prongs, explained in detail below:

- Processing - load the catalog, station and response information into the database; associate the .evt files with the events in the database.
- Web - allow users to download associated waveform data from the internet, both as raw counts and transformed into ground motion.

The major software components of UH are the same as those required for Quick Review:

* The Oracle DBMS containing event parameters and event trace data.

* Webserver programs which manipulate the data and provide a user interface.

* The SeisGram2K applet (by Anthony Lomax), which allows visualization of the data.

The source code and example configuration files can be found under:

EW_VERSION/src/oracle/apps/src/urban_hazards:

- process - processing tools
- web - web tools
- scripts - helpful scripts

PROCESSING TOOLS

The processing stream of the UH Project consists of several tools, each performing a specific task. They should be run in the following order:

- stalist_maker - reads .evt files and creates a station list file from the information gathered from the EVT headers.
- stalist_loader - loads the information from a station list file into the database.
- cnsscat2ora - loads the information from a CNSS format catalog file into the database.
- evtK2ora - reads .evt files and attempts to associate them with the events in the database. If an association is made, it saves the trace data from the .evt file into the database.

Note on the Directory Structure

The processing flow is intended to move .evt files from the source directory into the target directory whenever an .evt file is processed without errors. If an error is encountered, the offending .evt file is moved into the error directory. Therefore, the tools that read .evt files require the entire set of trigger files to be in one directory. Unfortunately, this is not how they are typically stored after an Urban Hazards experiment. In the typical case, the .evt files are stored in directories containing many subdirectories where the .evt files are not necessarily named uniquely.

To remedy this discrepancy and to provide a helpful workaround, we provide a set of scripts for both NT and Solaris that will process the typical experiment directory and create a single, consolidated directory of .evt files suitable for ingestion by the UH processing tools.

On Windows NT

This procedure requires the Cygwin Unix emulation software to be installed as c:\cygwin. This package is a required standard since Earthworm6. The consolidation scripts should be installed under the cygwin tree:

- copy ...\apps\src\urban_hazards\scripts\consolidate_evts_nt c:\cygwin\bin\ew
- copy ...\apps\src\urban_hazards\scripts\get_evts_nt c:\cygwin\bin\ew

Suppose that we have an experiment directory called c:\ExperimentXYZ, under which there are many subdirectories containing .evt files from multiple visits to all stations in the experiment. To create a consolidated directory called h:\XYZConsolidated:

- mkdir h:\XYZConsolidated
- cd c:\XYZExperiment
- c:\cywin\bin\tcsh -c 'consolidate_evts_nt /cygdrive/h/XYZConsolidated'

This procedure will create an output file c:\consolidate_evt_output which can be used as a mapping from the original location of an .evt file to its consolidated counterpart. The file is found one level above c:\XYZExperiment.

On Solaris

Analogous to the NT approach:

- cd /home/XYZExperiment
- mkdir ../XYZConsolidated
- consolidate_evts_sol ../XYZConsolidated

Configuration

As with all Earthworm tools, all UH processing tools read their configuration options from a .d file and write output to a log file.

stalist_maker

The configuration file specifies:

- EVTFilesInDir - where the consolidated .evt files are to be found
- EVTFilesOutDir - where .evt files are moved upon success
- EVTFilesErrorDir - where .evt files are moved upon error
- StaListFile - name of the station list file
- NetworkCode - two letter code to be assigned as a network designation to all channels

This program reads through the directory of .evt files and creates a station file containing information about each channel found in those .evt files. The station list file contains the following fields:

- 1-6 Station Code
- 7-12 Component Code
- 13-17 Network Code
- 18-27 Latitude
- 28-38 Longitude
- 39-45 Elevation
- 46-50 Azimuth
- 51-55 Dip
- 56-60 Sampling Rate
- 61-64 Gain
- 65-70 Fullscale
- 71-81 Sensitivity
- 82-83 Damping
- 88-91 Sensor Type
- 92-101 Name of the Response File (Poles and Zeros)

Once the station list file is created, the user is invited to examine it and modify any fields that may be set incorrectly in the .evt headers. The file is re-usable since stalist_maker first attempts to read in an existing station list file before rummaging through the directory of .evt files. If an existing station list file is found, the values therein will over-ride whatever is found in .evt headers. In that case, stalist_maker will overwrite the existing station list file when it is done reading through .evt files. For this reason, it is a good idea to make a copy of an existing station list file before running stalist_maker.

stalist_loader

The configuration files specifies:

- StaListFile - name of the station list file
- PZ_Dir - directory containing response files
- Database connection parameters

- DBuser
- DBpassword
- DBservice

This program reads in the station list file and loads the information into the database. Note that the response files must be in the PZ_directory and must named exactly as they appear in the station list file for each channel.

cnsscat2ora

The configuration files specifies:

- Database connection parameters

- DBuser
- DBpassword
- DBservice

This program is invoked as:

cnsscat2ora config_file catalog_file

The catalog file must be in the CNSS format. This program inserts the information about the events from the catalog file into the database.

evtK2ora

The configuration file specifies:

- EVTFilesInDir - where the consolidated .evt files are to be found
- EVTFilesOutDir - where .evt files are moved upon success
- EVTFilesErrorDir - where .evt files are moved upon error
- NetworkCode - two letter code to be assigned as a network designation to all channels
- Database connection parameters

- DBuser
- DBpassword
- DBservice

- MaxTravelTime - maximum distance from the event
- Pvelocity - local P velocity in km/sec
- ClocDoubt - uncertainty of K2 clock in seconds

This program reads a consolidated directory of .evt files. For each file it selects a list of candidate events for association. This list includes all events falling in the time interval between the end-time of the trace snippet and MaxTravelTime seconds before the start of the trace snippet. An association is made if any part of the trace snippet falls between P and S arrival times, as calculated in a homogeneous half-space. The P velocity is specified in the configuration table. The S velocity is P/1.73.

Note that the station list and the catalog must both be loaded before this program can run successfully.

WEB TOOLS

Setup and Configuration

No special setup or configuration is necessary beyond setting up Earthworm Quick Review and the basic Earthworm web pages. Be sure that the getlist.d configuration file has ShowStasCol enabled in order to allow users to enter the ground motion download page.

View Ground Motion Traces

Clicking on the Stas column in the getlist page brings up a new browser window which displays all associated trace data (from .evt files) for the selected events. The top of the page shows basic parameters for the event. Below that, channels are arranged according to stations. For each station, the user can view either all channels at that stations by clicking on the station name, or individual channels by clicking on the channel link.

Clicking on either type of link will bring up the SeisGram2K applet showing the selected trace data. If the channel name in the list is followed by a (+GM) tag, ground motion transformation was successfully completed and the applet will display four trace panels for each channel:

- raw data in counts
- acceleration in nm/s2
- velocity in nm/s
- displacement in nm

Download Trace Data

The user can select which waveforms to download (in SAC format) by selecting buttons corresponding either to all channels at a station or to specific channels. By clicking DONE at the bottom of the page, the user makes a request from the web server to package up the selected trace data.

The user will then be shown another web page offering up the selected trace data for download either as a .zip or a .tar file. Once downloaded and unpacked, those files will create a directory containing SAC files for each selected channel, with the following naming convention:

- STA.CHAN.NET - raw data in counts
- STA.CHAN.NET.acc - acceleration
- STA.CHAN.NET.vel - velocity
- STA.CHAN.NET.disp - displacement
- STA.CHAN.NET.pz - response poles-and-zeros used to transform the raw trace data into ground motion.