# Earthworm Modules:
Localmag Configuration File

(last revised June 30, 2011)

Page Index:

1. Functional command listing
2. Alphabetic command listing & description
3. Sample Configuration File
4. References

On startup, localmag examines its command-line arguments; the name of the configuration file is always the last of these arguments. Localmag will look for the configuration file in the current directory, or in the directory named by the EW_PARAMS environment variable (if set.) If the configuration file is located elsewhere, you must provide the needed path information on the command-line.

Since localmag may run as a standalone program (as well as being an Earthworm module), several of its parameters may be set from the command-line. Command-line options will override any settings from the configuration file. Only a few configuration-file commands have command-line equivalents; these are indicated in the tables below. In the control file, lines may begin with a valid localmag command (listed below) or with one of 2 special characters:

    #  marks the line as a comment (example: # This is a comment).

    @  allows control files to be nested; one control file can be
       accessed from another with the command "@" followed by
       a string representing the path name of the next control file
       (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Blank lines are also permitted in the control file.

## 1. FUNCTIONAL COMMAND LISTING

Earthworm system setup: | command-line option
--- | ---
MyModId | may be Required
RingInName | Optional
RingOutName | Optional
getEventsFrom | may be Required
HeartBeatInterval | may be Required
LogFile | Optional | -l
Memory allocation commands
maxSta | Required
maxTrace | Required
Event and Trace commands
eventSource | Optional | -e
traceSource | Optional | -t
readAmpDirect | Optional | -a
traceTimes | Optional
extraDelay | Optional
Add | Optional
Del | Optional
ChannelNumberMap | Optional
maxDist | Required
saveTrace | Optional | -s
outputFormat | Optional
useMedian | Optional
eventXML | Optional
saveXMLdir | Optional
MlmsgOutDir | Optional
Amplitude Controls
searchTimes | Optional
searchStartPhase | Optional
slideLength | Optional
z2pThresh | Optional
meanCompMags | Optional
minStationsMl | Optional
require2Horizontals | Optional
allowVerticals | Optional
Auxiliary Data Sources
logA0 | Required
respSource | Optional
staLoc | Required
velocity model | Optional
SgSpeed | Optional
SCNLpar | Optional
Miscellaneous Commands
Debug | Optional
EWDBaccess | Optional
Sacsource | Optional
WoodAndersonCoefs | Optional
wsTimeout | Optional

## 2. 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.) A detailed description of the command and is also given. Default values and example commands are listed after each command description.

command arg1 | function
Add STA COMP NET LOC | Event and Trace Commands
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
allowVerticals Flag | Amplitude Controls
allowVerticals is an optional configuration parameter. If the Flag is set to any non-zero integer, then Z components (vertical channels) are used in the ML computation. If an separte attenuation relationship is provided for them (see logA0 command), then it will be used otherwise the attenuation of the horizontals will be used. Verticals are NOT ALLOWED by default (if this command is missing).
    Default: 0, this command is optional
    Example: allowVerticals 1
Debug D | Miscellaneous Commands
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
ChannelNumberMap ENZ | Event and Trace Commands
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.
Del STA COMP NET LOC | Event and Trace Commands
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
eventSource SOURCE [params] | Event and Trace Commands
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
eventXML n | Event and Trace Commands
Optional setting to force writing of the SHAKEMAP EVENT XML format file to the SAC output directory. MUST BE USED with saveTrace option and SAC output at the time of this writing. Defaults to being off. Set n to 1 to activate this feature.
EWDBaccess USER PASSWORD SERVICE | Miscellaneous Commands
Specify the three parameters needed to access and Earthworm database. Not currently implemented.
extraDelay seconds | Event and Trace Commands
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
getEventsFrom INST MOD | Earthworm Setup
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
HeartBeatInterval H | Earthworm Setup
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
logA0 FILE | Auxilliary Data Sources
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
LogFile: `-lS` | Earthworm Setup
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)
maxDist D | Event and Trace Commands
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
maxSta N | Memory Allocation
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
maxTrace M | Memory Allocation
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
meanCompMags | Amplitude Controls
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
minStationsMl N | Amplitude Controls
If present, this parameter allows the minimum number N of stations needed for an Ml to be declared. Any number less than N will cause the magnitude to be written to the logs, but not published. This defaults to 1 if not set.
    Default: flag is absent, N is set to 1
    Example: minStationsMl 4
