Earthworm Modules:
Localmag Configuration File

Add the trace(s) with station name STA, component name COMP and network name NET and location code LOC to the selection list. Any of STA, COMP and NET may be the wildcard character `*'. COMP may be given as the first two letters of the component name, to select all direction desgnators (North and East) are accepted for that component. Vertical `Z' components are never selected by localmag. Zero, one or many Add commands may be listed in the configuration file. If no Add commands are given, all SCNLs from the trace source will be selected. The Del command may be used to narrow the selection implied by wildcard values in an Add command or by the absence of any Add commands.

Default: all traces are selected from a trace source
Example: Add * BH *
         Add SEA EH UW

Default: 0, this command is optional
Example: allowVerticals 1

Set the debug level to D. There are many different debug options; one or more of them may be activated using the Debug command. More than one Debug command may be used, or the different values (from the table) may be added together into one Debug command. Except as noted, the debug information is printed to STDERR and the log file (depending on the setting of LogFile.) Select from these debug options:

1:

trace and search times and P and S arrival estimates (relative to event origin time)

2:

SCNL selection tests

4:

distance and LogA0 values

8:

SAC file selection (only if traceSource is SAC)

16:

ws_client debugging

32:

poles. zeros and gain values

64:

trial frequency response functions to STDOUT. Produces about 1500 lines for each SCNL, which should be saved to a file.

128:

full frequency response function to STDOUT. Produces several thousand lines for each SCNL, which should be saved to a file.

256:

Input and output trace data including in padded arear to STDOUT. Produces several thousand lines for each SCNL, which should be saved to a file.

Default: 0; no debug output
Example: Debug 7 # turns on options 1, 2 and 4

Convert channels with Number orientations to letter orientations using the mapping string ENZ provided. The Map string maps 1 to the first letter, 2 to the second letter, and 3 to the last letter of the three char string provided. For example, a map of ENZ that means channels named EH1 would be seen as a East component horizontal and channel EH2 would be seen as a north component horizontal. Note that localmag does not recognize numbers, so this conversion is needed, otherwise the channel is rejected.

Default: Not used, numbered channels are ignored.

