This page refers to the old SeisComP 3 version, and may no longer be accurate.
See seiscomp.de for the latest version.
scwfparam
scwfparam is a SeisComP module that computes
- peak ground acceleration (PGA)
- peak ground velocity (PGV)
- relative displacement elastic response spectrum (DRS)
- pseudo absolute acceleration elastic response spectrum (PSA)
in real-time or offline. It includes a process scheduler and handles reprocessing of data in a smart way. It supports ShakeMap XML output as documented in the ShakeMap manual each time a new set of data is available.
Configuration
All values in square brackets are the default values.
- wfparam.streams.whitelist (list) [""]
- wfparam.streams.blacklist (list) [""]
-
Defines the white- and blacklist of data streams to be used.
The rules to decide if a stream is used or not are the following:
- if whitelist is not empty and the stream is not on the whitelist, don't use it, ok otherwise
- if blacklist is not empty and the stream is on the blacklist, don't use it, ok otherwise
Examples:# Disable all SH streams wfparam.streams.blacklist = *.*.*.SH?
# Disable all SH streams and BH on station STA01 wfparam.streams.blacklist = *.*.*.SH?, *.STA01.*.BH?
# Disable network AB wfparam.streams.blacklist = AB.*.*.*
- wfparam.totalTimeWindowLength (integer) [360]
- Default value of total time window length in seconds if wfparam.magnitudeTimeWindowTable is not specified. This times window includes wfparam.preEventWindowLength.
- wfparam.magnitudeTimeWindowTable (list) []
-
Magnitude dependent time window table. The format is "mag1:secs1, mag2:secs2, mag3:secs3".
If a magnitude falls between two configured magnitudes the time window of the lower magnitude
is then used. No interpolation takes place. Magnitude outside the configured range are clipped
to the lowest/highest value.
Example: wfparam.magnitudeTimeWindowTable = 3:100, 4:200, 5:300
- wfparam.preEventWindowLength (integer) [60]
- The pre event time window length in seconds.
- wfparam.maximumEpicentralDistance (integer) [400]
- The maximum epicentral distance in km of a station being considered for processing. This value is used if wfparam.magnitudeDistanceTable is not specified.
- wfparam.magnitudeDistanceTable (list) []
-
Analogue to wfparam.magnitudeTimeWindowTable but instead giving a time window, the
distance in km is specified.
Example: wfparam.magnitudeDistanceTable = 3:400, 4:450, 5:500
- wfparam.saturationThreshold (float) [80]
- Relative saturation threshold in percent. If the absolute raw amplitude exceeds X% of 223 counts the station will be excluded from processing. This assumes a 24bit datalogger.
- wfparam.STAlength (float) [1]
- Specifies the STA length in seconds of the applied STA/LTA check.
- wfparam.LTAlength (float) [60]
- Specifies the LTA length in seconds of the applied STA/LTA check.
- wfparam.STALTAratio (float) [3]
- Specifies the minimum STALTA ratio to be reached to further process a station.
- wfparam.dampings (list) [5]
-
Specifies a list of damping values (in percent) for computation of the relative displacement elastic
response spectrum.
Example: wfparam.dampings = 5, 10, 15
- wfparam.naturalPeriods (integer) [100]
-
Specifies the number of natural periods for computation of the relative displacement
elastic response spectrum between Tmin and Tmax.
If fixed is given then a fixed list of periods is used:
0, -1, 0.01, 0.02, 0.03, 0.04, 0.05, 0.075, 0.1, 0.11, 0.12, 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 0.19, 0.2, 0.22, 0.24, 0.26, 0.28, 0.3, 0.32, 0.34, 0.36, 0.38, 0.4, 0.42, 0.44, 0.46, 0.48, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2, 2.2, 2.4, 2.6, 2.8, 3, 3.2, 3.4, 3.6, 3.8, 4, 4.2, 4.4, 4.6, 4.8, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10
- wfparam.naturalPeriods.log (boolean) [false]
- Defines if a linear spacing or logarithmic spacing between Tmin and Tmax is used. The default is a linear spacing. The logarithmic spacing will fail if either Tmin or Tmax is 0.
- wfparam.Tmin (float) [0]
- Specifies the minimum period (Tmin) in seconds for computation of the relative displacement lastic response spectrum.
- wfparam.Tmax (float) [5]
- Specifies the maximum period (Tmax) in seconds for computation of the relative displacement elastic response spectrum.
- wfparam.afterShockRemoval (boolean) [true]
- Enables/disables aftershock removal (Figini, 2006; Paolucci et al., 2008)
- wfparam.eventCutOff (boolean) [true]
- Enables/disables pre-event cut-off. A hardcoded sta/lta algorithm (with sta=0.1s, lta=2s, sta/lta threshold=1.2) is run on the time window defined by (expected_P_arrival_time – 15 s). The pre-event window is hence defined as [t(sta/lta =1.2) - 15.5 s, t(sta/lta =1.2) - 0.5 s].
- wfparam.filter.order (integer) [4]
- Specifies the filter order of the general filter.
- wfparam.magnitudeFilterTable (list) [0:0.2;0.8fNyquist,3:0.1;0.8fNyquist,5:0.05;0.8fNyquist,7:0.025;0.8fNyquist]
-
Magnitude dependent filter table. The format is
"mag1:fmin1;fmax1, mag2:fmin2;fmax2, mag3:fmin3;fmax3".
If a magnitude falls between two configured magnitudes the filter
of the lower magnitude is then used. No interpolation takes place.
Magnitude outside the configured range are clipped to the lowest/highest
value.
Frequency values are given as simple positive doubles (Hz is assumed) or with suffix "fNyquist" which is then multiplied by the Nyquist frequency of the data to get the final corner frequency.
- wfparam.filter.loFreq (float) [0.025]
- Specifies the frequency of the general hi-pass filter. If this parameter is equal to 0 the hi-pass filter is not used. If suffix "fNyquist" is used then the value is multiplied by the Nyquist frequency of the data to get the final corner frequency of the filter.
- wfparam.filter.hiFreq (float) [40]
- Specifies the frequency of the general lo-pass filter. If this parameter is equal to 0 the lo-pass filter is not used. If suffix "fNyquist" is used then the value is multiplied by the Nyquist frequency of the data to get the final corner frequency of the filter.
- wfparam.sc.order (integer) [4]
- Specifies the filter order of the sensitivity correction filter.
- wfparam.sc.loFreq (float) [0.025]
- Specifies the frequency of the sensitivity correction hi-pass filter. If this parameter is equal to 0 the hi-pass filter is not used. If suffix "fNyquist" is used then the value is multiplied by the Nyquist frequency of the data to get the final corner frequency of the filter.
- wfparam.sc.hiFreq (float) [0.8fNyquist]
- Specifies the frequency of the sensitivity correction lo-pass filter. If this parameter is equal to 0, the lo-pass filter is disabled. If suffix "fNyquist" is used then the value is multiplied by the Nyquist frequency of the data to get the final corner frequency of the filter.
- wfparam.deconvolution (boolean) [true]
- Enables/disables deconvolution. If a channel does not provide full response information it is not used for processing.
- wfparam.filtering.noncausal (boolean) [false]
- Enables non-causal filtering in the frequency domain.
wfparam.filtering.taperLength (double) [-1]:
Defines the cosine taper length in seconds if non-causal filters are activated applied on either side of the waveform. If a negative length is given 10 percent of the pre-event window length is used on either side of the waveform.
wfparam.filtering.padLength (double) [-1]:
The length of the zero padding window in seconds applied on either side of the waveform if non-causal filters are activated. If negative, it is computed following Boore (2005) as 1.5*order/corner-freq and applied half at the beginning and half at the end of the waveform.
- wfparam.cron.wakeupInterval (integer) [10]
- Specifies the interval in seconds to check/start scheduled operations.
- wfparam.cron.eventMaxIdleTime (integer) [3600]
- Specifies the maximum allowed idle time of a process before removed. The idle time is calculated if no further processing is scheduled and computes as: [now]-lastRun.
- wfparam.acquisition.initialTimeout (integer) [30]
- Specifies the initial acquisition timeout. If the acquisition source (eg Arclink) does not respond within this threshold with waveforms, the request is discarded.
- wfparam.acquisition.runningTimeout (integer) [2]
- Specifies the acquisition timeout when waveforms are being transfered. If no new waveforms arrive within this threshold, the request is aborted. This is important if a Seedlink connection is configured which can block the application for a very long time if at least one requested channel has no data. Seedlink does not finished the request until all data has been sent. When data will arrive for a particular channel is not known.
- wfparam.cron.logging (boolean) [true]
-
Enables/disables updating of a cron log file. This file will be created under
~/.seiscomp3/log/[appname].sched
and contains information about the scheduled events and the processing queue. The file is updated each n seconds, where n = wfparam.cron.wakeupInterval. - wfparam.cron.updateDelay (integer) [60]
- Specifies the delay in seconds to delay processing if a new authoritative origin arrives for an event.
- wfparam.cron.delayTimes (list) []
-
Specifies a list of delay times in seconds relative to event time to trigger the
processing. When the first origin of an event arrives this list is used to construct
the crontab for this event.
Example: wfparam.cron.delayTimes = 60, 120, 300, 3600
- wfparam.output.messaging (boolean) [false]
-
Enables messaging output which creates objects of the StrongMotionParameters
data model extension (defined by SED) and sends them to scmaster. In order to
save the objects to the database, scmaster needs to load the dmsm plugin and
the corresponding database schema must be applied.
The default message group is AMPLITUDE. To change this group redefine connection.primaryGroup.
- wfparam.output.waveforms.enable (boolean) [false]
- Enables/disables the output of processed waveforms.
- wfparam.output.waveforms.path (string) [@LOGDIR@/shakemaps/waveforms]
- Specifies the waveform output path. This parameter is only used if wfparam.output.waveforms.enable is true.
- wfparam.output.waveforms.withEventDirectory (boolean) [false]
- Enables/disables the creation of an event directory (named with eventID) when storing the processed waveforms. This parameter is only used if wfparam.output.waveforms.enable is true.
- wfparam.output.spectra.enable (boolean) [false]
- Enables/disables the output of spectra (psa, drs). The output format is a simple ascii file where the first column is the period and the second column the corresponding value.
- wfparam.output.spectra.path (string) [@LOGDIR@/shakemaps/waveforms]
- Specifies the spectra output path. This parameter is only used if wfparam.output.spectra.enable is true.
- wfparam.output.spectra.withEventDirectory (boolean) [false]
- Enables/disables the creation of an event directory (named with eventID) when storing the spectra. This parameter is only used if wfparam.output.spectra.enable is true.
- wfparam.magnitudeTolerance (float) [0.5]
- Defines the magnitude tolerance to completely reprocess an event with respect to the last state.
- wfparam.output.shakeMap.enable (boolean) [true]
- Enables/disables ShakeMap XML output.
- wfparam.output.shakeMap.maximumOfHorizontals (boolean) [false]
- If enabled the maximum PGV, PGA, PSA03, PSA10 and PSA30 of both horizontal components is used in the final output. Otherwise all components are stored individually.
- wfparam.output.shakeMap.path (string) [@LOGDIR@/shakemaps]
- Specifies the ShakeMap XML output path. This is only used if wfparam.output.shakeMap.enable is set to true.
- wfparam.output.shakeMap.script (string) []
-
Specifies the path to a script that is called whenever a new ShakeMap XML
is available. The script is called with 3 parameters:
(1) EventID
(2) modified ShakeMap eventID
(3) path to event directory (where input/event.xml and input/event_dat.xml lives)
The event files are not deleted by the application. The ownership goes to the called script.
- wfparam.output.shakeMap.synchronous (boolean) [true]
- Enables/disables synchronous or asynchronous script calls. If enabled, be careful not to spend too much time in the script. The application is blocked while the script is running.
Commandline
The following options are available in addtion to general application options.
- --order
- Overrides param wfparam.filter.order
- --lo-filter
- Overrides param wfparam.filter.loFreq
- --hi-filter
- Overrides param wfparam.filter.hiFreq
- --sc-order
- Overrides param wfparam.sc.order
- --sc-lo-filter
- Overrides param wfparam.sc.loFreq
- --sc-hi-filter
- Overrides param wfparam.sc.hiFreq
- --expiry,x [1]
- Time span in hours after which objects expire.
- --event-id, -E []
- EventID to process. The event must be available either from the database or the passed event parameters XML file with --ep.
- --ep []
- EventParameters (XML) to load.
- --offline [0]
- Do not connect to the messaging and to the database. Only the given event-id is processed and not scheduling is applied. One run, one result set.
- --test [0]
- Test mode, no messages are sent.
Scheduling
When the module is not started in offline mode, the processing of events is scheduled following the configured rules. Parameters that influence the scheduling are:
- wfparam.cron.wakeupInterval
- wfparam.cron.updateDelay
- wfparam.cron.delayTimes
The wake-up interval specifies when the scheduler is called to check if a process is about to be started or stopped. The default is 10 seconds.
The scheduler checks then all scheduled jobs, adds a job to the processing queue if the next run time is not in the future and removes all scheduled jobs with timestamps in the past. The process queue contains all jobs that are about to be executed. Because waveform acquisition is a time- and memory-costly operation only one process can run at a time. Once a process finished, the next process in the queue is executed (if any). When a process is started, it fetches the latest event parameters (origin time, magnitude, location).
To add processes to the scheduler, the module distinguishes two cases:
- Process creation (new event or updated event seen the first time)
- Process update (event updates after an process has been created)
Process creation
When a new event or an event update is received which does not have an associated process yet, a new process is created. The event time (Origin[Event.preferredOriginID].time) is used to build the default schedule according to wfparam.cron.delayTimes.
for each time in wfparam.cron.delayTimes: add_cron_job(process, Origin[Event.preferredOriginID].time + time)
Process update
If a process for an event already exists, the next run time is the current time plus wfparam.cron.updateDelay. Before adding this job to the scheduler the application checks if the next scheduled runtime is at least wfparam.cron.updateDelay seconds after the new run time. If not, a new job is not addded to the scheduler. Pseudo code to illustrate the strategy is given below.
event_updated(event):
p = process_for_event(event)
# The schedule for process p could be {T1,T2,T3,T4}
now = get_current_time()
next_run = now + wfparam.cron.updateDelay
# Process currently suspended?
if isEmpty(p.schedule):
p.schedule.add(next_run)
elif (p.schedule[0] - next_run) > wfparam.cron.updateDelay:
p.schedule.prepend(next_run)
else:
# Do nothing, ignore the event update
pass
Processing
The processing can be divided into the following steps:
- Collect all stations within the configured maximum distance (wfparam.maximumEpicentralDistance or wfparam.magnitudeDistanceTable)
- Remove already processed channels
- Find the velocity and acceleration stream with the highest sampling frequency
- The sensor unit is used to distinguish between velocity and acceleration streams (M/S, M/S**2)
- Use all allowed components (wfparam.streams.whitelist, wfparam.streams.blacklist) of each stream
- Compute expected P arrival time if no pick is available
- Start waveform acquisition
- If the configured time window for one stream is complete, do (optional steps are written italic)
- Check saturation depending on wfparam.saturationThreshold
- Search maximum raw value (in counts)
- Apply gain
- Check STA/LTA threshold 5 seconds around P
- If velocity, differentiate data to acceleration
- Compute pre-event cut-off if enabled
- Compute offset of pre-event time window
- Compute signal duration and check for aftershocks
- Deconvolution using spectral division of FFT spectrum and transfer function
- Apply optional sensitivity correction filter (lo-, hi- or bandpass)
- Apply optional lo-pass, hi-pass or band-pass filter
- Compute PGA/PGV
- Calculate response spectra
- If acquisition finished
- Collect all values (also recently processed values)
- Results from velocity streams are always preferred over acceleration streams if both are available (eg. co-located stations)
- Generate ShakeMap event and station XML
- Unless wfparam.output.shakeMap.maximumOfHorizontals is set to true all processed streams are included in XML
- Call ShakeMap script and pass eventID and event ID path
- Collect all values (also recently processed values)
The channel is considered to be processed if the last step succeeded.
Waveform archival
If wfparam.output.waveforms.enable is set to true all processed waveforms are stored in the configured output directory wfparam.output.waveforms.path. The naming convention of a channel MiniSEED file is:
[EventDateTime]_[net]_[sta]_l[oc][cha]_[filterType][filterOrder]_[CornerFrequencies].mseed
If wfparam.output.waveforms.withEventDirectory is set to true, an event directory with the eventID is created additionally where the channel files are stored under.
Either:
/path/to/waveforms/file1.mseed
/path/to/waveforms/file2.mseed
...
or
/path/to/waveforms/eventid/file1.mseed
/path/to/waveforms/eventid/file2.mseed
...
The MiniSEED file contains uncompressed float 4096 byte records.
Example:
Event time: 2011-11-21 08:30:00
Network: CH
Station: SNIB
Location: _ _
Channel: HGZ
Filter: hi-pass
Order: 2
Corner frequencies: 0.025
Filename: 20111121083000_CH_SNIB_HGZ_HP2_0.025.mseed
Database
scwfparam can make use of the database schema extension for strong motion parameters.
In order to prepare the database the extension schema must be applied. The database schema is installed in seiscomp3/trunk/share/db/wfparam/*.sql. Login into the database backend and source the .sql file corresponding to the used database backend.
In order to enable scmaster to handle messages containing objects for strong motion parameters load the dmsm (data model strong motion) plugin as follows in scmaster.cfg:
plugins = ${plugins}, dmsm
scmaster must be restarted to activate the plugin.
To activate scwfparam to send messages with strong motion objects, set
wfparam.output.messaging = true
in scwfparam.cfg.
ShakeMaps
The ShakeMap XML is generated according the documentation of version 3.5 if wfparam.output.shakeMap.enable is set to true.
Below an example is given of an event XML and a station XML. The data was generated from a playback and does not describe a real event.
Event XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE earthquake SYSTEM "earthquake.dtd">
<earthquake id="gfz2011oasp" lat="38.916" lon="40.0711"
depth="10.3249" mag="5.80361" year="2011"
month="7" day="19" hour="14" minute="54"
second="21" timezone="GMT"
locstring="tst2011oasp / 38.916 / 40.0711"
/>
Station XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE earthquake SYSTEM "stationlist.dtd">
<stationlist created="" xmlns="ch.ethz.sed.shakemap.usgs.xml">
<station code="JMB" name="JMB" lat="42.467" lon="26.583">
<comp name="BHZ">
<acc value="0.0175823522" flag="0"/>
<vel value="0.0265134476" flag="0"/>
<psa03 value="0.0177551343" flag="0"/>
<psa10 value="0.0179450342" flag="0"/>
<psa30 value="0.0507100318" flag="0"/>
</comp>
</station>
<station code="BUD" name="BUD" insttype="STS-2/N"
lat="47.4836" lon="19.0239">
<comp name="BHZ">
<acc value="0.0018418704" flag="0"/>
<vel value="0.0012123935" flag="0"/>
<psa03 value="0.0019287320" flag="0"/>
<psa10 value="0.0033152716" flag="0"/>
<psa30 value="0.0027636448" flag="0"/>
</comp>
</station>
<station code="ANTO" name="ANTO" lat="39.868" lon="32.7934">
<comp name="BHZ">
<acc value="0.0322238962" flag="0"/>
<vel value="0.0250842840" flag="0"/>
<psa03 value="0.0326696355" flag="0"/>
<psa10 value="0.0621788884" flag="0"/>
<psa30 value="0.0903777107" flag="0"/>
</comp>
</station>
<station code="GNI" name="GNI" lat="40.148" lon="44.741">
<comp name="BHZ">
<acc value="0.0760558909" flag="0"/>
<vel value="0.0273735691" flag="0"/>
<psa03 value="0.0818660133" flag="0"/>
<psa10 value="0.1230812588" flag="0"/>
<psa30 value="0.1682284546" flag="0"/>
</comp>
</station>
</stationlist>
Examples
- Running scwfparam offline with a multiplexed miniseed volume, an event xml
and an inventory xml file. A hi-pass filter of 0.1hz (10secs) is used. Processing
starts immediately and the application finishes when processing is done. The
scheduler is disabled in offline mode.
scwfparam --offline -I vallorcine.mseed --inventory-db vallorcine_inv.xml \ --ep vallorcine.xml -E "Vallorcine.2005.09.08" \ --lo-filter 0.1 --hi-filter 0
- Running for a given event with scheduling enabled. Only the given event will be
processed.
scwfparam -I arclink://localhost:18001 -E gfz2011oeej\ -d mysql://sysop:sysop@localhost/seiscomp3
- For running in real-time it is enough to add the module to the client list of the trunk package in seiscomp config.
- Running with remote Arclink server
To use a remote Arclink server it is enough to configure the record stream with -I:scwfparam --offline -I vallorcine.mseed --inventory-db vallorcine_inv.xml \ --ep vallorcine.xml -E "Vallorcine.2005.09.08" \ -I "arclink://arclink.ethz.ch:18002"Note that the default acquisition timeout of 30 seconds might not be enough to get all the requested data. If necessary, increase the value with parameter wfparam.acquisition.initialTimeout. This can also be reached on command line:scwfparam --offline -I vallorcine.mseed --inventory-db vallorcine_inv.xml \ --ep vallorcine.xml -E "Vallorcine.2005.09.08" \ -I "arclink://arclink.ethz.ch:18002" --wfparam.acquisition.initialTimeout=300
- Running with remote Seedlink server
To use a remote Seedlink server it is enough to configure the record stream with -I:scwfparam --offline -I vallorcine.mseed --inventory-db vallorcine_inv.xml \ --ep vallorcine.xml -E "Vallorcine.2005.09.08" \ -I "slink://geofon.gfz-potsdam.de:18000"
