Changes between Version 8 and Version 9 of localmag


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

--

Legend:

Unmodified
Added
Removed
Modified
  • localmag

    v8 v9  
    311311}}} 
    312312 
    313 LogFile: -lS    Earthworm Setup 
     313'''!LogFile: -lS'''[[BR]] 
     314Function: Earthworm Setup 
     315 
    314316Sets the value of the logging switch to S. Possible values of S are: 
    315 0: 
    316 Do not create a log file. Some logging data will be printed to the screen (stdout or stderr.) 
    317 1: 
    318 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. 
    319 2: 
    320 Create a log file as for option `1', but do not write anything to the screen (stdout or stderr.) 
     317 
     3180: Do not create a log file. Some logging data will be printed to the screen (stdout or stderr.) 
     319 
     3201: 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. 
     321 
     3222: Create a log file as for option `1', but do not write anything to the screen (stdout or stderr.) 
     323{{{ 
    321324Default: 1 
    322 Example (on the command-line):  -l0 (lower-case ell zero; turns off creation of 
    323         log file) 
    324 maxDist D       Event and Trace Commands 
     325Example (on the command-line):  -l0 (lower-case ell zero; turns off creation of log file) 
     326}}} 
     327 
     328'''maxDist [D]'''[[BR]] 
     329Function: Event and Trace Commands 
     330 
    325331Sets the maximum station - epicenter distance to D kilometers. Traces outside this distance from the epicenter will not have their traces processed by localmag. 
     332{{{ 
    326333Default: none, this command is required. 
    327334Example: maxDist 600 
    328 maxSta N        Memory Allocation 
     335}}} 
     336 
     337'''maxSta [N]'''[[BR]] 
     338Function: Memory Allocation 
     339 
    329340At 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. 
     341{{{ 
    330342Default: none, this command is required. 
    331343Example: maxSta 100 
    332 maxTrace M      Memory Allocation 
     344}}} 
     345 
     346'''maxTrace [M]'''[[BR]] 
     347Function: Memory Allocation 
     348 
    333349Allocate 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. 
     350{{{ 
    334351Default: none, this command is required 
    335352Example: maxTrace 60000 
    336  
    337  
    338  
    339 meanCompMags    Amplitude Controls 
     353}}} 
     354 
     355'''meanCompMags'''[[BR]] 
     356Function: Amplitude Controls 
     357 
    340358If 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. 
     359{{{ 
    341360Default: flag is absent 
    342361Example: meanCompMags 
    343  
    344  
    345  
    346 minStationsMl  N 
    347 Amplitude Controls 
     362}}} 
     363 
     364'''minStationsMl [N]'''[[BR]] 
     365Function: Amplitude Controls 
     366 
    348367If 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. 
    349  
     368{{{ 
    350369Default: flag is absent, N is set to 1 
    351370Example: minStationsMl 4 
    352  
    353 MlmsgOutDir directory   Event and Trace Commands 
     371}}} 
     372 
     373'''!MlmsgOutDir [directory]'''[[BR]] 
     374Function: Event and Trace Commands 
     375 
    354376Optional setting to save all LM messages in distinct files within a specified directory. The format file is: 
     377 
    355378        <Event-Id>_<Origin-Version>_event.lm  
    356379 
    357  
    358 MyModId  mod_id Earthworm setup 
     380'''!MyModId [mod_id]'''[[BR]] 
     381Function: Earthworm setup 
     382 
    359383Sets 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. 
     384{{{ 
    360385Default: none 
    361386Example: MyModId MOD_LOCALMAG 
    362 outputFormat FORMAT     Event and Trace Commands 
     387}}} 
     388 
     389'''outputFormat [FORMAT]'''[[BR]] 
     390Function: Event and Trace Commands 
     391 
    363392Determines how localmag will report its results. In any event, localmag will log its results as set by the log switch. Choices for FORMAT are: 
    364 LM: 
    365 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. 
    366 File filename: 
    367 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). 
    368 EWDB: 
    369 Send the localmag results to an Earthworm Database. Not currently implemented. 
     393 
     394LM: 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. 
     395 
     396File 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). 
     397 
     398EWDB: Send the localmag results to an Earthworm Database. Not currently implemented. 
     399{{{ 
    370400Default: LM if using earthworm transport; no report except logs otherwise 
    371401Example: LM 
    372402Example: File /tmp/localmag_output 
    373 readAmpDirect   Amplitude Controls 
     403}}} 
     404 
     405'''readAmpDirect'''[[BR]] 
     406Function: Amplitude Controls 
     407 
    374408Get 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. 
    375409 
    376 require2Horizontals     Flag 
    377 Amplitude Controls 
     410'''require2Horizontals [Flag]'''[[BR]] 
     411Function: Amplitude Controls 
     412 
    378413If 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.... 
     414{{{ 
    379415Default: 0, this command is optional 
    380416Example: require2Horizontals 1 
    381 respSource SOURCE [params]      Auxilliary Data Sources 
     417}}} 
     418 
     419'''respSource [SOURCE [params]]'''[[BR]] 
     420Function: Auxilliary Data Sources 
     421 
    382422Tells 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: 
    383 SAC pz-filename-format 
    384 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. 
     423 
     424SAC 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. 
     425 
    385426The 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. 
    386427 
    387428The 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: 
    388429 
    389  
     430{{{ 
    390431CONSTANT    0.50280E+11 
    391432ZEROS       3 
     
    400441       -0.75400E+03    0.00000E+00 
    401442       -0.10560E+04    0.00000E+00 
    402 FILE dirname pz-filename-format 
    403 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. 
    404 EWDB 
    405 Query an Earthworm Database for reponse information. Not currently implemented. 
    406 Default: none, you must specify respSource if localmag is to synthesize 
    407   Wood-Anderson traces. 
     443}}} 
     444 
     445FILE 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. 
     446 
     447EWDB: Query an Earthworm Database for reponse information. Not currently implemented. 
     448{{{ 
     449Default: none, you must specify respSource if localmag is to synthesize Wood-Anderson traces. 
    408450Example: File /earthworm/responses %S_%C_%N.pz 
    409 RingInName ring Earthworm setup 
    410 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. 
     451}}} 
     452 
     453'''!RingInName [ring]'''[[BR]] 
     454Function: Earthworm setup 
     455 
     456Tells 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. 
     457{{{ 
    411458Default:  none 
    412459Example:  RingInName HYPO_RING 
    413 RingOutName ring        Earthworm setup 
    414 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. 
     460}}} 
     461 
     462'''!RingOutName [ring]'''[[BR]] 
     463Function: Earthworm setup 
     464 
     465Tells 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. 
     466{{{ 
    415467Default:  none 
    416468Example:  RingOutName MAG_RING 
    417 SACsource DIR FORMAT    Miscellaneous Commands 
     469}}} 
     470 
     471'''SACsource [DIR FORMAT]'''[[BR]] 
     472Function: Miscellaneous Commands 
     473 
    418474Tells 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. 
     475 
    419476The 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. 
    420  
     477{{{ 
    421478Default:  none 
    422479Example: SACsource /earthworm/data/98042703361 %S.%C.%N 
    423  
    424  
    425  
    426 saveTrace ST [params] DIR FORMAT        Event and Trace Commands 
     480}}} 
     481 
     482'''saveTrace [ST [params] DIR FORMAT]'''[[BR]] 
     483Function: Event and Trace Commands 
     484 
    427485Tells 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: 
    428 SAC baseDir dirFormat filename-format 
    429 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. 
    430 baseDir 
    431 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. 
    432 dirFormat 
    433 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: 
    434 %C 
     486 
     487SAC 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. 
     488 
     489baseDir: 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. 
     490 
     491dirFormat: 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: 
     492 
     493%C[[BR]] 
    435494Century number (the year divided by 100 and truncated to an integer as a decimal number [1,99]); single digits are preceded by 0. 
    436 %d 
     495 
     496%d[[BR]] 
    437497Day of month [1,31]; single digits are preceded by 0. 
    438 %h 
     498 
     499%h[[BR]] 
    439500Locale's abbreviated month name. 
    440 %H 
     501 
     502%H[[BR]] 
    441503Hour (24-hour clock) [0,23]; single digits are preceded by 0. 
    442 %i 
     504 
     505%i[[BR]] 
    443506The Earthworm event ID. Currently this event ID can only be read from a hyp2000 archive message. 
    444 %j 
     507 
     508%j[[BR]] 
    445509Day number of year [1,366]; single digits are preceded by 0. 
    446 %m 
     510 
     511%m[[BR]] 
    447512Month number [1,12]; single digits are preceded by 0. 
    448 %M 
     513 
     514%M[[BR]] 
    449515Minute [00,59]; leading zero is permitted but not required. 
    450 %R 
     516 
     517%R[[BR]] 
    451518Time as %H:%M 
    452 %S 
     519 
     520%S[[BR]] 
    453521Seconds [00,61] 
    454 %T 
     522 
     523%T[[BR]] 
    455524Time as %H:%M:%S 
    456 %u 
     525 
     526%u[[BR]] 
    457527Weekday as a decimal number [1,7], with 1 representing Sunday. 
    458 %U 
     528 
     529%U[[BR]] 
    459530Week number of year as a decimal number [00,53], with Sunday as the first day of week 1. 
    460 %v 
     531 
     532%v[[BR]] 
    461533The version of the Earthworm event ID. Currently this version of the event ID can only be read from a hyp2000 archive message. 
    462 %V 
     534 
     535%V[[BR]] 
    463536Week 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. 
    464 %w 
     537 
     538%w[[BR]] 
    465539Weekday as a decimal number [0,6], with 0 representing Sunday. 
    466 %W 
     540 
     541%W[[BR]] 
    467542Week number of year as a decimal number [00,53], with Monday as the first day of week 1. 
    468 %y 
    469 Year within century [00,99]. 
    470 %Y 
     543 
     544%y[[BR]] 
     545Year [[BR]]within century [00,99]. 
     546 
     547%Y[[BR]] 
    471548Year, including the century (for example 1993), 
    472 filename-format 
    473 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. 
     549 
     550filename-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. 
     551 
    474552Localmag 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. 
     553{{{ 
    475554Default:  command is absent (no Wood-Anderson traces are saved) 
    476555Example: SAC /earthworm/SAC/W-A %Y%j%i %S.%C.%N 
    477556Example: SAC /earthworm/SAC/W-A %i_%v  %S.%C.%N 
    478  
    479  
     557}}} 
    480558 
    481559saveXMLdir directory    Event and Trace Commands