Delete the trace(s) with station name STA, component name COMP, network name NET, and location code LOC from the selection list. Any of STA, COMP and NET may be the wildcard character `*'. COMP may be given as the first two letters of the component name, to select all direction desgnators (North and East) are accepted for that component. Zero, one or many Del commands may be listed in the configuration file.

Default: all traces are selected from a trace source
Example: Del SEA BH UW 01

Tells localmag where to find information about the event it is to process. The event information that localmag needs is: origin time, origin latitude, longitude and depth. If any of these values are missing, localmag will not process the event. EventSource may be specified on the command line (especially when run as a stand-alone program) instead of in the configuration file. The choices available for SOURCE are:

ARCH:

Command line: -eh Read event information from a hyp2000 archive message. This message is read from standard input except when localmag is running as an earthwrom module (see MyModId). In that case, the archive message is read from the transport ring.

SAC:

Command line: -es Read event information from the headers of one or more SAC files. If this option is used, then traceSource must be SAC and SACsource must be given. See also the command-line option for traceSource for naming the SAC directory on the command line.

EWDB eventID:

Command line: -ee eventID Obtain event information from an Earthworm database. Not currently implemented.

Default: ARCH (read hyp2000 archive messages)
Examples for the command-line: -es 00010101095

Specify the three parameters needed to access and Earthworm database. Not currently implemented.

When running as an Earthworm module (see RingInName) localmag will wait before processing a new event until traces have had time to propagate to the maxDist plus extraDelay seconds (which may be positive or negative.) The calculation of the maximum wait time is done at startup, assuming an event on the surface and a station at maxDist. When a new event message is received, localmag compares the origin time to the current (system) time. Localmag then sleeps until origin time is older than system time by the computed wait time. This will ensure that the waves localmag is aboutto request will have time to arrive at the station and thence at the wave_server.

Default:  0 seconds extra delay
Example:  extraDelay 10.0

Get event messages (TYPE_HYP2000ARC) from installation INST and module MOD. These installation and module IDs are found in earthworm.d and earthworm_global.d. Only one getEventsFrom command may be used; use the wildcard installation or module IDs if dewsired. This command is required if localmag is running as an earthworm module; see MyModId.

Default:  none
Example:  getEventsFrom INST_WILDCARD MOD_EQPROC

Send TYPE_HEARTBEAT messages every H seconds to the transport ring. This command is required if localmag is running as an earthworm module; see MyModId.

Default:  none
Example:  HeartbeatInterval 30

Specify the file containing the table of attenuation factors ( -log(A0) ) used in the local magnitude calculation. This file mist start with two commands:

Dist type:

Identify which distance is to used to access this table. Choices are:

epi:

station - epicenter distance

hypo:

station - hypocenter distance (uses event depth but not station depth.)

nDist N:

The number of table entries that follow is at most N.

Following these two commands are up to N lines of distance and -logA0 values. The distance numbers must be integer values, in kilometers. The -logA0 values are positive decimal values. Entries MUST be in order of increasing distance. When this table is used to find the -logA0 value, the entry with distance nearest to the desired distance will be used. As of June 30, 2011, the attenuation relationship allows for vertical components to have a separate attenuation curve as an option with the allowVerticals configuration parameter. This is to allow those networks (like LCSN) who have computed attenuation on verticals to compute ML on vertical (Z) channels. The EasternUS.tab is provided with the release of localmag now as an example of 2 attenuation curves specified. If the desired distance exceeds the largest distance in this table, then the -logA0 value for the last table entry will be returned. The file Richter.tab provided with the localmag program contains the table established by Richter & Guttenberg for Southern California. Note that localmag will try to read the logA0 file from the current directory. Specify the appropriate path information if the file is located elsewhere.

David Boore reminds us:

The proper procedure is first to determine the attenuation for the region, and second to constrain the curves at 100 km according to the formal definition of Ml.

Default:  none
Example:  logA0 Richter.tab

Sets the value of the logging switch to S. Possible values of S are:

0:

Do not create a log file. Some logging data will be printed to the screen (stdout or stderr.)

1:

Create a log file in the directory named by the EW_LOG environment variable. The log file name will based on the config-file name and the current data. A new file will be created for each day (but only if there are logging entries to be made.) Some logging data will be printed to the screen (stdout or stderr,) as with option `0' above.

2:

