Shakemapfeed Configuration File Commands

# shakemapfeed's parameter file

# Basic Earthworm setup
#----------------------
MyModuleId         MOD_SHAKEMAPFEED # module id for this instance
RingName           HYPO_RING        # shared memory ring for input/output
HeartBeatInterval  30               # seconds between heartbeats
LogFile            1                # 0 = log to screen only
                                    # 1 = log to disk and screen
                                    # 2 = log to disk only
Debug              1                # 0 for no debug messages
                                    # non-zero logs debug messages

# List the message logos to grab from transport ring -
# shakemapfeed can process three different message types:
#  GetEventsFrom     command is required (at least one).
#  GetMagnitudesFrom command is optional.
#  GetEQDeletesFrom  command is optional.
#                 Installation    Module     # Message Types
#--------------------------------------------------------------
GetEventsFrom     INST_WILDCARD MOD_WILDCARD # TYPE_HYP2000ARC (hardcoded)
GetMagnitudesFrom INST_WILDCARD MOD_WILDCARD # TYPE_MAGNITUDE  (hardcoded)
GetEQDeletesFrom  INST_WILDCARD MOD_WILDCARD # TYPE_EQDELETE   (hardcoded)

# Set criteria for creating files for shakemap
#---------------------------------------------
MagThresh         3.5               # Minimum magnitude to feed shakemap
MagWeightThresh   2.0               # Minimum magnitude weight (~no. of stas)

DelayFirstFeed    30                # Seconds to wait between receiving archive
                                    #   msg and starting first feed to shakemap.
UpdateInterval    10                # Minutes between updates to shakemap
                                    #   once an "interesting event" happens.
UpdateDuration    120               # Keep creating updates for shakemap
                                    #   until this many minutes after the
                                    #   event origin time.  Assumes your
                                    #   computer's clock is set close to UTC.
TempDir          /home/tmp          # Full path of working directory.
OutputDir        /home/shakemap     # Full path of directory in which to
                                    #   write completed shakemap files.
ShakemapFormat    2                 # Specify format of output files:
                                    #   1=shakemap1, 2=shakemap2(XML)
UseEventID        1                 # Specify which eventid to write in output:
                                    #   1=binder eventid, 2=DBMS eventid
LogShakemapFile   1                 # non-zero causes shakemap file to be
                                    #   written to shakemapfeeder's log
QuakeAuthor       014024003         # MsgLogo of original TYPE_HYP2000ARC
                                    #   msg, written as a 9-char ascii string
                                    #   msgtype-moduleid-installationid.
                                    #   Used with binder's eventid to look up
                                    #   the DBMS is of the event.
MappingFile       NCSN.map          # File contain mappings of instrument type,
                                    #   long station names and agency names
                                    #   MappingFile is optional.

# Set criteria for requesting strongmotion data from the DBMS
#------------------------------------------------------------
DBservice         db_service        # which instance DBMS to connect to
DBuser            db_user           # as this user name
DBpassword        db_pswd           # with this password
MaxDataPerEvent   1000              # Maximum number of channels of SM data
                                    #   to retrieve from DBMS for each event.
LatitudeRange     5.0               # request data within Y degrees lat of eq.
LongitudeRange    6.0               # request data within X degrees lon of eq.

# Add list of components to block (optional):
BlockComponent VHZ
BlockComponent HV1

# Set up time tolerance in seconds (how sloppy are timestamps?)
DefaultTimeTolerance     1.0   # tolerance for unlisted networks
NetTimeTolerance     PG 30.0
NetTimeTolerance     NP 30.0
NetTimeTolerance     CE 50.0

# Specify a simple velocity model ala binder_ew
# One "lay depth-to-top P-velocity" command per layer
lay  0.0 6.5
lay 25.0 8.0
psratio 1.78

# List page groups to notify when a shakemap file is generated (optional).
# One group per command, up to 10 PageOnShakemapFeed commands.
PageOnShakemapFeed jack_seismologist
PageOnShakemapFeed jill_seismologist

Below are the configure commands recognized by Shakemapfeed, grouped by the function they influence. Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Most of the commands are required.

3. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

command arg1						function

BlockComponent XYZ		 			Data selection & filtering

Optional command lists a component code that shakemapfeed should not write to its output file. XYZ is the 3-letter component code that appears in the channel's station-component-network codes.

Example:  BlockComponent VHZ

DBpassword password					DBMS access

Password of the database user that has read/write access to all the strongmotion tables that shakemapfeed uses. To access the DBMS, shakemapfeed must first log in as the database user, giving the correct password. See also DBuser and DBservice commands.

Example:  DBpassword abc123				