MlmsgOutDir directory | Event and Trace Commands
Optional setting to save all LM messages in distinct files within a specified directory. The format file is:
            <Event-Id>_<Origin-Version>_event.lm
MyModId mod_id | Earthworm setup
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
outputFormat FORMAT | Event and Trace Commands
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
readAmpDirect | Amplitude Controls
Get the WA amplitude directly from the source format (SAC or UW format), instead of synthesizing the trace into a Wood-Anderson response and getting the peak from that. The default is to get this from the trace by converting to a W-A time-series.
require2Horizontals Flag | Amplitude Controls
If the Flag is set to any non-zero integer, then any station contributing to an Ml must have both horizontal components with valid amplitudes otherwise the station is not included in the Ml. This option defaults to off (or 0). In the future this may be used for other options....
    Default: 0, this command is optional
    Example: require2Horizontals 1
respSource SOURCE [params] | Auxilliary Data Sources
  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
RingInName ring | Earthworm setup
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
RingOutName ring | Earthworm setup
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
SACsource DIR FORMAT | Miscellaneous Commands
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
saveTrace ST [params] DIR FORMAT | Event and Trace Commands
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
saveXMLdir directory | Event and Trace Commands
Optional setting to force writing of the SHAKEMAP EVENT XML format file to the specified output directory. Using this option ignores the eventXML option which is for backward compatibility at INGV where this feature was added. The format file is:
            <Event-Id>_<Origin-Version>_event.xml