Create a log file as for option `1', but do not write anything to the screen (stdout or stderr.)

Default: 1
Example (on the command-line):  -l0 (lower-case ell zero; turns off creation of
        log file)

Sets the maximum station - epicenter distance to D kilometers. Traces outside this distance from the epicenter will not have their traces processed by localmag.

Default: none, this command is required.
Example: maxDist 600

At startup, localmag will allocate space for N individual stations (unique station/network names.) Each station may have any number of different components (BHE/BHN/HHE/HHN.) If localmag tries to read more than N stations, the excess ones will be skipped with a logged warning message. The order that stations are read into localmag is determined by the trace source and thus may be arbitrary.

Default: none, this command is required.
Example: maxSta 100

Allocate memory for M data samples to process for one trace. This is the product of the trace length in seconds and the highest expected sample rate. For example, 10 minutes of data at 100 samples per second gives 60000 samples. The time duration of traces used by localmag is determined by the traceTimes command and the estimated P and S phase arrival times.

Default: none, this command is required
Example: maxTrace 60000

If present, this command causes localmag to compute a stations local magnitude by taking the mean of the local magnitudes for each of its horizontal components, Otherwise, localmag will take the average of the component amplitudes and use that to find the local magnitude for the station.

Default: flag is absent
Example: meanCompMags

Default: flag is absent, N is set to 1
Example: minStationsMl 4

Sets the module id for labeling all outgoing localmag, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number. In general, a different module ID is needed for each instance of localmag.

Default: none
Example: MyModId MOD_LOCALMAG

Determines how localmag will report its results. In any event, localmag will log its results as set by the log switch. Choices for FORMAT are:

LM:

Write the output to an Earthworm TYPE_MAGNITUDE message which is sent to transport to the transport ring. This option is avaliable only if local mag is running as an Earthworm module (see RingInName), in which case LM is the default FORMAT.

File filename:

Write the output in TYPE_MAGNITUDE format to the file specified by filename. This option is avaliable only if localmag is running in stand-alone mode (see RingInName).

EWDB:

Send the localmag results to an Earthworm Database. Not currently implemented.

Default: LM if using earthworm transport; no report except logs otherwise
Example: LM
Example: File /tmp/localmag_output

Default: 0, this command is optional
Example: require2Horizontals 1

Tells localmag where to find instrument response data. This command is required unless readAmpDirect option is present or the trace source provides Wood-Anderson traces. Choices for SOURCE are:

SAC pz-filename-format

find response files in the SAC directory given with SACsource. pz-filename-format is a string similar to the printf format: %S, %C, %N are replaced by station, component and network names, respectively, all in upper case. Similarly %s, %c, %n work for lower-case station, component and network. The digraph %% stands for %; all other characters are taken literally.

The response file format is similar to that used by SAC POLEZERO files with some extra requirements. The options in the file are keyword driven and the numbers are in free format. You may specify a multiplicative scaling constant by putting a line in the file containing the keyword "CONSTANT" followed by a floating point number. The default for this constant is 1.0 if you omit this line. You specify the number of poles by putting a line in the file with the keyword "POLES" following by an integer number. The next lines in the file until another keyword is read become the poles for this instrument. Each such line contains two floating point numbers specifying the real and imaginary parts of one of the poles. If you have fewer lines specifying poles than you stated on the "POLES" line, the remaining poles are assumed to lie at the origin. You specify the zeros in the same way with a "ZEROS" keyword line following by lines specifying the zeros that do not lie at the origin. You may specify up to as many poles and zeros as you need.

The poles, zeros and gain constant of the response file MUST be for an input of displacement in nanometers. See the documentation provided by the NEIC AutoDRM for more details. The poles and zeros specify the Laplace transform of the analogue instrument response. Currently localmag has no provision for handling digital FIR or IIR filter responses. For example, the following is the specification for the NSN broadband seismometer OCWA.BHE.US:

CONSTANT    0.50280E+11
ZEROS       3
        0.00000E+00    0.00000E+00
        0.00000E+00    0.00000E+00
        0.00000E+00    0.00000E+00
POLES       6
       -0.31420E-01    0.00000E+00
       -0.19790E+00    0.00000E+00
       -0.20110E+03    0.00000E+00
       -0.69740E+03    0.00000E+00
       -0.75400E+03    0.00000E+00
       -0.10560E+04    0.00000E+00

FILE dirname pz-filename-format

Similar to the SAC option above, except that the response files will be found in the directory dirname. The same requirements apply to the response files.

EWDB

Query an Earthworm Database for reponse information. Not currently implemented.

Default: none, you must specify respSource if localmag is to synthesize
  Wood-Anderson traces.
Example: File /earthworm/responses %S_%C_%N.pz

Tells localmag which shared memory region to use reading hyp2000 arc messages. 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. If this command is present in the configuration file, localmag will run as an Earthworm module, processing as many events as it learns about. If RingInName is absent from the config-file, localmag will run as a standalone program, processing a single event for each invocation.

Default:  none
Example:  RingInName HYPO_RING

Tells localmag which shared memory region to use for sending magnitude, heartbeat and error messages. 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. If RingInName is used, then RingOutName must also be given. This ring can be the same as or different from the RingInName ring.

Default:  none
Example:  RingOutName MAG_RING

Tells localmag to read SAC files from the DIR directory. These files could be SAC data files used by any of eventSource,traceSource, or staLoc. Or they could be SAC pole-zero-gain files read by respSource. When localmag is going to read SAC data files, it will scan the directory DIR for file names that match the format string FORMAT.

The FORMAT string may include special format characters, which are introduced by `%'. The special characters are any of "sScCnN%". The letters s or S indicate a station name which must start with an alphabetic character, contain alphabetic characters or numbers, be up to 6 characters long; for s has no upper-case letters; for S has no lower-case. Similarly, c or C search for a component name, up to 8 characters, and n or N search for a network name, up to 8 characters long. These odd name lengths are base on Earthworm tracebuf packets. The symbol % must match itself, as do all characters not preceeded by %. The pattern matching of file names againts FORMAT is fairly crude. For example, the FORMAT string %S.%C would match the file name LKWY1.BHE. But the FORMAT string %S1.%C would not match: LKW1 would match the %S, leaving nothing to match the `1' in the format string. If the SAC directory contained a SAC datafile named LKW1.BHE and a response file named LKW1,BHE.resp, the FORMAT string %S.%C would correctly match the datafile name and skip the response file.

Default:  none
Example: SACsource /earthworm/data/98042703361 %S.%C.%N

Tells localmag whether and how to save synthetic Wood-Anderson traces. If the saveTrace command is absent, no traces will be saved. Choices for ST include:

SAC baseDir dirFormat filename-format

Save Wood-Anderson traces in SAC-format files. The full pathname for each SAC file will be made up of base directory, formatted directory, and formatted filename; all concatenated together with appropriate path separators.

baseDir

Specifies a fixed directory name. This can be an absolute directory path or a path relative to the current directory. It can contain one or more parts with pathname separators. This all components of this path (except possibly the last) must exist before localmag is started.

dirFormat

Gives a formattted subdirectory name; the format string is that used for the Unix date command applied to the event origin time, with the addition of `%i' to indicate the event ID and `%v' to indicate the version of the event ID. Be careful with this; some formats produce output not compatible with directory names. The directory name derived from dirFormat must not contain any path separators. Suitable format strings include:

%C

Century number (the year divided by 100 and truncated to an integer as a decimal number [1,99]); single digits are preceded by 0.

%d

Day of month [1,31]; single digits are preceded by 0.

%h

Locale's abbreviated month name.

%H

Hour (24-hour clock) [0,23]; single digits are preceded by 0.

%i

The Earthworm event ID. Currently this event ID can only be read from a hyp2000 archive message.

%j

Day number of year [1,366]; single digits are preceded by 0.

%m

Month number [1,12]; single digits are preceded by 0.

%M

Minute [00,59]; leading zero is permitted but not required.

%R

Time as %H:%M

%S

Seconds [00,61]

%T

Time as %H:%M:%S

%u

Weekday as a decimal number [1,7], with 1 representing Sunday.

%U

Week number of year as a decimal number [00,53], with Sunday as the first day of week 1.

%v

The version of the Earthworm event ID. Currently this version of the event ID can only be read from a hyp2000 archive message.

%V

Week number of the year as a decimal number [01,53], with Monday as the first day of the week. If the week containing 1 January has four or more days in the new year, then it is considered week 1; otherwise, it is week 53 of the previous year, and the next week is week 1.

%w

Weekday as a decimal number [0,6], with 0 representing Sunday.

%W

Week number of year as a decimal number [00,53], with Monday as the first day of week 1.

%y

Year within century [00,99].

%Y

Year, including the century (for example 1993),

filename-format

Gives the formatted file name using % to introduce one of the format specifiers "sScCnN%" `s' is the station name in lower case; `S' is upper case. Likewise for component and network names; `%' stands for itself. All other characters are taken literally. This works in the same way as the format string for SAC response files.

Localmag adds the following special fields to SAC file headers. If a zero-to-peak amplitude pick was made for the trace, the amplitude value will be placed in USER0, and the time of the pick will be placed in T0. If a pair of peak-to-peak amplitude picks were made for a trace, then the minimum amplitude will be placed in USER1; the maximum amplitude will be placed in USER2; the time of the negative peak will be placed in T1; and the time of the maximum peak will be placed in T2. Comments to this effect will be placed in the respective string fields for each of these data values. See the slideLength command for details about amplitude picking.

Default:  command is absent (no Wood-Anderson traces are saved)
Example: SAC /earthworm/SAC/W-A %Y%j%i %S.%C.%N
Example: SAC /earthworm/SAC/W-A %i_%v  %S.%C.%N

Set certain parameters (described below) for specific traces identified by their SCN: STA, COMP, NET, and LOC (station/component/network name.) No wildcards are permitted here; each SCNL must be given explicitly, but only if special values are needed for that SCNL. Often, the default values will be adequate for most SCNLs. If there are only a few of these commands, they may be listed in the configuration file. But if a large number of them are needed, it may be more convenient to place them in a separate file. Then that file will get included with the configuration file by the syntax:

@scnl_param_file

Note that the format of this files is identical to the one used by the gmew module. Each SCNLpar command must include the STA, COMP, NET, LOC names followed by the following seven decimal values. Use spaces between all eleven items in each SCNLpar line. All values must be present; no default values are used for an SCNL if it has an SCNLpar line. The seven decimal values are:

magnitude correction

The value to be added to the component local magnitude to account for site effects. Normally this value should be the same for each component at a given site.

taper low-freq off

The frequency at the low end of the passband below which the cosine taper has zero value. This taper is applied to the frequency response function before it is convolved with the trace. Frequency units are Hz.

taper low-freq on

The frequency at the low end of the passband above which the cosine taper has a value of 1. The low-end taper can be eliminated by setting the off and on values to the same value. The default low-end taper is turned off, passing all low frequencies.

taper high-freq on

The frequency at the high end of the passband below which the cosine taper has a value of 1.

taper high-freq off

The frequency at the high end of the passband above which the cosine taper has a value of 0. The high-end taper can be eliminated by setting the off and on values to the same value. The default high-end taper has an off value equal to the trace Nyquist frequency (one half the sample rate.) The default on frequency is 90% of the Nyquist frequency.

clipping limit

The value, in digital counts, beyond which in absolute value the unprocessed trace should be considered clipped. If the trace is declared clipped by locamag, it will synthesized into a Wood-Anderson trace, but it will not have amplitude picks or magnitude calculations performed. The default clipping limit is 7.55e+06 counts, 90% of 2^23, the limit of a 24-bit digitizer.

taper time interval

This value is not used by localmag; it is only used by the gmew module.

Default: as described above
Example: SCNLpar SEA EHE UW -- 0.2   0.1 0.1 20 25   2.9e4 1.0

Specify which phase arrival time to use in computing the search start time (see searchTimes). Choices are P for the first arriving P phase from the layered velocity model, or S for the first arriving S phase from the layered model.

Default: searchStartPhase S
Example: searchStartPhase P

Specify the start and end times of the interval in which localmag will search for peak amplitudes in the Wood-Anderson traces. Together with the P- or S-phase arrival times estimated from the velocity model, and the Sg arrival time these two parameters set the start and end times of this search window. The search times are computed as follows:

start time:

= T - A

end time:

= (distance/SgSpeed) + B

where T is arrival time of the searchStartPhase and distance is the distance from hypocenter to station.

Default: searchTimes 1.0 45.0 # Search window runs from 1 second
        before searchStartPhase to 45 seconds after the estimated Sg arrival
Example: searchTimes 1.0 45.0

Specify the speed of the Sg phase. Research by Jim Peschmann at UUSS has shown that the majority of peak amplitudes in the Wood-Anderson traces occur near to or after the Sg phase arrival. This fixed phase speed is a better predictor of the peak time than the phases computed from the layered velocity model.

Default: none, required command
Example: SgSpeed 3.39

Localmag can perform two different searches for the "peak" magnitude of a given Wood-Anderson trace. First, (provided the trace has no gaps and is not clipped), a search is made for the largest absolute value within the search window. This will be the largest zero-to-peak value, since the Wood-Anderson trace always has zero mean in the program.

The second search is a "sliding window" search, in which the largest swing, positive-to-negative or negative-to-positive, is measured within a sliding window of N seconds duration. The window slides along the full length of the search window. The result is the largest peak-to-peak value for the trace. Since the local magnitude formula is based on a zero-to-peak value, one half of the peak-to-peak value is used for the magnitude calculation. The intent of this sliding window search is to reduce the chances of picking a one-sided glitch that could happen with the zero-to-peak search.

To turn off the sliding-window search, set N to any negative value. If peak-to-peak values are not available to localmag (becuase the sliding-window search is disabled or because the values can't be read from the data source) localmag will use the zero-to-peak value if it is available. Turning off this feature will improve localmag's performance, since the sliding window search is quite CPU-intensive.

Default:  0.8 seconds, the free period of the Wood-Anderson instrument
Example: slideLength 1.0

Tells localmag where to find station location information. Station locations are used to find the station-epicenter distance, which is then used in the local magnitude calculation, as well as in the estimate of P and S phase arrivals. The choices for LOC are:

File loc-file:

Get station locations from a hyp2000-format station location file named loc-file. This file must be in text format, not the binary-format file sometimes used by hyp2000. If the file is not located in the current directory, partial or full path information must be included in loc-file.

EWDB

Query the Earthworm database for station locations. Not currently implemented.

SAC

Get station locations from the header of SAC files. This can be either station lat and lon, or station-epicenter distance in the SAC header. This option can only be used if the trace source is SAC.

Default: none; this command is required
Example: staLoc File /earthworm/run/params/hypoinverse/stas/uw_sta.hinv

Directs localmag to obtain trace data from SOURCE. In the event that localmag is reading amplitudes directly (see readAmpDirect), this command directs localmag to the appropriate SOURCE. Choices are:

waveServer server-list

Obtain trace data from the wave servers in server-list, a space delimited list of one or more server:port pairs. The server can be an IP address or a hostname for the wave server. The port is the port number used by that wave server.

waveServer File server-file

Command line: -tvObtain trace data from the wave servers listed in the file named server-file. This file consists of lines listing server and port, one server to each line. The two entries on a line may be separated by space or colon.

Localmag will connect to one server at a time. For each connection, it will obtain the server's current menu, match SCNLs on the menu against the selection list from Add and Del commands, obtain and process the trace data segment for each of the selected SCNLs. The time interval for each trace is established by the traceTimes command. After all the selected SCNLs for one wave server have been processed, the connection to that server will be closed and the next server will be accessed.

SACFile

Command line: -ts SACdir filename-formatObtain raw trace data (as opposed to Wood-Anderson traces) from SAC files. The files are found in directory SACdir, will filenames matching filename-format. See SACsource for details on filename matching..

SACWAFile

Command line: -tsW SACdir filename-formatObtain Wood-Anderson traces from SAC files. The files are found in directory SACdir, will filenames matching filename-format.

EWDB

Obtain raw trace data from an Earthworm Database. Not Currently implemented.

Default:  waveServer with list of servers read from the file $EW_PARAMS/servers
Example: traceSource SACFile

Specify the start and end times of trace data to be used from any trace source.

START:

is the number of seconds before the first P arrival from the layered velocity model to start the trace.

END:

is the number of seconds after the Sg arrival computed from hypocenter to station distance and SgSpeed to end the trace.

Default: traceTimes 5.0 60.0
Example: traceTimes 10.0 40.0

Default: useMedian (off by default)
Example: useMedian

Read in the one-dimensional velocity model to be used to estimate P and S phase arrival times. This is done using the syntax:

@velocity_file

Typically this will be the same file as used for binder_ew. Localmag will always look for this file in the current directory, so appropriate path information must be included if the file is located elsewhere. The commands that are most useful in this file are lay and psratio. Also see the Velocity Model section in the Notes on Configuring BINDER_EW.

Default:  none
Example: @/earthworm/run/params/uw_velovity.d

Optional command to specify the coefficients used for the Wood-Anderson instrument response. The standard parameters for the transfer function are: period: 0.8 seconds; damping 0.8 critical; gain: 2800. However, testing by Uhrhammer & Collins indicate better values are: period 0.8 seconds; damping 0.7 critical; gain 2080 (twenty-eighty). Be sure you know what you are doing before you change these values!

Default: as described above
Example: WoodAndersonCoefs 0.8 0.7 2080

Set the timeout for wave server connections to M milliseconds. If no response is heard from the wave server after this time, localmag will assume this wave server is dead and proceed to the next one.

Default: 5000 milliseconds
Example: wsTimeout 10000

In addition to searching the search window for peak amplitudes (the `event' zero-to-peak), localmag checks the part of trace prior to estimated P arrival for peak amplitude (the `pre-event' peak.) If the `event' peak is not greater than T times the `pre-event' peak, there is not sufficient event signal above the pre-event noise, and localmag does not use the event peak amplitude for that trace. Localmag will also skip the expensive sliding window search for peak-to-peak amplitude for small event peak amplitudes.

The traceTimes command in the config file specifies how many seconds before P and after S is to be analyzed by localmag. Starting from that time duration, additional time is allotted at each end to allow for a 5% time domain taper and still have the above specified ttime duration untouched by the taper. The pre-event noise level is determined from the synthetic Wood-Anderson data from the end of the starting taper to the time that is 10 percent of the start traceTimes value before the estimated P arrival.

Default: 3.0
Example: z2pThresh 1.5