Changes between Version 1 and Version 2 of localmag


Ignore:
Timestamp:
05/13/12 10:14:13 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • localmag

    v1 v2  
    108108 
    109109== Configuration File Commands == 
     110On 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. 
     111 
     112Since 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: 
     113{{{ 
     114#  marks the line as a comment (example: # This is a comment). 
     115    
     116@  allows control files to be nested; one control file can be  
     117   accessed from another with the command "@" followed by  
     118   a string representing the path name of the next control file  
     119   (example: @model.d). 
     120}}} 
     121Command 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. 
     122 
     123=== FUNCTIONAL COMMAND LISTING === 
     124{{{ 
     125'''Earthworm system setup:'''                   command-line option 
     126    MyModId             may be Required 
     127    RingInName          Optional 
     128    RingOutName         Optional 
     129    getEventsFrom       may be Required 
     130    HeartBeatInterval   may be Required 
     131    LogFile             Optional                -l 
     132'''Memory allocation commands''' 
     133    maxSta              Required 
     134    maxTrace            Required 
     135'''Event and Trace commands''' 
     136    eventSource         Optional                -e 
     137    traceSource         Optional                -t 
     138    readAmpDirect       Optional                -a 
     139    traceTimes          Optional 
     140    extraDelay          Optional 
     141    Add                 Optional 
     142    Del                 Optional 
     143    ChannelNumberMap    Optional 
     144    maxDist             Required 
     145    saveTrace           Optional                -s 
     146    outputFormat        Optional 
     147    useMedian           Optional 
     148    eventXML            Optional 
     149    saveXMLdir          Optional 
     150    MlmsgOutDir         Optional 
     151'''Amplitude Controls''' 
     152searchTimes             Optional 
     153searchStartPhase        Optional 
     154slideLength             Optional 
     155z2pThresh               Optional 
     156meanCompMags            Optional 
     157minStationsMl           Optional 
     158require2Horizontals     Optional 
     159allowVerticals          Optional 
     160'''Auxiliary Data Sources''' 
     161logA0                   Required 
     162respSource              Optional 
     163staLoc                  Required 
     164velocity model          Optional 
     165SgSpeed                 Optional 
     166SCNLpar                 Optional 
     167'''Miscellaneous Commands''' 
     168Debug                   Optional 
     169EWDBaccess              Optional 
     170Sacsource               Optional 
     171WoodAndersonCoefs       Optional 
     172wsTimeout               Optional 
     173}}} 
     174 
     175=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     176In 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. 
     177 
     178The following list is organized by: 
     179 
     180command [argument here] 
     181 
     182Add STA COMP NET LOC    Event and Trace Commands 
     183Add 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. 
     184Default: all traces are selected from a trace source 
     185Example: Add * BH * 
     186         Add SEA EH UW 
     187allowVerticals     Flag 
     188Amplitude Controls 
     189allowVerticals 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).  
     190Default: 0, this command is optional 
     191Example: allowVerticals 1 
     192Debug D Miscellaneous Commands 
     193Set 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: 
     1941: 
     195trace and search times and P and S arrival estimates (relative to event origin time) 
     1962: 
     197SCNL selection tests 
     1984: 
     199distance and LogA0 values 
     2008: 
     201SAC file selection (only if traceSource is SAC) 
     20216: 
     203ws_client debugging 
     20432: 
     205poles. zeros and gain values 
     20664: 
     207trial frequency response functions to STDOUT. Produces about 1500 lines for each SCNL, which should be saved to a file. 
     208128: 
     209full frequency response function to STDOUT. Produces several thousand lines for each SCNL, which should be saved to a file. 
     210256: 
     211Input and output trace data including in padded arear to STDOUT. Produces several thousand lines for each SCNL, which should be saved to a file. 
     212Default: 0; no debug output 
     213Example: Debug 7 # turns on options 1, 2 and 4 
     214ChannelNumberMap ENZ    Event and Trace Commands 
     215Convert 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. 
     216Default: Not used, numbered channels are ignored. 
     217Del STA COMP NET LOC    Event and Trace Commands 
     218Delete 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. 
     219Default: all traces are selected from a trace source 
     220Example: Del SEA BH UW 01 
     221eventSource SOURCE [params]     Event and Trace Commands 
     222Tells 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: 
     223ARCH: 
     224Command 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. 
     225SAC: 
     226Command 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. 
     227EWDB eventID: 
     228Command line: -ee eventID Obtain event information from an Earthworm database. Not currently implemented. 
     229Default: ARCH (read hyp2000 archive messages) 
     230Examples for the command-line: -es 00010101095 
     231eventXML n      Event and Trace Commands 
     232Optional 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. 
     233 
     234EWDBaccess USER PASSWORD SERVICE        Miscellaneous Commands 
     235Specify the three parameters needed to access and Earthworm database. Not currently implemented. 
     236extraDelay seconds       Event and Trace Commands 
     237When 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. 
     238Default:  0 seconds extra delay 
     239Example:  extraDelay 10.0 
     240getEventsFrom INST MOD   Earthworm Setup 
     241Get 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. 
     242Default:  none 
     243Example:  getEventsFrom INST_WILDCARD MOD_EQPROC 
     244HeartBeatInterval H      Earthworm Setup 
     245Send TYPE_HEARTBEAT messages every H seconds to the transport ring. This command is required if localmag is running as an earthworm module; see MyModId. 
     246Default:  none 
     247Example:  HeartbeatInterval 30 
     248logA0 FILE      Auxilliary Data Sources 
     249Specify the file containing the table of attenuation factors ( -log(A0) ) used in the local magnitude calculation. This file mist start with two commands: 
     250Dist type: 
     251Identify which distance is to used to access this table. Choices are: 
     252epi: 
     253station - epicenter distance 
     254hypo: 
     255station - hypocenter distance (uses event depth but not station depth.) 
     256nDist N: 
     257The number of table entries that follow is at most N. 
     258Following 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. 
     259David Boore reminds us: 
     260 
     261The 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. 
     262Default:  none 
     263Example:  logA0 Richter.tab 
     264 
     265 
     266LogFile: -lS    Earthworm Setup 
     267Sets the value of the logging switch to S. Possible values of S are: 
     2680: 
     269Do not create a log file. Some logging data will be printed to the screen (stdout or stderr.) 
     2701: 
     271Create 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. 
     2722: 
     273Create a log file as for option `1', but do not write anything to the screen (stdout or stderr.) 
     274Default: 1 
     275Example (on the command-line):  -l0 (lower-case ell zero; turns off creation of 
     276        log file) 
     277maxDist D       Event and Trace Commands 
     278Sets the maximum station - epicenter distance to D kilometers. Traces outside this distance from the epicenter will not have their traces processed by localmag. 
     279Default: none, this command is required. 
     280Example: maxDist 600 
     281maxSta N        Memory Allocation 
     282At 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. 
     283Default: none, this command is required. 
     284Example: maxSta 100 
     285maxTrace M      Memory Allocation 
     286Allocate 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. 
     287Default: none, this command is required 
     288Example: maxTrace 60000 
     289 
     290 
     291 
     292meanCompMags    Amplitude Controls 
     293If 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. 
     294Default: flag is absent 
     295Example: meanCompMags 
     296 
     297 
     298 
     299minStationsMl  N 
     300Amplitude Controls 
     301If 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. 
     302 
     303Default: flag is absent, N is set to 1 
     304Example: minStationsMl 4 
     305 
     306MlmsgOutDir directory   Event and Trace Commands 
     307Optional setting to save all LM messages in distinct files within a specified directory. The format file is: 
     308        <Event-Id>_<Origin-Version>_event.lm  
     309 
     310 
     311MyModId  mod_id Earthworm setup 
     312Sets 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. 
     313Default: none 
     314Example: MyModId MOD_LOCALMAG 
     315outputFormat FORMAT     Event and Trace Commands 
     316Determines how localmag will report its results. In any event, localmag will log its results as set by the log switch. Choices for FORMAT are: 
     317LM: 
     318Write 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. 
     319File filename: 
     320Write 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). 
     321EWDB: 
     322Send the localmag results to an Earthworm Database. Not currently implemented. 
     323Default: LM if using earthworm transport; no report except logs otherwise 
     324Example: LM 
     325Example: File /tmp/localmag_output 
     326readAmpDirect   Amplitude Controls 
     327Get 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. 
     328 
     329require2Horizontals     Flag 
     330Amplitude Controls 
     331If 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.... 
     332Default: 0, this command is optional 
     333Example: require2Horizontals 1 
     334respSource SOURCE [params]      Auxilliary Data Sources 
     335Tells 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: 
     336SAC pz-filename-format 
     337find 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. 
     338The 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. 
     339 
     340The 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: 
     341 
     342 
     343CONSTANT    0.50280E+11 
     344ZEROS       3 
     345        0.00000E+00    0.00000E+00 
     346        0.00000E+00    0.00000E+00 
     347        0.00000E+00    0.00000E+00 
     348POLES       6 
     349       -0.31420E-01    0.00000E+00 
     350       -0.19790E+00    0.00000E+00 
     351       -0.20110E+03    0.00000E+00 
     352       -0.69740E+03    0.00000E+00 
     353       -0.75400E+03    0.00000E+00 
     354       -0.10560E+04    0.00000E+00 
     355FILE dirname pz-filename-format 
     356Similar 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. 
     357EWDB 
     358Query an Earthworm Database for reponse information. Not currently implemented. 
     359Default: none, you must specify respSource if localmag is to synthesize 
     360  Wood-Anderson traces. 
     361Example: File /earthworm/responses %S_%C_%N.pz 
     362RingInName ring Earthworm setup 
     363Tells 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. 
     364Default:  none 
     365Example:  RingInName HYPO_RING 
     366RingOutName ring        Earthworm setup 
     367Tells 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. 
     368Default:  none 
     369Example:  RingOutName MAG_RING 
     370SACsource DIR FORMAT    Miscellaneous Commands 
     371Tells 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. 
     372The 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. 
     373 
     374Default:  none 
     375Example: SACsource /earthworm/data/98042703361 %S.%C.%N 
     376 
     377 
     378 
     379saveTrace ST [params] DIR FORMAT        Event and Trace Commands 
     380Tells 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: 
     381SAC baseDir dirFormat filename-format 
     382Save 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. 
     383baseDir 
     384Specifies 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. 
     385dirFormat 
     386Gives 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: 
     387%C 
     388Century number (the year divided by 100 and truncated to an integer as a decimal number [1,99]); single digits are preceded by 0. 
     389%d 
     390Day of month [1,31]; single digits are preceded by 0. 
     391%h 
     392Locale's abbreviated month name. 
     393%H 
     394Hour (24-hour clock) [0,23]; single digits are preceded by 0. 
     395%i 
     396The Earthworm event ID. Currently this event ID can only be read from a hyp2000 archive message. 
     397%j 
     398Day number of year [1,366]; single digits are preceded by 0. 
     399%m 
     400Month number [1,12]; single digits are preceded by 0. 
     401%M 
     402Minute [00,59]; leading zero is permitted but not required. 
     403%R 
     404Time as %H:%M 
     405%S 
     406Seconds [00,61] 
     407%T 
     408Time as %H:%M:%S 
     409%u 
     410Weekday as a decimal number [1,7], with 1 representing Sunday. 
     411%U 
     412Week number of year as a decimal number [00,53], with Sunday as the first day of week 1. 
     413%v 
     414The version of the Earthworm event ID. Currently this version of the event ID can only be read from a hyp2000 archive message. 
     415%V 
     416Week 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. 
     417%w 
     418Weekday as a decimal number [0,6], with 0 representing Sunday. 
     419%W 
     420Week number of year as a decimal number [00,53], with Monday as the first day of week 1. 
     421%y 
     422Year within century [00,99]. 
     423%Y 
     424Year, including the century (for example 1993), 
     425filename-format 
     426Gives 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. 
     427Localmag 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. 
     428Default:  command is absent (no Wood-Anderson traces are saved) 
     429Example: SAC /earthworm/SAC/W-A %Y%j%i %S.%C.%N 
     430Example: SAC /earthworm/SAC/W-A %i_%v  %S.%C.%N 
     431 
     432 
     433 
     434saveXMLdir directory    Event and Trace Commands 
     435Optional 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: 
     436        <Event-Id>_<Origin-Version>_event.xml  
     437 
     438 
     439SCNLpar STA COMP NET LOC special-parameters     Auxilliary Data Sources 
     440Set 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: 
     441@scnl_param_file 
     442Note 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: 
     443magnitude correction 
     444The 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. 
     445taper low-freq off 
     446The 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. 
     447taper low-freq on 
     448The 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. 
     449taper high-freq on 
     450The frequency at the high end of the passband below which the cosine taper has a value of 1. 
     451taper high-freq off 
     452The 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. 
     453clipping limit 
     454The 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. 
     455taper time interval 
     456This value is not used by localmag; it is only used by the gmew module. 
     457Default: as described above 
     458Example: SCNLpar SEA EHE UW -- 0.2   0.1 0.1 20 25   2.9e4 1.0 
     459 
     460 
     461 
     462searchStartPhase phase  Amplitude Controls 
     463Specify 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. 
     464Default: searchStartPhase S 
     465Example: searchStartPhase P 
     466 
     467 
     468 
     469searchTimes A B Amplitude Controls 
     470Specify 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: 
     471start time: 
     472= T - A 
     473end time: 
     474= (distance/SgSpeed) + B 
     475where T is arrival time of the searchStartPhase and distance is the distance from hypocenter to station. 
     476Default: searchTimes 1.0 45.0 # Search window runs from 1 second 
     477        before searchStartPhase to 45 seconds after the estimated Sg arrival 
     478Example: searchTimes 1.0 45.0 
     479 
     480 
     481 
     482SgSpeed Amplitude Controls 
     483Specify 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. 
     484Default: none, required command 
     485Example: SgSpeed 3.39 
     486 
     487 
     488 
     489slideLength N   Amplitude Controls 
     490Localmag 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. 
     491The 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. 
     492 
     493To 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. 
     494 
     495Default:  0.8 seconds, the free period of the Wood-Anderson instrument 
     496Example: slideLength 1.0 
     497 
     498 
     499 
     500staLoc LOC [params]     Auxilliary Data Sources 
     501Tells 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: 
     502File loc-file: 
     503Get 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. 
     504EWDB 
     505Query the Earthworm database for station locations. Not currently implemented. 
     506SAC 
     507Get 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. 
     508Default: none; this command is required 
     509Example: staLoc File /earthworm/run/params/hypoinverse/stas/uw_sta.hinv 
     510 
     511 
     512 
     513tracesource SOURCE [params]     Event and Trace Commands 
     514Directs 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: 
     515waveServer server-list 
     516Obtain 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. 
     517waveServer File server-file 
     518Command 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. 
     519Localmag 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. 
     520 
     521SACFile 
     522Command 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.. 
     523SACWAFile 
     524Command line: -tsW SACdir filename-formatObtain Wood-Anderson traces from SAC files. The files are found in directory SACdir, will filenames matching filename-format. 
     525EWDB 
     526Obtain raw trace data from an Earthworm Database. Not Currently implemented. 
     527Default:  waveServer with list of servers read from the file $EW_PARAMS/servers 
     528Example: traceSource SACFile 
     529 
     530 
     531 
     532traceTimes START END    Event and Trace Commands 
     533Specify the start and end times of trace data to be used from any trace source. 
     534START: 
     535is the number of seconds before the first P arrival from the layered velocity model to start the trace. 
     536END: 
     537is the number of seconds after the Sg arrival computed from hypocenter to station distance and SgSpeed to end the trace. 
     538Once 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. 
     539Default: traceTimes 5.0 60.0 
     540Example: traceTimes 10.0 40.0 
     541 
     542 
     543 
     544useMedian 
     545Event and Trace Commands 
     546By 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" 
     547 
     548Default: useMedian (off by default) 
     549Example: useMedian 
     550 
     551velocity model  Auxilliary Data Sources 
     552Read in the one-dimensional velocity model to be used to estimate P and S phase arrival times. This is done using the syntax: 
     553@velocity_file 
     554Typically 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. 
     555Default:  none 
     556Example: @/earthworm/run/params/uw_velovity.d 
     557 
     558 
     559WoodAndersonCoefs period damp gain      Miscellaneous Commands 
     560Optional 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! 
     561Default: as described above 
     562Example: WoodAndersonCoefs 0.8 0.7 2080 
     563 
     564 
     565 
     566wsTimeout M     Miscellaneous Commands 
     567Set 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. 
     568Default: 5000 milliseconds 
     569Example: wsTimeout 10000 
     570 
     571 
     572 
     573z2pThresh T     Miscellaneous Commands 
     574In 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. 
     575The 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. 
     576Default: 3.0 
     577Example: z2pThresh 1.5 
     578 
     579=== Sample Configuration File === 
     580{{{ 
     581# Configuration file for the localmag program 
     582# Some of these parameters can be overridden on the command-line; 
     583# some of them only make sense on the command-line. 
     584# 
     585# As of 20 December, 2000, there is NO SUPPORT for Earthworm Database (EWDB) 
     586# 
     587# Required Commands:  
     588# The following five commands are always required by localmag. 
     589# Other commands below may be required when certain options are given. 
     590# 
     591# maxSta number 
     592# The number of stations to be used by localmag must be specified with 
     593# the maxSta command. This is the number of unique SNs to be used. 
     594# A total of 6 * maxSta channel structures will be allocated. 
     595# The maxSta command must come before any "Pri" commands. 
     596 
     597maxSta 100 
     598 
     599# maxDist km 
     600# The maximum epicenter - station distance in kilometers.  
     601# Stations lying outside this radius will not be used by localmag. 
     602# 
     603maxDist 600 
     604 
     605 
     606# maxTrace nsamples 
     607# The maximum number of trace data samples to process from one SCNL. 
     608# This is the product of the trace length in seconds and the highest  
     609# expected sample rate. For example, 10 minutes of data at 100 samples per 
     610# second gives 60000 samples. 
     611 
     612maxTrace 60000 
     613 
     614 
     615# logA0 filename 
     616# The file containing the table of -logA0 values versus distance. 
     617# This file mist start with two commands: 
     618# Dist : which distance is to used to access this table. 
     619# choices are: epi - station - epicenter distance 
     620# hypo - station - hypocenter distance (use event depth 
     621# but not station depth.) 
     622# nDist number: the number of table entries that follow. 
     623# Following these two commands are `nDist' lines of distance and -logA0  
     624# values. The distance numbers must be integer values, in kilometers. 
     625# The -logA0 values are positive decimal values. 
     626# Entries MUST be in order of increasing distance. 
     627# When this table is used to find the -logA0 value, the entry with distance 
     628# nearest to the desired distance will be used. If the desired distance 
     629# exceeds the largest distance in this table, then the -logA0 value for 
     630# the last table entry will be returned. 
     631 
     632logA0 Richter.tab 
     633 
     634 
     635# staLoc: station location source 
     636# Choices: File - get station locations from a hyp2000-format 
     637# file named loc-file 
     638# EWDB - query the EW database for station locations; access info 
     639# given below. 
     640# SAC - get station locations from the header of SAC files. 
     641# Can be either station lat and lon, or station-epicenter 
     642# distance in the SAC header. 
     643 
     644staLoc File /data0/earthworm/run/params/hypoinverse/stas/uw_sta.hinv 
     645 
     646 
     647# Regional Velocity model: must be specified as "@vel_model_file". Typically 
     648# this will be the same file as used for binder_ew. 
     649 
     650@uw_velocity.d 
     651 
     652# Speed of Sg wave; provides a good estimate of the Wood-Anderson peak arrival 
     653 
     654SgSpeed 3.39 
     655 
     656 
     657# Optional Commands 
     658# 
     659# eventSource: Tells localmag how and where to learn about a new event 
     660# choices are: ARCH - hyp2000 archive message 
     661# SAC - SAC file header;  
     662# EWDB - query EW database for eventID; usually 
     663# given as command-line option. 
     664# default: ARCH 
     665# eventSource ARCH 
     666 
     667 
     668# traceSource: Where localmag will obtain trace data 
     669# choices are: waveServer - raw traces from wave_servers;  
     670# server-list is either a space separated list 
     671# of ip-address:port or  
     672# "File " 
     673# SACFile - raw traces from SAC files 
     674# SACWAFile - synthetic Wood-Anderson traces from SAC files 
     675# EWDB - raw traces from EW database; access info given below 
     676# default: waveServer with list of servers read from $EW_PARAMS/servers 
     677 
     678# traceSource waveServer File servers 
     679 
     680 
     681# Add STA COMP NET 
     682# Del STA COMP NET 
     683# SCNL selection is done by a selection list and a rejection list. 
     684# The station selection command `Add' specifies the names of  
     685# STA (station), COMP (component), and NET (network).  
     686# The wildcard `*' may be used for any or all of STA, COMP, NET. 
     687# COMP may be given as the first two letters of the component name, 
     688# to select all direction desgnators are accepted for that component. 
     689# If no Add commands are given, all SCNLs will be selected. 
     690# The Del command is used to put SCNLs on the rejection list: 
     691# for example: "Add * EL UW" followed by "Del LAB EL UW" to include 
     692# all ELE and ELN components from UW except LAB.ELE.UW and LAB.ELN.UW. 
     693# Localmag will NEVER use vertical components. 
     694# List as many Add and Del commands as desired, one to a line 
     695 
     696Add * BH * 
     697Add * HH * 
     698Add * SL * 
     699Add * EL * 
     700Del LAB * UW 
     701 
     702 
     703# respSource: Tells localmag where to get response information;  
     704# may be ommitted if traceSource points to Wood-Anderson  
     705# Choices: EWDB - query the EW databse for pole-zero-gain responses. 
     706# SAC - find response files in the  
     707# SAC directory given with SACsource. 
     708# filename-format is a string similar to printf 
     709# format: %S, %C, %N are replaced by station,  
     710# component and network names, respectively, 
     711# all in upper case. Similarly %s, %c, %n work 
     712# for lower-case station, component and network. 
     713# The digraph %% stands for %; all other  
     714# characters are taken literally. 
     715# The response file format is that used by SAC. 
     716# File - find response files in 
     717# directory dirname with file names given by 
     718# pz-filename-format, as above. dirname can be  
     719# a full directory name, or relative to $EW_PARAMS. 
     720#  
     721# default: none; you must specify one of the above choices. 
     722 
     723respSource File responses %S_%C_%N.pz 
     724 
     725 
     726# readAmpDirect: flag to tell localmag to read Wood-Anderson amplitudes 
     727# directly from a `trace' source instead of from Wood-Anderson traces.  
     728# If this flag is used, then traceSource must be one that includes  
     729# amplitude data, such as SAC files, EW database. 
     730# 
     731# default: flag is not present, so localmag reads amplitudes from 
     732# Wood-Anderson traces that it either synthesizes or reads from traceSource. 
     733 
     734 
     735# extraDelay seconds 
     736# number of seconds to wait after the total trace length has arrived at 
     737# most distant station before processing event; used only when localmag is 
     738# running as an Earthworm module. 
     739# default: extraDelay 0.0 # no extra delay added to estimated propagation time 
     740 
     741extraDelay 0.0 
     742 
     743 
     744# traceTimes start end 
     745# The start and end times for traces is set here.  
     746# is the number of seconds before estimated P arrival to start 
     747# the trace. 
     748# is the number of seconds after estimated Sg arrival to end the trace. 
     749# default: traceTimes 5.0 60.0 # starts trace 5 seconds before estimated P 
     750# arrival and ends trace 60 seconds after estimated S arrival. 
     751 
     752traceTimes 5.0 60.0 
     753 
     754 
     755# searchStartPhase phase 
     756# The phase to use for computing the start of the peak serach window 
     757# Choices: P - the first-arriving P phase from the layered velocity model 
     758# S - the first-arriving S phase from the layered velocity model 
     759# default: searchStartPhase S 
     760 
     761searchStartPhase S 
     762 
     763 
     764# searchTimes A B 
     765# The time window for searching for peak amplitudes is set here. 
     766# number of seconds before the searchStartPhase to start the 
     767# search window. 
     768# is the number of seconds of seconds after the constant-speed Sg 
     769# arrival to end the search window 
     770# default: searchTimes 1.0 45.0 # Search window runs from 1 second 
     771# before searchStartPhase arrival to 45 seconds after Sg arrival 
     772 
     773searchTimes 1.0 45.0 
     774 
     775 
     776# slideLength n 
     777# Set the width of of the sliding search window to n seconds. 
     778# default: slideLength 0.8 # sliding search window is 0.8 seconds wide 
     779 
     780slideLength 0.8 
     781 
     782 
     783# z2pThresh is the threshold by which the zero-to-peak maximum in the 
     784# search window must exceed the zero-to-peak maximum from the 
     785# pre-event portion of the trace. This test tries to ensure that the 
     786# zero-to-peak and peak-to-peak values are seismic and not just noise. 
     787# default: z2pThresh 3.0 
     788 
     789z2pThresh 3.0 
     790 
     791# meanCompMags: If present, this command causes localmag to compute a  
     792# stations local magnitude by taking the mean of the local magnitudes 
     793# for each of its horizontal components, Otherwise, localmag will take 
     794# the average of the component amplitudes and use that to find the 
     795# local magnitude for the station. 
     796 
     797 
     798# WoodAndersonCoefs : optional command to specify the 
     799# coefficients used for the Wood-Anderson instrument response. The standard 
     800# parameters for the transfer function are:  
     801# period: 0.8 seconds; damping 0.8 critical; gain: 2800 
     802# However, testing by Uhrhammer & Collins (BSSA 1990, V80 p702-716) and 
     803# others indicate better values are: 
     804# period 0.8 seconds; damping 0.7 critical; gain 2080 (twenty-eighty) 
     805# 
     806# default: WoodAndersonCoefs 0.8 0.8 2800 
     807 
     808 
     809# saveTrace: whether and how to save synthetic Wood-Anderson traces 
     810# If saveTrace command is absent, no traces will be saved. 
     811# Choices: SAC -  
     812# save W-A traces in SAC-format files.  
     813# baseDir specifies a fixed directory name. 
     814# dirFormat gives a formattted subdirectory name; the 
     815# format string is that used for the "date" command applied 
     816# to the event origin time, with the addition of `%i'  
     817# to indicate the event ID and optionally `%v' for the 
     818# the origin version. Be careful with this; some 
     819# formats produce output not compatible with file names. 
     820# filename-format gives the formatted file name using 
     821# % to introduce one of the format specifiers "sScCnN%" 
     822# `s' is the station name in lower case; `S' is upper case 
     823# Likewise for component and network names; `%' stands for 
     824# itself. All other characters are taken literally. 
     825# 
     826# default: None (no Wood-Anderson traces are saved.) 
     827 
     828 
     829# eventXML 1    - turns on writing SHAKEMAP XML files to the SAC directory 
     830#    that is specified by the saveTrace command above. This feature contributed by INGV. 
     831#  default is that this feature is off (0). 
     832 
     833# outputFormat: how localmag reports its results; results are always logged 
     834# Choices: LM - TYPE_MAGNITUDE message to earthworm transport 
     835# File - write TYPE_MAGNITUDE message to the 
     836# file specified by filename. Standalone mode only. 
     837# EWDB - send results to Earthworm database. 
     838# default: LM if using earthworm transport; no report otherwise 
     839 
     840 
     841# 
     842# EWDBaccess user password service  
     843# How to access the Earthworm Database, if needed.  
     844# Give the user name, password, and srvice needed for connection. 
     845# default: none 
     846 
     847 
     848# SACsource : where to find SAC files for 
     849# reading. 
     850# is a fixed directory name 
     851# is the format for SAC 
     852# file names. 
     853# This command or its equivalent on the command 
     854# line is required if traceSource or respSource 
     855# is SAC files. 
     856 
     857SACsource /data0/earthworm/working/src/localmag/Test/98042703361 %S.%C 
     858 
     859 
     860# wsTimeout: wave_server timeout in milliseconds 
     861# default: 5000 milliseconds 
     862 
     863# wsTimeout 10000 
     864 
     865 
     866# Earthworm Transport commands. Use these commands to make localmag 
     867# run as an earthworm module to run continuously. 
     868# Otherwise localmag runs as a standalone program and handles a 
     869# single event per invocation. 
     870# 
     871# RingInName : specify the name of the earthworm transport ring from 
     872# which to read TYPE_HYP2000ARC messages for event notification. 
     873 
     874# RingInName HYPO_RING 
     875 
     876# RingOutName : specify the name of the earthworm transport ring to 
     877# which Magnitude, Heartbeat and Error messages are sent. This may be 
     878# the same as RingInName if desired. 
     879 
     880# RingOutName HYPO_RING 
     881 
     882# MyModId : specify the module ID for localmag 
     883# MyModId MOD_LOCALMAG 
     884 
     885# HeartBeatInterval int: How often localmag should beat its heart. 
     886# Currently, localmag will not issue heartbeats while it is busy doing 
     887# calculations for an event. Thus a heartbeat could be late by as much as the 
     888# time it takes to do a full localmag event calculation. Be sure that 
     889# statmgr will wait that long for the heartbeat. 
     890 
     891# HeartBeatInterval 30 
     892 
     893# getEventsFrom INST_ID MOD_ID 
     894# Specify the installation ID and module ID names from which to get 
     895# hypoinverse archive messages to read event data. These names may be 
     896# selected from earthworm.d and earthworm_global.d Only required when 
     897# localmag is running as an Earthworm module. No default values. 
     898# Use as many of these commands as necessary. 
     899 
     900getEventsFrom INST_WILDCARD MOD_WILDCARD 
     901 
     902 
     903LogFile 1  
     904# 1 -> Keep log, 0 -> no log file 
     905 
     906# 2 -> log to module log but not to stderr/stdout 
     907 
     908# default: LogFile 1 
     909 
     910 
     911# Debug N 
     912# There are several different debug features, listed below.  
     913# You can give one Debug command for each feature you want to turn on,  
     914# or you can add together the values of desired features and give  
     915# one Debug command. 
     916# value feature 
     917# 1 trace and search times and P and S arrival estimates 
     918# 2 SCNL selection tests 
     919# 4 distance and LogA0 values 
     920# 8 SAC file selection (only if traceSource is SAC) 
     921# 16 ws_client debugging 
     922# 32 poles. zeros and gain values 
     923# 64 trial frequency response functions to STDOUT 
     924# 128 full frequency response function to STDOUT 
     925# 256 input and output trace date including in padded area 
     926 
     927 
     928# SCNL Parameters: normally this command will be given as "@SCNL_param_file" 
     929# to cause the separate file "SCNL_param_file" to be processed. 
     930}}} 
     931 
     932=== References ==== 
     933 * Uhrhammer & Collins (BSSA 1990, V80 pp702-716) 
     934 * Richter & Guttenberg (BSSA 1942, V32 pp163-191) 
     935 * Boore (Tectonophysics 1989, V166, pp1-14) 
     936 
    110937 
    111938== Helpful Hints ==