SCNLpar STA COMP NET LOC special-parameters | Auxilliary Data Sources
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
searchStartPhase phase | Amplitude Controls
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
searchTimes A B | Amplitude Controls
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
SgSpeed | Amplitude Controls
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
slideLength N | Amplitude Controls
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
staLoc LOC [params] | Auxilliary Data Sources
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
tracesource SOURCE [params] | Event and Trace Commands
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
traceTimes START END | Event and Trace Commands
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. Once localmag computes the start and end times for the trace using the traceTimes values, it adds on additional time to the trace window. This extra time is used to apply a cosine taper to the data in the time domain. The length of each of these tapers will be 5 percent of the total trace length. The tapered portion of the trace is never including in the peak search window nor in the pre-event noise check window. This taper is applied to prevent `wrap-around' spikes from appearing in the pre-event noise check window.
    Default: traceTimes 5.0 60.0
    Example: traceTimes 10.0 40.0
useMedian | Event and Trace Commands
By default the localmag program puts the average Ml into the TYPE_MAGNITUDE message. If this command is issued, then the median value of the median is inserted into the magnitude and the algorithm member of the MAG_INFO struct is set to "MED"
    Default: useMedian (off by default)
    Example: useMedian
velocity model | Auxilliary Data Sources
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
WoodAndersonCoefs period damp gain | Miscellaneous Commands
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
wsTimeout M | Miscellaneous Commands
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
z2pThresh T | Miscellaneous Commands
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

##
3. Sample Configuration File

# Configuration file for the localmag program
# Some of these parameters can be overridden on the command-line;
# some of them only make sense on the command-line.
#
# As of 20 December, 2000, there is NO SUPPORT for Earthworm Database (EWDB)
#
# Required Commands:
# The following five commands are always required by localmag.
# Other commands below may be required when certain options are given.
#
# maxSta number
# The number of stations to be used by localmag must be specified with
# the maxSta command. This is the number of unique SNs to be used.
# A total of 6 * maxSta channel structures will be allocated.
# The maxSta command must come before any "Pri" commands.
maxSta 100
# maxDist km
# The maximum epicenter - station distance in kilometers.
# Stations lying outside this radius will not be used by localmag.
#
maxDist 600
# maxTrace nsamples
# The maximum number of trace data samples to process from one SCNL.
# 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.
maxTrace 60000
# logA0 filename
# The file containing the table of -logA0 values versus distance.
# This file mist start with two commands:
# Dist : which distance is to used to access this table.
# choices are: epi - station - epicenter distance
# hypo - station - hypocenter distance (use event depth
# but not station depth.)
# nDist number: the number of table entries that follow.
# Following these two commands are `nDist' 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. If the desired distance
# exceeds the largest distance in this table, then the -logA0 value for
# the last table entry will be returned.
logA0 Richter.tab
# staLoc: station location source
# Choices: File - get station locations from a hyp2000-format
# file named loc-file
# EWDB - query the EW database for station locations; access info
# given below.
# SAC - get station locations from the header of SAC files.
# Can be either station lat and lon, or station-epicenter
# distance in the SAC header.
staLoc File /data0/earthworm/run/params/hypoinverse/stas/uw_sta.hinv
# Regional Velocity model: must be specified as "@vel_model_file". Typically
# this will be the same file as used for binder_ew.
@uw_velocity.d
# Speed of Sg wave; provides a good estimate of the Wood-Anderson peak arrival
SgSpeed 3.39
# Optional Commands
#
# eventSource: Tells localmag how and where to learn about a new event
# choices are: ARCH - hyp2000 archive message
# SAC - SAC file header;
# EWDB - query EW database for eventID; usually
# given as command-line option.
# default: ARCH
# eventSource ARCH
# traceSource: Where localmag will obtain trace data
# choices are: waveServer - raw traces from wave_servers;
# server-list is either a space separated list
# of ip-address:port or
# "File "
# SACFile - raw traces from SAC files
# SACWAFile - synthetic Wood-Anderson traces from SAC files
# EWDB - raw traces from EW database; access info given below
# default: waveServer with list of servers read from $EW_PARAMS/servers
# traceSource waveServer File servers
# Add STA COMP NET
# Del STA COMP NET
# SCNL selection is done by a selection list and a rejection list.
# The station selection command `Add' specifies the names of
# STA (station), COMP (component), and NET (network).
# The wildcard `*' may be used for any or all of STA, COMP, NET.
# COMP may be given as the first two letters of the component name,
# to select all direction desgnators are accepted for that component.
# If no Add commands are given, all SCNLs will be selected.
# The Del command is used to put SCNLs on the rejection list:
# for example: "Add * EL UW" followed by "Del LAB EL UW" to include
# all ELE and ELN components from UW except LAB.ELE.UW and LAB.ELN.UW.
# Localmag will NEVER use vertical components.
# List as many Add and Del commands as desired, one to a line
Add * BH *
Add * HH *
Add * SL *
Add * EL *
Del LAB * UW
# respSource: Tells localmag where to get response information;
# may be ommitted if traceSource points to Wood-Anderson
# Choices: EWDB - query the EW databse for pole-zero-gain responses.
# SAC - find response files in the
# SAC directory given with SACsource.
# filename-format is a string similar to 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 that used by SAC.
# File - find response files in
# directory dirname with file names given by
# pz-filename-format, as above. dirname can be
# a full directory name, or relative to $EW_PARAMS.
#
# default: none; you must specify one of the above choices.
respSource File responses %S_%C_%N.pz
# readAmpDirect: flag to tell localmag to read Wood-Anderson amplitudes
# directly from a `trace' source instead of from Wood-Anderson traces.
# If this flag is used, then traceSource must be one that includes
# amplitude data, such as SAC files, EW database.
#
# default: flag is not present, so localmag reads amplitudes from
# Wood-Anderson traces that it either synthesizes or reads from traceSource.
# extraDelay seconds
# number of seconds to wait after the total trace length has arrived at
# most distant station before processing event; used only when localmag is
# running as an Earthworm module.
# default: extraDelay 0.0 # no extra delay added to estimated propagation time
extraDelay 0.0
# traceTimes start end
# The start and end times for traces is set here.
# is the number of seconds before estimated P arrival to start
# the trace.
# is the number of seconds after estimated Sg arrival to end the trace.
# default: traceTimes 5.0 60.0 # starts trace 5 seconds before estimated P
# arrival and ends trace 60 seconds after estimated S arrival.
traceTimes 5.0 60.0
# searchStartPhase phase
# The phase to use for computing the start of the peak serach window
# Choices: P - the first-arriving P phase from the layered velocity model
# S - the first-arriving S phase from the layered velocity model
# default: searchStartPhase S
searchStartPhase S
# searchTimes A B
# The time window for searching for peak amplitudes is set here.
# number of seconds before the searchStartPhase to start the
# search window.
# is the number of seconds of seconds after the constant-speed Sg
# arrival to end the search window
# default: searchTimes 1.0 45.0 # Search window runs from 1 second
# before searchStartPhase arrival to 45 seconds after Sg arrival
searchTimes 1.0 45.0
# slideLength n
# Set the width of of the sliding search window to n seconds.
# default: slideLength 0.8 # sliding search window is 0.8 seconds wide
slideLength 0.8
# z2pThresh is the threshold by which the zero-to-peak maximum in the
# search window must exceed the zero-to-peak maximum from the
# pre-event portion of the trace. This test tries to ensure that the
# zero-to-peak and peak-to-peak values are seismic and not just noise.
# default: z2pThresh 3.0
z2pThresh 3.0
# meanCompMags: 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.
# WoodAndersonCoefs : 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 (BSSA 1990, V80 p702-716) and
# others indicate better values are:
# period 0.8 seconds; damping 0.7 critical; gain 2080 (twenty-eighty)
#
# default: WoodAndersonCoefs 0.8 0.8 2800
# saveTrace: whether and how to save synthetic Wood-Anderson traces
# If saveTrace command is absent, no traces will be saved.
# Choices: SAC -
# save W-A traces in SAC-format files.
# baseDir specifies a fixed directory name.
# dirFormat gives a formattted subdirectory name; the
# format string is that used for the "date" command applied
# to the event origin time, with the addition of `%i'
# to indicate the event ID and optionally `%v' for the
# the origin version. Be careful with this; some
# formats produce output not compatible with file names.
# 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.
#
# default: None (no Wood-Anderson traces are saved.)
# eventXML 1 - turns on writing SHAKEMAP XML files to the SAC directory
# that is specified by the saveTrace command above. This feature contributed by INGV.
# default is that this feature is off (0).
# outputFormat: how localmag reports its results; results are always logged
# Choices: LM - TYPE_MAGNITUDE message to earthworm transport
# File - write TYPE_MAGNITUDE message to the
# file specified by filename. Standalone mode only.
# EWDB - send results to Earthworm database.
# default: LM if using earthworm transport; no report otherwise
#
# EWDBaccess user password service
# How to access the Earthworm Database, if needed.
# Give the user name, password, and srvice needed for connection.
# default: none
# SACsource : where to find SAC files for
# reading.
# is a fixed directory name
# is the format for SAC
# file names.
# This command or its equivalent on the command
# line is required if traceSource or respSource
# is SAC files.
SACsource /data0/earthworm/working/src/localmag/Test/98042703361 %S.%C
# wsTimeout: wave_server timeout in milliseconds
# default: 5000 milliseconds
# wsTimeout 10000
# Earthworm Transport commands. Use these commands to make localmag
# run as an earthworm module to run continuously.
# Otherwise localmag runs as a standalone program and handles a
# single event per invocation.
#
# RingInName : specify the name of the earthworm transport ring from
# which to read TYPE_HYP2000ARC messages for event notification.
# RingInName HYPO_RING
# RingOutName : specify the name of the earthworm transport ring to
# which Magnitude, Heartbeat and Error messages are sent. This may be
# the same as RingInName if desired.
# RingOutName HYPO_RING
# MyModId : specify the module ID for localmag
# MyModId MOD_LOCALMAG
# HeartBeatInterval int: How often localmag should beat its heart.
# Currently, localmag will not issue heartbeats while it is busy doing
# calculations for an event. Thus a heartbeat could be late by as much as the
# time it takes to do a full localmag event calculation. Be sure that
# statmgr will wait that long for the heartbeat.
# HeartBeatInterval 30
# getEventsFrom INST_ID MOD_ID
# Specify the installation ID and module ID names from which to get
# hypoinverse archive messages to read event data. These names may be
# selected from earthworm.d and earthworm_global.d Only required when
# localmag is running as an Earthworm module. No default values.
# Use as many of these commands as necessary.
getEventsFrom INST_WILDCARD MOD_WILDCARD
LogFile 1
# 1 -> Keep log, 0 -> no log file
# 2 -> log to module log but not to stderr/stdout
# default: LogFile 1
# Debug N
# There are several different debug features, listed below.
# You can give one Debug command for each feature you want to turn on,
# or you can add together the values of desired features and give
# one Debug command.
# value feature
# 1 trace and search times and P and S arrival estimates
# 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
# 128 full frequency response function to STDOUT
# 256 input and output trace date including in padded area
# SCNL Parameters: normally this command will be given as "@SCNL_param_file"
# to cause the separate file "SCNL_param_file" to be processed.

##
4. References

- Uhrhammer & Collins (BSSA 1990, V80 pp702-716)
- Richter & Guttenberg (BSSA 1942, V32 pp163-191)
- Boore (Tectonophysics 1989, V166, pp1-14)

Module Index | localmag Overview

Contact: