(last revised June 6, 2011)
Localmag can run as an Earthworm module or as a standalone program. It can be used in several different ways for calculating the local (or Richter) magnitude of an event. There are a large number of options that can be specified in the configuration file or on the command line for this program. But don't let them scare you: once you decide how you want to use localmag, you will need to set only a portion of these parameters.
When run as an Earthworm module, localmag connects to a transport ring and reads HYP2000_ARC messages, produced by hypoinverse. Localmag also uses the transport ring for sending heartbeat and status messages as is common practice for Earthworm modules. Localmag reads the summary line of the HYP2000_ARC message, starts collecting trace data from one or more wave_servers, and processes that data for that event. Once the processing (described below) is completed, the localmag module becomes dormant, waiting for the next event to arrive and beating its heart at the specified interval.
As a standalone program, localmag is run one or more times for each event. It can get event information from a number of different sources: HYP2000_ARC messages (read from standard input), SAC files, an Earthworm Database among others. Localmag can get trace data (if necessary) from wave_servers, SAC files of raw trace data or previously synthesized Wood-Anderson traces, or from other sources. And instead of reading trace data, localmag can read Wood-Anderson amplitudes (from SAC files or other sources) and compute local magnitudes directly from these. These methods could be used to as part of the review process after localmag module generated the initial automatic local magnitude.
After localmag prepares (the new data for processing by checking for gaps (if the data was obtained from wave servers) and removes the mean. Then localmag synthesizes these traces into Wood-Anderson traces. This conversion is done by a frequency domain convolution to remove the original instrument response and replace it with the Wood-Anderson response. The frequency response function (generated as an intermediate step in this process) may optionally have a cosine taper applied to either or both the low and high ends of the frequency range.
When the synthetic Wood-Anderson traces have been returned to the time domain, the peak amplitude is located for each trace. The search for peak amplitude is done within a time window related to the estimated Sg phase arrival time. One or two `peak' values may be located. First, the largest (absolute value) zero-to-peak is found. This zero-to-peak value is compared to the largest zero-to-peak found before the estimated P arrival. If the event zero-to-peak does not exceed the pre-event zero-to-peak by the factor z2pThresh, then that trace is not used for local magnitude calculations and no further peak searches are performed for that trace. This threshold should prevent the use of station/channels that are far from a small event or have a lot of background noise. It may also prevent localmag from processing traces where one event is preceeded by the coda of another large event.
The second peak value is a "sliding window" search, in which the largest plus-to-minus or minus-to-plus swing is found within a specified interval (normally 0.8 seconds, the free period of the Wood-Anderson instrument.) The motivation for this algorithm is to reduce the chances of picking a noise glitch instead of seismic signal. When computing the local magnitude, localmag uses one half of this peak-to-peak signal. Note that one half of peak-to-peak will usually be a smaller value than the largest zero-to-peak value.
The Wood-Anderson traces may optionally be saved in SAC (or other format) files, along with the peak amplitude picks, for review by human beings. If pick locations are changed or bad traces are thrown out, the traces or picks can be read back in by localmag to update the calculated magnitude.
Besides the peak amplitude values from the Wood-Anderson traces, localmag needs the -log(A0) values to correct for attenuation with station-hypocenter distance. The table of these values is read from a file. Thus regional networks can use their own attenuation relations in place of the one Richter (later Richter & Guttenburg) developed of Southern California. This table can be configured to use station to epicenter distance or station to hypocenter distance. For each horizontal component that has a valid trace (no data gaps, not clipped, sufficient event signal) localmag computes a local magnitude value.
The magnitude values from all the traces are combined in the following manner. For stations with traces from both horizontal components (East and North) of a given instrument band (broadband or accelerometer), a station `band' local magnitude is found in one of two ways. Either the mean of the component magnitudes is used, or the mean of the component amplitudes is used to compute a station magnitude. If a station has more than one band of instrument (both broadband and accelerometer), the station magnitude is always the mean of the band magnitudes.
Finally, all the station magnitude values are averaged; the standard deviation and the median are computed. These results are logged in all cases. When localmag is connected to an Earthworm transport ring, the results are sent to transport as a LOCALMAG message; other forms of output may be selected as well.
Localmag will wait for trace data to appear in the wave_servers, when run as an Earthworm module. It computes the time need to wait from event origin until the trace window has propagted to the maximum distance to be used. When an event message arrives, localmag compares the origin time with the system time and sleeps until sufficient time has passed. This means that you should run localmag on a computer which is accurately set to CUT, the same time as is used to timestamp phase picks.
Some warnings about this program: Localmag uses a quite a bit of CPU time, depending on the number and duration of traces requested. If this and other CPU-intensive modules such as gmaew are running on the same machine, they will have a significant impact on the machine load after one or more large events. Until Earthworm has some sort of scheduling system, you may want to run these programs at reduced priority.
When run as an earthworm module, localmag will gradually use increasing amounts of memory. This is normal. It is keeping information about FFT factors and trig functions, so that these do not need to be recalculated for each trace calculation.
I give thanks here to Jim Pechmann of UUSS for providing many useful comments and his SAC macros for local magnitude calculations. Many features of this program are the result of his ideas.
While any manufacturer or instument might be used as an illustrative example
for creating response files, we select a Guralp CMG5TD which has the following
manufacturer supplied calibration information:
Poles (no Zeros) in Hz: -63.7927 +- 90.3864i -209.656 + 0i -755.898 + 0i Normalizing factor at 1Hz: 1.9396e9
To convert from Hz to radians, multipy each pole and zero by 2pi.
The normalizing factor must also be scaled to account for the discrepency
in the number of factors of 2pi in the poles (denominator ) and zeros
(numerator) of the transfer function. Multiply A0 by 2pi*(np-nz).
That is, A(radians) = A(Hz) * (2*pi)^(np-nz) where np and nz are
the number of poles and number of zeros respectively. So, the response
of a 5td (without the sensor gain) in radians is
Poles (no Zeros) in radians: -400.8214 +- 567.9145i -1317.3 + 0i -4749.4 + 0i Normalizing factor at 1Hz: 3.0230e12
To convert from acceleration to displacement, multiply the acceleration response by two factors of i*omega (-w^2). Equivalently, "add" two zeros.
The 5td sensor has a constant of about 0.256 V/m/s2.
The DM24 has a digitizer constant of about 1.9e-6 volts/count.
So the overall system gain (excludes any pole/zero factors) is about 7.422e-6 m/s^2 per count (or about 7.422 micron/s per count).
Soo, the constant in the complete transfer function (in microns/count and radians) is the normalizing factor (radians) * 1e6 (microns/meter) * 7.422e-6 (m/s^2 per count) = 7.422 * 3.0230e12 = 2.2437e13.
Sooo, the complete transfer function for a cmt5td set to +-2g will be (in microns/count and radians) in sac format:
ZEROS 2 POLES 4 -400.8214 -567.9145 -400.8214 567.9145 -1317.3 0.0 -4749.4 0.0 CONSTANT 2.2437e13
The earthworm transfer library (used by localmag, gmew, etc) expects responses to be in units of nanometers of displacement. The cmg5td response is then (in nanometers/count and radians),
ZEROS 2 POLES 4 -400.8214 -567.9145 -400.8214 567.9145 -1317.3 0.0 -4749.4 0.0 CONSTANT 2.2437e16
Note that we ignored the effect of the anti-aliasing filter which is a brickwall lowpass FIR at the Nyquist frequency. It should be included to be correct but we ignore it for the sake of simplicity.
Note that if you have the IRIS program rdseed and a dataless seed volume for your station you can get
out the appropriate format SAC poles and zeroes file using the command:
rdseed -pf datalessNote that you will still need to add zeroes (e.g. one if going from velocity, two if going from acceleration) to get it to displacement and then must convert units to nanometers.
1 nanometer = 1.0 x 10-9 meters. So if we see Input Units of METERS and the CONSTANT is 5.356916e+17, then Nanometers is: CONSTANT 5.356916e+26
Module Index | Localmag Commands