DBservice servicename					DBMS access

Name of the database service that shakemapfeed will retreive data from. This servicename is a character string that is mapped to a tcp/ip address and port number in Oracle's tnsnames.ora file on the shakemapfeed computer. See also DBuser and DBpassword commands.

Example:  DBservice myeqs				

DBuser username						DBMS access

Name of the database user that has read/write access to all the strongmotion tables that shakemapfeed uses. To access data in the DBMS, shakemapfeed must first log in as username. See also DBpassword and DBservice commands.

Example:  DBuser equser				

Debug flag						Output Control

Optional command to control the amount of logging done by shakemapfeed. If flag is zero, debug-level logging is turned off; shakemapfeed will do normal logging of start, stop, error conditions, and brief descriptions of how it has handled each message it received. If flag is non-zero, shakemapfeed will include details about its strong-motion filtering decisions.

Example:  Debug 0				

DefaultTimeTolerance nsec				Data selection & filtering

Sets a default value for how sloppy the timestamps on strongmotion data can be. Shakemapfeed will write a set of strongmotion data to its output file if its timestamp +/- nsec is within the expect traveltime range for that station. Shakemapfeed calculates traveltimes using the simple velocity model specified with the lay and psratio commands. You can specify different time tolerances for different network codes using the NetTimeTolerance command. Any network code not specifically listed will be assigned the default tolerance.

Example:  DefaultTimeTolerance 1.0

DelayFirstFeed delaysec					Shakemap file creation

Controls when shakemapfeed creates the first shakemap files for an event. After receiving a TYPE_HYP2000ARC message for a new qualifying event, shakemapfeed sets the "feed shakemap" timer to the current system time plus delaysec seconds. This allows time for strongmotion data to be inserted into the DBMS.

Example:  DelayFirstFeed 15

GetEQDeletesFrom inst mod_id				Earthworm setup

Optional command which controls the event deletion messages (TYPE_EQDELETE) input to shakemapfeed. Shakemapfeed will only process eqdelete messages that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Wildcards (INST_WILDCARD and MOD_WILDCARD) will force shakemapfeed to process all eqdelete messages, regardless of their place of origin.

Example:  GetEQDeletesFrom INST_MENLO MOD_WILDCARD				

GetMagnitudesFrom inst mod_id				Earthworm setup

Optional command which controls the magnitude messages (TYPE_MAGNITUDE) input to shakemapfeed. Shakemapfeed will only process magnitudes that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Wildcards (INST_WILDCARD and MOD_WILDCARD) will force shakemapfeed to process all magnitude messages, regardless of their place of origin.

Example:  GetMagnitudesFrom INST_MENLO MOD_WILDCARD				

GetEventsFrom inst mod_id				Earthworm setup

Controls the event messages (TYPE_HYP2000ARC) input to shakemapfeed. Shakemapfeed will only process events that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Wildcards (INST_WILDCARD and MOD_WILDCARD) will force shakemapfeed to process all event messages, regardless of their place of origin.

Example:  GetEventsFrom INST_MENLO MOD_EQFILTER				

HeartBeatInterval nsec					Earthworm setup		

Defines the minimum number of seconds nsec between TYPE_HEARTBEAT messages issued by shakemapfeed.

Example:  HeartbeatInt 30

LatitudeRange latrange					Data selection & filtering

Sets the latitude range (in degrees) for requesting strongmotion data from the DBMS. Shakemapfeed uses space-time box to request associated and unassociated strongmotion data. The latitude boundaries of the space box is set to the epicenter latitude +/- latrange degrees. The longitude range is set with the LongitudeRange command.

Example:  LatitudeRange 5.0

LogFile switch						Output Control

Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written, but messages may go to stderr and/or stdout. If switch is 1, shakemapfeed will write to stderr/stdout and to a daily log file(s) called shakemapfeedxx.log_ccyymmdd where xx is shakemapfeed's module id (set with "MyModuleId" command) and ccyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). If switch is 2, the log file will be written, but no messages will go to stderr or stdout.

Example:  LogFile 1

LogShakemapFile switch					Output Control

Sets the on-off switch for including shakemapfeed's output files in its daily log. If switch is non-zero, shakemapfeed will write its output files to its log. If switch is 0, it won't.

Example:  LogShakemapFile 1

lay depth velocity					Data selection & filtering

Defines the layered velocity structure to be used for calculating travel times. depth is the distance (km) to the top of the layer, and velocity is the seismic P-wave velocity (km/sec) within that layer. No default velocity structure is defined; therefore, the user must always supply one in the control file. Up to 20 layers can be specified, and they should be listed in order of increasing depth.

Example:  lay   0.0  4.0
          lay   3.5  5.9
          lay  15.0  6.85
          lay  25.0  7.85

LongitudeRange lonrange					Data selection & filtering

Sets the longitude range (in degrees) for requesting strongmotion data from the DBMS. Shakemapfeed uses space-time box to request associated and unassociated strongmotion data. The longitude boundaries of the space box is set to the epicenter longtitude +/- lonrange degrees. The latitude range is set with the LatitudeRange command.

Example:  LongitudeRange 6.0

PageOnShakemapFeed pagegroup				Output Control

Optional command to enable pager message output. pagegroup is a string (up to 30 characters) that identifies a page recipient in your installation's paging system. Up to 10 PageOnShakemapFeed commands may be used. Shakemapfeed will produce a TYPE_PAGE message addressed to each pagegroup every time it produces shakemap files (message includes eventid, cumulative number of feeds for this event, and time elapsed since event origin) and every time it removes an event from the processing list.

Example:  PageOnShakemapFeed  joe_seismologist

psratio value                                		Data selection & filtering

Sets the value of the P/S seismic velocity ratio. Used in calculating travel times.

Default:  psratio  1.72                 

QuakeAuthor author					Data selection & filtering

Identifies the earthworm author of the earthquake's eventid. author (a 9-character string) is the ascii representation of the earthworm MSG_LOGO of the original TYPE_HYP2000ARC message for the event. The logo is written with 3-digits each for message type, module id, and installation id. The message type should always be 014 (for TYPE_HYP2000ARC from earthworm_global.d), the module id will usually be MOD_EQPROC (look number up in your earthworm.d), and the installation id is installation-dependent (see earthworm_global.d). This author string is used in conjunction with the eventid (found in the TYPE_HYP2000ARC message) to look up the DBMS id of the event. Knowing the DBMS id, shakemapfeed can easily request all strongmotion data in the DBMS that is associated with the event.

Example:  QuakeAuthor 014024003

MagThresh magthresh					Shakemap file creation

Sets the minimum magnitude event for shakemapfeed to work on. Shakemapfeed reads the magnitude value and magnitude weight for both the preferred and duration magnitudes from the first line of the TYPE_HYP2000ARC message. Shakemapfeed uses the preferred magnitude if its weight is non-zero. Otherwise, shakemapfeed uses the duration magnitude. If the event magnitude is greater than or equal to magthresh and its weight is greater than or equal to the magnitude weight threshold (set with MagWeightThresh command), shakemapfeed will enter the event into its processing list and set timers for generating shakemap files.

Example:  MagThresh 3.5

MagWeightThresh magwtthresh				Shakemap file creation

Sets the minimum magnitude weight for an event to qualify for shakemapfeed. In most cases, the magnitude weight is an approximation of the number of stations that were used in the magnitude determination; shakemapfeed reads magwtthresh as a floating point number. Shakemapfeed reads the magnitude value and magnitude weight for both the preferred and duration magnitudes from the first line of the TYPE_HYP2000ARC message. Shakemapfeed uses the preferred magnitude if its weight is non-zero. Otherwise, shakemapfeed uses the duration magnitude. If the event magnitude is greater than or equal to the magnitude threshold (set with MagThresh command) and its weight is greater than or equal to magwtthresh, shakemapfeed will enter the event into its processing list and set timers for generating shakemap files. If shakemapfeed receives a TYPE_MAGNITUDE message, it will replace the event's existing magnitude with the new magnitude only if its weight is greater than or equal to magwtthresh.

Example:  MagWeightThresh 2.0

MappingFile fname					Shakemap file creation

Identifies the optional mapping file fname to be used for producing ShakemapFormat 2 (XML) files. This file maps 2-letter network codes and station codes to longer, possibly more descriptive, character strings. These longer strings are included in the XML output. Hopefully this mapping file will become obsolete when this kind of information is contained in the DBMS.

Example: MappingFile YourNetwork.map

Sample Mapping file:

# Mapping file contains tables of instrument types, long station names
# and agency names.
# Agency net agency-name # net is standard network code;
#    agency-name: the long agency name, up to 40 characters
Agency NC   Northern California Seismic Network
Agency BK   Berkeley Digital Seismic Network
#
#
# Station sta net longName
#  sta and net are standard station and network codes;
#  longName is the long station name, up to 20 characters
Station  ARC   BK     Arcata Humbolt Stat
Station  BDM   BK     Black Diamond Mines
Station  BKS   BK     UC Berkeley -Byerly
Station  BRIB  BK     Briones Russel Rsrv
#
# Inst sta comp net inst-type
#   sta, comp and net are standard station, component and network codes
#   inst-type is the instrument description, up to 50 characters
Inst  ARC     BHZ   BK   Unknown Type
Inst  ARC     HLE   BK   Kinemetrics FBA-23
Inst  ARC     HLN   BK   Kinemetrics FBA-23
Inst  ARC     HLZ   BK   Kinemetrics FBA-23
Inst  BDM     HLE   BK   Unknown Accelerometer

MaxDataPerEvent maxdata					Data selection & filtering

Controls the number of strongmotion data sets shakemapfeed can retrieve from the DBMS for each event. All the information contained in one TYPE_STRONGMOTIONII message (PGA,PGV,PGD,spectral accelerations,etc) counts as one data set. If a channel reports a preliminary and a final TYPE_STRONGMOTIONII message, that counts as 2 data sets. Therefore, maxdata should be set to allow for the number of individual strongmotion channels in your network plus duplicate data (if applicable). Before writing shakemap files, shakemapfeed does filter out duplicate data, using the set loaded into the database last.

Example:  MaxDataPerEvent 1000

MyModuleId mod_id					Earthworm setup

Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number.

			
Example:  MyModuleId MOD_SHAKEMAPFEED

NetTimeTolerance net nsec				Data selection & filtering

Sets a value for how sloppy the timestamps on strongmotion data from a specific network can be. This is an optional command. net is the 2-letter code that identifies the network in the data, nsec is the tolerance in seconds. Shakemapfeed will write a set of strongmotion data to its output file if its timestamp +/- nsec is within the expect traveltime range for that station. Shakemapfeed calculates traveltimes using the simple velocity model specified with the lay and psratio commands. Any network code not specifically listed will be assigned the default tolerance set in the DefaultTimeTolerance.

Example:  NetTimeTolerance  PG  30.0

OutputDir outputpath					Shakemap file creation

Sets the path to shakemapfeed's final output directory. outputpath is any string up to 55 characters. Shakemapfeed creates its output files in the directory specified by the TmpDir command. When complete, it moves them to outputpath. Any program using the output of shakemapfeed should look only in the outputpath directory.

Example: OutputDir /home/earthworm/run/shakemapfeed

RingName ring						Earthworm setup

Tells shakemapfeed which shared memory region to use for input and output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

		
Example:  RingName HYPO_RING

ShakemapFormat format					Shakemap file creation

Controls what format shakemapfeed's output will be in. Valid values for format are 1 or 2. Format 1 is an outdated ascii file that contains both event origin and strongmotion data and was used by shakemap version 1. Format 2 produces XML files, one for the event and a second for the associated strongmotion data. Format 2 is used as input by shakemap version 2.

Example: ShakemapFormat 2

TempDir tmppath						Shakemap file creation

Sets the path to shakemapfeed's temporary working directory. tmppath is any string up to 55 characters. Shakemapfeed creates its output files in tmppath. When complete, it moves them to the final output directory specified in the OutputDir command. This temporary work space is necessary to keep shakemap or other programs from trying to process a partially-complete shakemap file.

Example: TempDir /home/earthworm/run/tmp

UpdateDuration totalduration				Shakemap file creation

Controls when shakemapfeed will stop updating shakemap files for an event. When shakemapfeed gets a TYPE_HYP2000ARC message for a qualifying event, it sets the "stop automatic updating" time to the event origin time plus totalduration minutes. When the system clock passes this time, shakemapfeed will stop producing shakemap files automatically . Note that since shakemapfeed uses event origin time to set an absolute "stop" time, you'll want to keep the computer's clock fairly close to UTC (within a minute). If shakemapfeed gets a new piece of information (TYPE_HYP2000ARC or TYPE_MAGNITUDE message) for an event whose update duration has already expired, it will force the creation of one set of shakemap files immediately. This feature allows manual re-runs of older events (use file2ring to write the contents of an ascii file into an Earthworm ring).

Example: UpdateDuration 120

UpdateInterval nmin					Shakemap file creation

Controls how frequently shakemapfeed creates the shakemap files for an event. After creating a set of shakemap files, shakemapfeed resets the "feed shakemap" timer to the current system time plus nmin minutes. When the timer expires, shakemapfeed will query the DBMS for strongmotion data. It will generate new shakemap files only if new strongmotion data has been received or if the event magnitude has been updated since the last feed.

Example: UpdateInterval 10

UseEventID idtype					Shakemap file creation

Controls which eventid shakemapfeed will write to its output file. Set idtype=1 to use binder's eventid, idtype=2 to use the DBMS eventid.

Example: UseEventID 1