ccloc

Event detector based on template matching by waveform cross-correlation.

Description

ccloc detects events by template matching. It finds similarities of waveforms to templates from pre-defined master events based on cross-correlation of characteristic functions.

ccloc declares a new origin if the waveform fit parameters are above the configured thresholds. The origin location and depth are taken from the matched master event whereas the origin time is determined from the processed time window.

An efficient configuration strategy is described in Getting started.

Note

The hypocenter location and time are derived from the master template not from locating. Relocate the origin for more precise parameters. For relocation provide the origin to other modules such as scanloc or screloc or use scolv for interactive analysis.

Event type

The new origin contains the event type of the master event as a comment. The type comment is evaluated by the evccloc plugin for scevent. When applying this plugin the type of the event is set according to the type of the master event. In this way, ccloc can also be used for event discrimination.

Magnitudes

The magnitude is computed from the ratio of PGV amplitudes measured on the continuous data to the PGV amplitudes measured on the data of the master event:

(1)M = M_{master} + \frac{1}{N} \sum_{i=1}^{N} \log_{10} \frac{PGV_{continuous_i}}{PGV_{master_i}}

Modes of operation

ccloc can run in real time as a daemon module or on the commandline or offline for playbacks. See the examples for some applications.

Workflow

The full workflow consists of

  1. Data processing
  2. Cross-correlation detection
  3. Optional pick refinement
  4. Sending of origins.

ccloc subscribes to all streams (channels) for which the master event has picks. 3-component data are considered if use3C is enabled. On each received record the common time window of all channels is computed. If sufficient data are available the time windows are processed.

_images/stepping.png

Processing of a data time window of contiuous channels. The step of each processing step is the time of one sample. See Data processing for how each time window is processed.

Each processed time window is matched with the master event. If the overall fit exceeds the configured threshold, the detector is started to search for the maximum fit within the configured timewindow. The timestamp of the maximum fit is taken as event time and an origin with a magnitude is sent to the messaging.

Data processing

The data processing consists of

  1. data selection
  2. filtering
  3. computation of the characteristic function used for detection.

For increased speed the data are processed according to the configuration in the time domain. The schema is illustrated below.

_images/processing.png

Processing schema in the time domain. data are the template waveforms and continuous input waveforms corrected for sensitivity. data are also the output waveforms used by subsequent steps.

Note

The processing is applied to the data of the master events as well as to the continuous data. Processing in the time-domain is much faster than in the frequency domain. Therefore, time-domain processing is currently supported.

Data selection

The data of the master event template and of the real-time data are selected and loaded according to the streams corresponding to the picks defined by the master event. The parameter use3C configured in the ccloc binding profile controls whether the data from all available stream components are loaded or only for the stream component on which the pick was defined. By default, use3C is enabled and all stream components are used. If disabled and the S-wave picks are defined on one horizontal component then the other complementary component is considered as well. If the S pick is defined on the vertical component, then only vertical-component data are considered.

Filtering

Raw waveforms can be filtered using SeisComP3 filters defined in processing.filter.definition. Bandstops at 50 Hz and 100 Hz are applied when enabling processing.filter.bandStop.

Characteristic functions

Supported characteristic functions are:

  1. Processed waveforms where the processing can comprise any SeisComP filters.
  2. Envelopes formed from processed waveforms.
  3. Logarithm applied to processed waveforms.

Processed waveforms

Processed waveforms can be used as characteristic function. Here, any available filter or filter chain can be provided by configuring the parameter processing.filter.definition. In this way more complex characteristic functions such as STALTA or user-defined envelopes can be formed.

As filter chains can be applied to waveforms and viewed in scolv or scrttv, they can be interactively designed and tested before.

Envelope

The cross-correlation can be computed on the seismograms itself or on the envelopes of the processed waveforms. Using the envelope of seismograms instead of the seismograms itself, the cross-correlation becomes less sensitive to small changes in the source location and in source mechanism between master signal and the earthquake to be detected. For envelope computation enable processing.envelope.enable.

ccloc computes the envelope in the time domain using a running root mean square:

(2)\hat{y}_i^j = \sqrt{ \frac{2}{N} \sum_{k = i-N}^i (y_k^j)^2 }

Here yij is the output signal of the single trace operation, which in this case is the envelope of the signal. ykj is the input signal of the single trace operation, which in this case is the filtered seismogram. i and j are counters for time and trace number, respectively. N is the number of samples used for the RMS. N is calculated as:

N = \frac{\text{processing.envelope.samplingFrequency}}{\text{processing.envelope.hiFreq}}

The parameters processing.envelope.samplingFrequency and processing.envelope.hiFreq are configurable.

Logarithm

By enabling processing.logarithm.enable and disabling processing.envelope.enable the logarithm of the processed waveforms is computed and used as characteristic function:

(3)y_i^j = sgn(y_i^j) \: ln|y_i^j|

Application of this single trace operation will generally amplify the noise level with respect to the signals from events. This may be an unwanted effect. On the other hand using this option increases the importance of small-amplitude waves like coda waves in comparison to direct P- and S-waves. It may also increase the importance of recordings at distant stations in comparison with close stations (if the network cross-correlation is applied).

Noise removal

If we use seismogram envelopes, the constant background noise level causes a problem in the computation of the cross-correlation. Even if we remove the mean value in the seismograms, a constant offset appears in the envelopes. This offset value in the envelopes corresponds to the standard deviation of noise in the original seismograms. Correlating a constant (noise) trace with the master event results in a large correlation coefficient possibly causing wrong detections. A simple solution to this problem is to remove the noise level from the master event traces as well as from the current time window traces. We estimate the noise level yj in a time window j before the potential signal at envelope trace yij:

(4)\overline{y^j} = \frac{1}{N_n}\sqrt{\sum_{i=1}^{N_n} y_i^j}

Here i is the counter for time samples, Nn is the number of time samples in the time window to estimate the noise level, and j is a counter for the traces (seismometers times components). Then we remove the noise level, which is a constant offset in the envelopes:

(5)\hat{y}_i^j = y_i^j - \overline{y^j}

Here, the time window, where we remove the offset (and where we later compute the correlation) is generally different from the time window, where we estimate the noise level.

Cross-correlation

After data processing, the processed waveform templates are cross-correlated with the measured waveform data.

Single trace

In a first step we compute the single trace cross-correlation coefficient with zero lag at channel j:

(6)R^j = \frac{1}{\sqrt{(\sum_{i=1}^N x_i^j x_i^j) \: (\sum_{i=1}^N y_i^j y_i^j)}} \: \sum_{i=1}^N x_i^j y_i^j

Here i is the sample index of the channel, N is the number of time samples in the used correlation time window, xj is the filtered seismogram or envelope of the master event after single trace operations described in Data processing, yj is the filtered seismogram or envelope of the current time window after applying the same operations as to the master traces, and j is a counter for the traces (seismometers times components).

This cross-correlation coefficient is computed for all traces j=1,...,J, where J/3 is the total number of stations of the master event, if we use three-component seismograms. Using three-component seismograms is controlled by parameter use3C defined in the ccloc binding profile.

The first condition for a detection is, that

(7)R^j > R_1,

for at least Jmin channels. Rj is defined in equation (6). R1 is the configurable input threshold detector.channelThreshold. It is typically chosen in the order of R1 ≈ 0.6 - 0.8. Jmin is the minimum number of matched seismograms, that is where the event is detected. j>=Jmin is required. Jmin is implicitly given through detector.minimumChannelRatio as the minimum ratio between matched and available channels.

In other words: These condition require that the current time window and the master event shows similar waveforms (Rj > R1) for at least Jmin seismograms. We use the parameter Jmin to account for the fact that some seismograms may show large local noise (Rj < R1), when a small earthquake occurs.

When the data transmission of some sensors is interrupted the respective correlation coefficient is set to zero: Rj = 0 < R1 and the result is similar to a local noise disturbance. A detection is only possible if the number of noisy or otherwise disturbed traces does not exceed J - Jmin.

Network

In a next step ccloc computes the network cross-correlation with zero lag, where two options, trace (A) and total (B), are available. The option is selected with processing.normalization.

Note

The network cross-correlation is only computed if the ratio of time window traces and master event traces does not fall below detector.minimumChannelRatio and if the ratio of time window stations and master event stations does not fall below detector.minimumStationRatio. Otherwise the network cross-correlation is set to 0.

In option A ccloc computes the average single trace cross-correlation coefficient of the Jmin traces with the highest single trace cross-correlation coefficient:

(8)R_{trace} &= \frac{1}{J_{min}} \sum_{j=1}^{J_{min}} R^j \\ &= \frac{1}{J_{min}} \sum_{j=1}^{J_{min}} \frac{1}{\sqrt{(\sum_{i=1}^N x_i^j x_i^j) \: (\sum_{i=1}^N y_i^j y_i^j)}} \: \sum_{i=1}^N x_i^j y_i^j

In option B ccloc computes the matrix cross-correlation with zero lag, where one dimension of the matrix is time and the other dimension are the different traces:

(9)R_{total} = \frac{1}{\sqrt{(\sum_{j=1}^{J_{min}} \sum_{i=1}^N x_i^j x_i^j) (\sum_{j=1}^{J_{min}} \sum_{i=1}^N y_i^j y_i^j)}} \sum_{j=1}^{J_{min}} \sum_{i=1}^N x_i^j y_i^j

The major difference between Rtrace and Rtotal is that in equation (8) the relative amplitudes between stations and components are neglected, whereas they are taken into account in equation (9).

Then, the second and third condition for a detection are:

(10)R_{trace} > \text{detector.threshold}

(11)R_{total} > \text{detector.threshold}

Here detector.threshold is a configurable threshold, which judges the network similarity and should be set to about detector.threshold ≈ 0.6 - 0.8.

Declaration of origins

Once the detector thresholds are met, a new origin is created containing the origin parameters, picks and arrivals as well as the event type of the master event as a comment.

The origin time is the time of the detection. The pick times are the derived from the traveltimes of the master event added to the origin time of the detection.

For differences in source location the matched and real arrivals may be significantly different. The matched picks may hence be of limited accuracy and of limited use for relocating. Therefore, the picks somewhat represent theoretical onsets and are flagged by adding a T to the beginning of the phase hint, e.g. TP and TS for P and S phases, respectively. Hereby, the original phase names, e.g. Pn, Sg, PKP, etc., originating from the master event are preserved.

All arrivals starting with T are given a weight of 0. Therefore, they cannot be used for relocation, e.g. by scanloc or screloc as typically no corresponding traveltime tables exist. Viewing these picks in scrttv or scolv provides more advanced control over the functioning of ccloc.

Apply repicking to refine the picks by the AIC method and make the refined picks applicable to locator routines. When repicking, a minimum score based on the repicked phases may be defined as a threshold which must be exceeded before sending the origins.

Note

The detections by template matching can only have phase detections for which the master event has arrivals. That is, if the master event misses an S arrival at a station, then the detection cannot have a TS arrival for the corresponding station.

Pick refinement

The T-picks found from template matching may be inaccurate. Therefore they can be re-picked by a second-stage AIC picker. Once the AIC can finds a pick, the leading T of the phase name is removed and the arrival is given a weight of 1. In this way, the re-picked phase picks are typically more accurate and can now be used for re-locating.

Note

Sending all T- and A-type picks may results in an unnecessary and large amount of output and is therefore disabled by default. Activate repicking.sendTheoreticalPicks to enable the sending.

As a result of re-picking one station may deliver two different picks for the same phase type with different given phase hints. Both picks are shown in scolv: gray for arrivals with weight 0 from template matching and red for automatically re-picked picks with weight 1.

The AIC configuration parameters are configured in the ccloc configuration and in the ccloc binding profile:

  1. enable repicking.enableAIC in the module configuration in order to activate re-picking by AIC
  2. set the ppicker.AIC.* parameters for re-picking P-type phases. The parameters are configured in the ccloc binging profile. The time window parameter are use with respect to the TP picks. Ensure that AIC windows for P wave do not overlap with S phases.
  3. set the spicker.AIC.* parameters for re-picking S-type phases. The parameters are configured in the ccloc binging profile. The time window parameter are use with respect to the TS picks. As the approximate arrival time is known from the template, the parameters spicker.AIC.step and spicker.AIC.minCnt are unused and can be ignored.

In contrast to the T-picks delivered from the detector, the refined picks are usually of higher accuracy. The original phase names from the master template are regained and a weight of 1 is given to the arrival. Therefore, the refined picks can be used for re-locating the new origin automatically by scanloc, screloc or manually in scolv.

The AIC picker also checks the signal-to-noise ratio. If the minimum SNR defined in the ccloc bindings profile is not reached, the pick is provided with a phase hint starting with A, e.g. APg instead of Pg. The corresponding arrival is given a weight of 0. Adding the prefix A prevents the pick from being used for relocation, e.g. by scanloc or screloc as typically no corresponding traveltime tables exist.

Showing these picks provides more advanced control over the functioning of ccloc.

_images/ccloc_scolv_arrivals.png

scolv picker window with TP, TS, P and S picks.

_images/ccloc_scolv_main.png

scolv main window with arrival information from TP, TS, P and S phases.

Configuration: Getting started

Stations participating in template matching must have ccloc bindings with detecEnable being activated. At least one master event must be configured. Multiple master events can be defined and processed in parallel to account for different waveforms or seismicity regions. For a verification of the configuration read the section Configuration: Verification.

To get started, it is sufficient to define a master template and a few general parameters:

  1. Create ccloc bindings to all stations participating in template matching. Activate detecEnable in the ccloc binding profiles.

  2. The master event by the eventID.

    1. Create an event profile. The name of the event profile is typically the eventID. For the new profile configure at least:

      1. event.$name.baseID for the ID of the event if the event parameters are read from the SeisComP3 database.

      2. event.$name.originID for the ID of the considered origin associated to the event. By default, the preferred origin is selected. However, the preferred origin may change by reprocessing or other origins may be specifically prepared for template matching. Therefore, it is recommended to provide a unique originID.

      3. event.$name.signalBegin and event.$name.signalEnd according to the waveform of the master event template. event.$name.signalBegin and event.$name.signalEnd are relative to the first picked P and the first picked S arrivals.

        *. If the master event contains no P arrival for a station, then the

        P arrival time is predicted from the first S arrival assuming vp/vs = 1.73.

        *. If the master event contains no S arrival for a station, then the

        S arrival time is predicted from the first P arrival assuming vp/vs = 1.73.

      The noise window (event.$name.noiseEnd, event.$name.noiseEnd) must be set carfully to account for any effects due to filtering (see section Filtering).

      Note

      Events may have several P and S picks on the same station, e.g. Pg, Pn, Sg or Sn. Currently only the first arriving P and the first arriving S picks are used. Late P and S arrivals are currently not considered.

    2. Configure events using the name of the event profile.

      When regularly clearing the database or the waveform archive, the master event information may get lost. In this case it is recommended to store the master event information and waveforms in files. Check below for the procedure.

  3. General parameters. The general parameters are inherited by the event profiles and the processing profiles where they can be overwritten. Configure

    1. processing.filter.definition to filter the raw data
    2. processing.envelope.samplingFrequency to resample the envelope if processing.envelope.enable = true. Resampling is performed by simply by removing or adding samples. Downsampling boosts the performance of ccloc.
    3. detector.fitWindow to allow searching for matches on all waveforms from all stations within that time window. This parameter is important to account for hypocentre differences with respect to the master event which will result in traveltime differences.
    4. detector.window to search for more detections after the initial trigger. ccloc will aggregate all found detections within detector.window and select the detection with the best overall match to create a new origin. All other detections will be ignored.
    1. Detection thresholds:
      1. detector.channelThreshold
      2. detector.threshold
      3. detector.minimumChannelRatio
      4. detector.minimumStationRatio

Optional parameters

  1. Data processing:
    1. Set parameter use3C in the ccloc binding profile to decide whether or not to use 3 components for matching. If disabled, only the component for which the selected origin of the master event has an arrival will be considered.
    2. Decide if matched phases should be refined by using an AIC repicker. Configure repicking.enableAIC accordingly. If repicking.enableAIC is enabled the AIC parameters must be configured in the ccloc bindings profiles.
  2. Event specific parameters:
    1. event.$name.group defining the membership of the master template to a group. The origins resulting from templates belonging to the same group are jointly evaluated if they were created within a timespan defined in processing.interval. Only the resulting origin with the highest overall match is send to the messaging.

Master event definition

The master event defines the template used for detection. It must be carefully selected being representative in terms of magnitude, data availability and waveform quality. When regularly clearing the database or the waveform archive, the master event information may get lost. In this case it is recommended to store the master event information and waveforms in files.

  1. Select a typical event as a master event for template matching. The eventID of this event will be used to configure event.$name.baseID.

  2. Use scolv for refinement of picks. Use only P and S phases with clear onsets from stations which are close the the event and which are likely to provide phase observations in real time. Deactivate phase picks which shall not be used for template matching. Real-time data are selected for processing based on the stream component on which the pick was made. Only streams for which picks exist are considered for template matching. Therefore, phases should be picked on the component on which they can be observed best and on which the automatic picks, e.g. from scautoloc are made.

    Note

    When picks for the same phase type from ccloc and other pickers such as scautoloc exist but they are made on different streams, e.g. HHN and HHZ, they may both be associated to the same origin and bias the solution. Therefore, the picks provided with the master event must match in component with the picks from the other phase pickers.

  3. Relocate the event

  4. Compute the magnitude

  5. Commit the results to the SeisComP3 system and note the originID of the created origin. This originID will be used for configuring event.$name.originID.

  6. Extract the event XML of the selected master event from the database on the host to a file. The filename of the XML file can with event.$name.xml. The extracted event XML must contain at least the event with the created origin including all relevant arrivals and all picks.

    scxmldump -E <eventID> -d <host>/<database> -PAMf -o myfile.xml

  7. Configure :ref:`event.$name.xml` with the name of the extracted new XML file. Otherwise the parameters are read from the database.

  8. Extract the waveform data in miniSEED format with sufficient margin, about 1 minute before the first and the last detected phase. Definw the time window based on the actual event using scevtstreams. The data can be extracted from an SDS and a CAPS archive by scart and capstool, respectively. Save the waveforms in a miniSEED file sorted by endtime.

  9. Configure :ref:`event.$name.data` with the name of the extracted miniSEED file. Otherwise the waveforms are read from the RecordStream interface.

When the master event has been defined the configuration should be tested in an offline playback at least by matching the master template to its own waveforms.

Multiple master events

Multiple master events can be defined in order to account for events of different kinds for the same or for different seimicity regions. One new event may be detected by several master events. In this case keeping only the best solution with the highest overall fit instead of all may be desired.

To keep only the best solution, master events can be grouped. The best solution will then be selected from all solutions found from the master events belonging to the same group arriving within a configured time window. The group name and the time window can be configured by the parameters event.$name.group and detector.window, respectively.

Configuration: Verification

A first verification test should include to find the master event itself by template matching: Verify that time windows and data processing is appropriate. Filter effects must not disturb the data signal used for cross-correlation.

  1. Run ccloc on the command line in dump mode on a dataset that contains the template event with all waveforms. In dump mode ccloc will generate output files from all processing steps in the ${event} directory which is created for all consider master events.

    • set dump output directory: output.dump.directory = ${DUMP_PATH}
    • enable dumping with the command line option --dump

    Note

    The output files may be very large. To minimize the file sizes we recommended to use small input files. The output files are created in output.dump.directory for the template and the processed signal. Indices indicate the content:

    0: raw waveforms

    1: waveforms without gain

    2: waveforms with subtracted mean

    3: filtered waveforms

    4: enveloped waveforms

    5: resampled waveforms

    6: logarithm of waveforms

    7: prepared waveforms

    8: data used for cross-correlation

  2. Verify the time window settings

    1. Display filtered template waveforms of the master event on top of filtered input data.

      scrttv ${DUMP_PATH}/${event}/real/3_filtered.mseed ${DUMP_PATH}/${event}/master/3_filtered.mseed

    2. Navigate to the master template and check for differences between the signal of the master event template and the input signal

      • in scrttv press 4 to sort the traces and zoom into the individual channels
      • the template waveforms include the configured time windows of the noise and the signal
      • the overlapping of the template and the input signal is indicated in scrttv in pink
      • note that yellow areas indicate gaps which are expected in the order of one sample due uncertainties when cutting out the time windows
      • depending on the configured filter, differences at the beginning of the master template within the noise window are normal
      • however, make sure that the differences do not reach the signal window which is considered for template matching
      • decrease parameter event.${event}.noiseBegin until you are satisfied with the results

    Example:

    Assume the following configuration example for the master event gempa2018abcd:

    1. configuration:

      events = gempa2018abcd
event.gempa2018abcd.data = gempa2018abcd.mseed
output.dump.directory = /tmp/ccloc_dump/

    2. execution:

      ccloc -I gempa2018abcd.mseed --dump
scrttv /tmp/ccloc_dump/gempa2018abcd/real/3_filtered.mseed /tmp/ccloc_dump/gempa2018abcd/master/3_filtered.mseed
    _images/verify_windows.png

    Template and signal with noise and signal windows optimized for filtering.

  3. Verify filter, envelope and time window settings.

    1. Run ccloc in dump mode as described above.

    2. Display raw and signal data of the master template side by side.

      $ scrttv ${DUMP_PATH}/${event}/master/0_raw.mseed ${DUMP_PATH}/${event}/master/8_signal.mseed
      • ccloc uses location code '09' to highlight the signal data used for cross-correlation
      • press 4 to bring related channels close to each other
      • load picks of master event (File -> Open XML)
      • verify that the envelopes created by ccloc match your expectations (make sure P- and S-waves are covered correctly)
      • adjust parameters event.${event}.signalBegin and event.${event}.signalEnd until you are satisfied with the results
    _images/verify_signal-windows.png

    Envelope of template correct and too short signal windows.

  4. Review matching results.

    1. Run ccloc in dump mode as described above.

    2. Compare envelopes of template with real data.

      scrttv ${DUMP_PATH}/${event}//master/4_enveloped.mseed ${DUMP_PATH}/${event}/real/4_enveloped.mseed

    3. navigate to a location where you expect a match in both windows

    4. compare the envelopes with each other - both should match

Configuration: Pipeline or multi-area application

ccloc can be applied in different processing pipelines and for different purposes simultaneously. To avoid clashes in configuration parameters for such applications or to separate the processing different instances of ccloc can be configured and executed. E.g. for a new instances named "l1" create a ccloc alias and treat it separately.

seiscomp alias create l1ccloc ccloc

Evaluating origins

ccloc adds a comment field to the new origins containing the match parameters of the origin. The information are also written to the log files of ccloc at output level 4 (debug) or on the commandline when starting ccloc with the option --debug. The comment field can be shown in the Events tab of scolv. To show the comment configure a custom column in the scolv configuration file scolv.cfg:

# Default value to display if the specified origin or event comment id was not
# found.
eventlist.customColumn.default = "-"

# Define the comment id to be used
eventlist.customColumn.originCommentID = configID

# Define the column header label
eventlist.customColumn = ccloc-config

To view the comment values in scolv, expand the event entry in the Events table and list the origins. The origins created with ccloc will show the comment values in the configured custom column:

  • overall (mean) fit calculated from the fit values of all matched channels.
  • number of traces which have match vs. number of tested traces
  • number of stations which have a match vs. number of tested stations.
_images/ccloc-scolv-customncolumn.png

Events table with ccloc custom column in the scolv main window.

evccloc plugin

ccloc ships with evccloc a plugin for scevent. If existing the plugin reads the event type of the master event written to the origin by ccloc as a comment. The read event type is used to set the event type of the event to which the origin is associated to.

When the event to which the origin is associated to has multiple origins, the latest origin containing an event type comment is considered for setting the event type.

Overwriting an existing event type is enabled by default but can be disbled by configuring ccloc.overwriteEventType.

Setting the event type if the event contains manual origins is disabled by default but can be enabled by configuring ccloc.overwriteManual.

Setup

  1. Add the evccloc plugin to the configuration of scevent:

    plugins = evccloc

  2. Set the plugin parameters in the scevent configuration:

    • ccloc.setEventType: Read the event type comment set by ccloc for the origin and apply it to the event. If enabled, all origins of the event are tested for the ccloc event type comment. The type comment of the last origin is used to set the comment.
    • ccloc.overwriteEventType: Overwrite existing event types by the type set by ccloc. Disabling ignores all type comments if the event has a type.
    • ccloc.overwriteManual: Allow setting the event type if the event has a manual origin. Disabling ignores all type comments if the event has a manual origin.

Examples

  1. Print the commandline help of ccloc:

    ccloc -h

  2. Real-time applications

    1. Run ccloc in real time on the commandline with descriptive debug output and configured values:

      ccloc --debug

    2. Run ccloc in real time as a daemon whenever seiscomp is started:

      seiscomp enable ccloc
seiscomp start ccloc

    3. Run ccloc in real time on the commandline while reading the binding configuration from a dedicated database on a specific host:

      ccloc -d localhost/seiscomp3

  3. Offline applications

    1. Execute ccloc offline with a multiplexed miniseed volume and an inventory XML file. Neither a messaging nor a database connection is required. The resulting origin parameters are not printed.

      ccloc --offline --inventory-db inventory.xml --config-db config.xml -I test-sorted.mseed

    2. Execute ccloc offline with a multiplexed miniseed volume and connecting to the seiscomp3 database on localhost. A messaging system is not required. The resulting origin parameters are output to standard output and redirected to an XML file. Eventually the origins parameters are sent to the SeisComP3 messaging system on localhost. After sending the origins they can be treated by other configured and running modules such as scanloc, screloc, scamp, scmag or scevent.

      ccloc --ep -d localhost/seiscomp3 -I test-sorted.mseed > origins_ccloc.xml
scdispatch -i origins_ccloc.xml -H localhost

    3. Execute ccloc offline with a multiplexed miniseed volume and an inventory XML file. Neither a messaging nor a database connection is required. The resulting origin parameters are output to standard output and redirected to an XML file. The origins parameters can be sent to a SeisComP3 messaging system or dumped to a seiscomp3 database.

      ccloc --ep --inventory-db inventory.xml --config-db config.xml -I test-sorted.mseed > origins_ccloc.xml

Configuration

etc/defaults/global.cfg
etc/defaults/ccloc.cfg
etc/global.cfg
etc/ccloc.cfg
~/.seiscomp3/global.cfg
~/.seiscomp3/ccloc.cfg

ccloc inherits global options.

events

Type: list:string

Profile names for one or more master events defined in the events section. It can be a single name or a list of event profile names. In a list the names are separated by comma.

profiles

Type: list:string

Defines one or more available processing profiles defined in the profiles section. It can be a single name or a list of profile names defined in the profiles section. The parameter can be overwritten per processing profile. Processing profiles can be created and used for processing with different master events. Profiles must be defined here for further use.

Note

processing.* Data processing before correlation detection.

processing.bufferSize

Type: int

Unit: s

Data buffer size (integer values). This parameter is important when testing with record volumes where records are not ordered by time. Default is 600.

processing.interval

Type: int

Unit: s

Processing interval (integer values). If records are received it will process the data every n seconds not more often. 0 disables the interval and starts processing whenever a new record is received and enough data is available. Default is 0.

processing.maximumLatency

Type: double

Unit: s

Defines the maximum data latency in seconds tolerated by the detector. If data latency is higher than this value processing is triggered without this particular channel. Default is 10.

processing.maximumStepFrequency

Type: int

The maximum frequency of processing steps per time window. If the data sampling frequency is much higher this parameter reduces processing time by increasing the time steps. A value of zero derives the time steps from the data or envelopes sampling frequency. Default is 0.

processing.maxAllowedGap

Type: double

Unit: s

Sets the maximum allowed gap between two samples. Default is 0.5.

processing.maxAllowedOverlap

Type: double

Unit: s

Sets the maximum allowed overlap between two samples. Default is 0.5.

processing.normalization

Type: string

Flag for normalization: trace, total. Default is total.

processing.filter.definition

Type: string

Filter applied to the raw waveforms. The depreciated parameters order, loFreq and hiFreq of this group are ignored if a value is set. Can be overwritten per processing profile.

processing.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. Can be overwritten per processing profile. Default is false.

Note

processing.envelope.* Waveform envelopes can be used as characteristic functions. Envelopes are formed from pre-processed data data.

processing.envelope.enable

Type: boolean

Use envelope as characteristic function for fitting the master events. Can be overwritten per master event. Default is true.

processing.envelope.samplingFrequency

Type: int

Unit: Hz

Sampling frequency of the envelope (0 = no resampling). Low sampling frequencies speed up the computations. Resampling at least twice the upper corner frequency of the filter. Can be overwritten per master event. Default is 0.

processing.envelope.hiFreq

Type: double

Unit: Hz

Corner frequency of lowpass for smoothing the envelope (0 = no filter). Can be overwritten per master event. Default is 20.

processing.envelope.resampleAverage

Type: boolean

Enables averaging of neighboring samples when downsampling. The width of the kernel is the ratio of SF/samplingFrequency. SF is the sampling rate of the original data before resampling. Can be overwritten per master event. Default is false.

processing.logarithm.enable

Type: boolean

Use the logarithm of the characteristic function (either waveforms or envelope). Can be overwritten per master event. Default is false.

Note

detector.* Detection by cross-correlation including detection thresholds after data pre-processing.

detector.channelThreshold

Type: double

Minimum channel fit which needs to be reached to declare a match on the channel. Formed by cross-correlating with master event template. Can be overwritten per master event. Parameter range: 0 - 1. Default is 0.55.

detector.threshold

Type: double

Minimum overall (mean) fit of all matched channels. Formed from the channel fits of all matched channels. Needs to be reached to declare a new origin. Can be overwritten per master event. Parameter range: 0 - 1. Default is 0.55.

detector.minimumChannelRatio

Type: double

Minimum ratio of the number of all matched channels vs. the number of all channels in master event. Needs to be reached to declare a new origin. Can be overwritten per master event. Parameter range: 0 - 1. Default is 0.55.

detector.minimumStationRatio

Type: double

Minimum ratio of the number of all matched stations vs. the number of stations in master event. A station is matched when it has at least one matched channel. Needs to be reached to declare a new origin. Can be overwritten per master event. Parameter range: 0 - 1. Default is 0.55.

detector.fitWindow

Type: double

Unit: s

Time window to search for the best match on all waveforms for a given detection. Important parameter to account for traveltime uncertainties wrt. the master template. Default is 0.5.

detector.window

Type: double

Unit: s

Time window to search for other detections after triggering. Only the detection with the best overall match is reported. Set this window for avoiding multiple detections on the same event. Default is 2.

detector.minimumProcessingWindow

Type: double

Unit: s

Sets the minimum processing time window length to minimize processing steps on each record arrival. 0 s processes the data as fast as possible. Can be overwritten per master event. Default is 0.

detector.groupPublicationTimeout

Type: int

Unit: s

If event groups are used and an event is declared which still needs to wait for all other events in the group to be processed this timeout is used to publish the best event of this group after a certain amount of time regardless of unprocessed events in the group. A negative value disables this feature and a queued event never times out. Default is 10.

Note

repicking.* Refinement of picks after detection.

repicking.enableAIC

Type: boolean

Run AIC to refine P and S picks found from template matching. The AIC parameters can be configured via ccloc station bindings. Use the picker and spicker parameters in the global section of the ccloc bindings profile. Default is true.

repicking.sendTheoreticalPicks

Type: boolean

Send theoretical picks like TP and TS. Default is false.

repicking.score.minScore

Type: double

Score to be reached to send origin. Default is 0.

repicking.score.pWeight

Type: double

Defines the weight of P arrivals for scoring. Default is 1.

repicking.score.sWeight

Type: double

Defines the weight of S arrivals for scoring. Default is 2.

Note

output.* Output of auxilliary information for debugging and tuning.

output.events.file

Type: string

Define output file for matched events. Each match creates a new line with format yyyy mm dd HH MM SS.FFF Lat Long Mag city CF usedPhases (cha:fit, ...). If not set no event file is created.

Note

output.dump.* Configuration of waveform dumping. Run ccloc with --dump to enable these parameters.

output.dump.directory

Type: string

Define location of dump files as a path to an already existing directory.

output.dump.eachStep

Type: boolean

Dump each step. An appropriate time window can be configured with parameters output.dump.startTime and output.dump.endTime. Note that this may produce a lot of files. It can be necessary to increase the number of maximum opened files on your system. Enable this option only with small input files or short time windows.

output.dump.startTime

Type: string

Time to start dumping of single steps (requires parameter output.dump.eachStep to be enabled).

output.dump.endTime

Type: string

Time to stop dumping of single steps (requires parameter output.dump.eachStep to be enabled).

Note

event.* Define master events and data processing per master event. Processing profiles can be defined and used instead of defining the parameters per master event.

Note

event.$name.* Defines one master event. The master event contains the eventID, the event type (opetional), the origin parameters, arrivals and picks. The configuration parameters for processing, detector and repicking overwrite the module-wide defined values which are used otherwise. $name is a placeholder for the name to be used and needs to be added to events to become active.

events = a,b
event.a.value1 = ...
event.b.value1 = ...
# c is not active because it has not been added
# to the list of events
event.c.value1 = ...
event.$name.baseID

Type: string

Defines the eventID to use. The considered origin is configured by originID. Using baseID reads the event from the database if no XML file is defined. Otherwise, the event is loaded from the XML file.

event.$name.xml

Type: string

Defines an event parameter XML file to extract the information from the XML file: eventID, event type, originID, origin time, magnitude, latitude, longitude and depth. Furthermore arrivals and picks are collected to define the arrival times and the phase hints. If xml is not set, the parameters are read from the SeisComP3 database.

event.$name.originID

Type: string

Defines the origin ID used to extract the following information from the XML file or the database: origin time, magnitude, latitude, longitude and depth. Furthermore arrivals and picks are collected and used to create the final origin. If not set, the preferred origin is considered. Default is preferred.

event.$name.data

Type: string

Defines the data URI for fetching the waveforms. The format is equal to the --record-url parameter. E.g. it can point to a file, an archive or a server. If not set, the template waveforms are requested using the configured RecordStream.

event.$name.noiseBegin

Type: double

Unit: s

Defines the begin of the noise window if envelope is enabled. The mean is computed from the noise window and removed from the whole envelope. This value is relative to the first P arrival. If not given then noiseBegin is set to signalBegin. The minimum mean of both defined noise windows is used finally.

event.$name.noiseEnd

Type: double

Unit: s

Defines the end of the noise window if envelope is enabled. The mean is computed from the noise window and removed from the whole envelope. This value is relative to the first P arrival. If not given then noiseEnd is set to signalBegin + 1. The minimum mean of both defined noise windows is used finally.

event.$name.noise2Begin

Type: double

Unit: s

Defines the begin of the second noise window if envelope is enabled. This value is relative to the first P arrival. If not given then noise2Begin is set to signalBegin. The minimum mean of both defined noise windows is used finally. This parameter is optional and set to noiseBegin if not given.

event.$name.noise2End

Type: double

Unit: s

Defines the end of the second noise window if envelope is enabled. This value is relative to the first P arrival. If not given then noiseEnd is set to signalBegin + 1. The minimum mean of both defined noise windows is used finally. This parameter is optional and set to noiseEnd if not given.

event.$name.signalBegin

Type: double

Unit: s

Defines the begin of the signal window used for cross-correlation. Relative to the first P arrival. Mandatory parameter.

event.$name.signalEnd

Type: double

Unit: s

Defines the end of the signal window used for cross-correlation. Relative to the first S arrival. Mandatory parameter.

event.$name.deltaM

Type: double

Defines a magnitude offset which is applied to the final magnitude. This parameter is optional.

event.$name.enable

Type: boolean

Enables or disables processing of master event data. If disabled the data is used as provided. Incoming data are processed in any way. If disabled the provided data must have been processed the same way as the current configuration. Default is true.

event.$name.profiles

Type: list:string

Assigns a list of processing profiles for processing the current master event. The profiles must be defined in the profile configuration section.

event.$name.group

Type: string

Defines a group name for detected events. Results from master events belonging to the same group are jointly evaluated. Only the result with the best match is considered. Therefre ,only one event of a group can occur at one time. If the group is empty the event is independent and forms a group containing only this event. Configure groupPublicationTimeout for defining the wait time.

event.$name.negative

Type: boolean

If enabled this event is a negative event. Negative event detections don't create an origin. They can be used to stop false alarms. Default is false.

Note

event.$name.tolerances.* The following options define thresholds used by ccloc to decide whether a master template should be used even if errors occur. Use these options with caution. It should be preferred to use well prepared master templates to avoid unexpected results.

event.$name.tolerances.maxImproperChannels

Type: int

Sets the maximum number of improper channels tolerated by ccloc. Use -1 to tolerate any number of improper channels. Default is 0.

event.$name.tolerances.maxImproperStations

Type: int

Sets the maximum number of improper stations tolerated by ccloc. Use -1 to tolerate any number of improper stations. Default is 0.

event.$name.tolerances.minProperChannels

Type: int

Sets the minimum required number of properly configured channels. Default is 0.

event.$name.tolerances.minProperStations

Type: int

Sets the minimum required number of properly configured stations. Default is 0.

event.$name.tolerances.ignoreImproperEvent

Type: boolean

Defines whether this event should be ignored if classified as improper. If set to 'false', processing will be aborted if this event is not properly configured. Default is false.

event.$name.processing.maxAllowedGap

Type: double

Unit: s

Sets the maximum allowed gap between two samples. Default is 0.5.

event.$name.processing.maxAllowedOverlap

Type: double

Unit: s

Sets the maximum allowed overlap between two samples. Overwrites general settings. If not given the general settings are used. Default is 0.5.

event.$name.processing.filter.definition

Type: string

Filter applied to the raw waveforms. The depreciated parameters order, loFreq and hiFreq of this group are ignored if a value is set. Overwrites general settings. If not given the general settings are used.

event.$name.processing.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. Overwrites general settings. If not given the general settings are used.

Note

event.$name.processing.envelope.* Waveform envelopes can be used as characteristic functions. Envelopes are formed from pre-processed data data.

event.$name.processing.envelope.enable

Type: boolean

Compute envelope to be used for fitting the master events. Overwrites general settings. If not given the general settings are used.

event.$name.processing.envelope.samplingFrequency

Type: int

Unit: Hz

Defines the target sampling frequency of the envelope (0 = no resampling). Overwrites general settings. If not given the general settings are used.

event.$name.processing.envelope.hiFreq

Type: double

Unit: Hz

Frequency of lowpass for smoothing the envelope (0 = no filter). Overwrites general settings. If not given the general settings are used.

event.$name.processing.envelope.resampleAverage

Type: boolean

Enables averaging of neighbor samples when downsampling. The width of the kernel is the ratio of SR/samplingFrequency. Overwrites general settings. If not given the general settings are used. Default is false.

event.$name.processing.logarithm.enable

Type: boolean

Use the logarithm of the characteristic function (either waveforms or envelope). Can be overwritten per master event. Default is false.

Note

event.$name.detector.* Parameters defining the detection thresholds.

event.$name.detector.channelThreshold

Type: double

Minimum channel fit which needs to be reached to declare a match on the channel. Formed by cross-correlating with master event template. Overwrites general settings. If not given the general settings are used. Default is 0.70.

event.$name.detector.threshold

Type: double

Minimum overall (mean) fit of all matched channels. Formed from all channel fits. Needs to be reached to declare a new origin. Overwrites general settings. If not given the general settings are used. Default is 0.75.

event.$name.detector.minimumChannelRatio

Type: double

Minimum ratio of the number of all matched channels vs. the number of all channels in master event. Needs to be reached to declare a new origin. Overwrites general settings. If not given the general settings are used. Default is 0.60.

event.$name.detector.minimumStationRatio

Type: double

Minimum ratio of the number of all matched stations vs. the number of stations in master event. A station is matched when it has at least one matched channel. Needs to be reached to declare a new origin. Overwrites general settings. If not given the general settings are used. Default is 0.60.

event.$name.detector.minimumProcessingWindow

Type: double

Unit: s

Sets the minimum processing time window length in seconds to minimize processing steps on each record arrival. 0 processes the data as fast as possible. Overwrites general settings. If not given the general settings are used. Default is 0.

event.$name.repicking.enableAIC

Type: boolean

Run AIC to refine P and S picks found from template matching. The AIC parameters can be configured via ccloc station bindings. Use the picker and spicker parameters in the global section of the ccloc bindings profile. Default is true.

Note

profile.* Defines processing profiles. If a processing profile is defined it can be referred to in the master event configuration. The profile parameters overwrite parameters in the event definition.

Note

profile.$name.* Defines a profile. Filter options can be overwritten on a per stream basis, otherwise the global values are used. $name is a placeholder for the name to be used and needs to be added to profiles to become active.

profiles = a,b
profile.a.value1 = ...
profile.b.value1 = ...
# c is not active because it has not been added
# to the list of profiles
profile.c.value1 = ...
profile.$name.streams

Type: list:string

Defines a list of stream patterns for which filter values shall be overwritten.

profile.$name.filter.definition

Type: string

Specifies a filter definition. The parameters order, loFreq and hiFreq of this group are ignored if a value is set. If not given the general settings are used.

profile.$name.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. If not given the general settings are used.

Bindings

Configuration

detecEnable

Type: boolean

Enable data processing. If disabled the station is not considered. Default is true.

use3C

Type: boolean

Use all three components for processing. If disabled ccloc uses only the channel on which the pick in the master event was made. Default is true.

Note

ppicker.* Parameters controlling the refinement of P-type phase picks using the AIC methods. P-type phase picks include any phase arriving at the station as a P phase, e.g. P, pP, Pn, PKP, etc. The AIC is applied to the component on which the P pick of the master event was made.

ppicker.procMargin

Type: double

Unit: s

Begin of processing time window relative to the TP pick. As filtering may result in artefacts, the processing window should start before the AIC window allowing all artefacts to be deminished. Default is -3.

ppicker.signalBegin

Type: double

Unit: s

Begin of AIC time window relative to the TP pick. Default is -1.

ppicker.signalEnd

Type: double

Unit: s

End of AIC time window relative to the TP pick. Default is 1.

ppicker.filter

Type: string

Filter applied to the data before AIC analysis. Filtering starts at procMargin. Default is RMHP(2)>>ITAPER(1)>>BW(3,2,20).

ppicker.minSNR

Type: double

Minimum SNR which must be reached at the detection time of the AIC. Otherwise no pick is created. Default is 3.

Note

spicker.* Parameters controlling the refinement of S-type phase picks using the AIC methods. S-type phase picks include any phase arriving at the station as a S phase, e.g. S, sS, Sn, PKS, etc. The AIC is applied on the L2 norm of the horizontal components or on the vertical component of the master if the S pick was made on the vertical.

spicker.procMargin

Type: double

Unit: s

Begin of processing time window relative to the TS pick. As filtering may result in artefacts, the processing window should start before the AIC window allowing all artefacts to be deminished. Default is -3.

spicker.signalBegin

Type: double

Unit: s

Begin of AIC time window relative to the TS pick. Default is -1.

spicker.signalEnd

Type: double

Unit: s

End of AIC time window relative to the TS pick. Default is 1.

spicker.filter

Type: string

Filter applied to the raw data before forming the L2 norm of the horizontal seismograms. This filter is recommended to account for DC offset of individual components. Filtering starts at procMargin. Default is RMHP(2)>>ITAPER(1)>>BW(3,2,10).

spicker.detecFilter

Type: string

Filter applied to the L2 trace of the data before AIC analysis. Filtering starts at procMargin. Leave this parameter empty to apply no further filtering. This is often the case.

spicker.minSNR

Type: double

Minimum SNR which must be reached at the detection time of the AIC. Otherwise no pick is created. Default is 5.

Command-line

Generic

-h, --help

show help message.

-V, --version

show version information

--config-file arg

Use alternative configuration file. When this option is used the loading of all stages is disabled. Only the given configuration file is parsed and used. To use another name for the configuration create a symbolic link of the application or copy it, eg scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

Run as daemon. This means the application will fork itself and doesn't need to be started with &.

--auto-shutdown arg

Enable/disable self-shutdown because a master module shutdown. This only works when messaging is enabled and the master module sends a shutdown message (enabled with --start-stop-msg for the master module).

--shutdown-master-module arg

Sets the name of the master-module used for auto-shutdown. This is the application name of the module actually started. If symlinks are used then it is the name of the symlinked application.

--shutdown-master-username arg

Sets the name of the master-username of the messaging used for auto-shutdown. If "shutdown-master-module" is given as well this parameter is ignored.

Verbosity

--verbosity arg

Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug

-v, --v

Increase verbosity level (may be repeated, eg. -vv)

-q, --quiet

Quiet mode: no logging output

--component arg

Limits the logging to a certain component. This option can be given more than once.

-s, --syslog

Use syslog logging back end. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Debug mode: --verbosity=4 --console=1

--log-file arg

Use alternative log file.

Messaging

-u, --user arg

Overrides configuration parameter connection.username.

-H, --host arg

Overrides configuration parameter connection.server.

-t, --timeout arg

Overrides configuration parameter connection.timeout.

-g, --primary-group arg

Overrides configuration parameter connection.primaryGroup.

-S, --subscribe-group arg

A group to subscribe to. This option can be given more than once.

--encoding arg

Overrides configuration parameter connection.encoding.

--start-stop-msg arg

Sets sending of a start- and a stop message.

--test

Runs the detector without sending any objects to the messaging system.

Database

--db-driver-list

List all supported database drivers.

-d, --database arg

The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg

The configmodule to use.

--inventory-db arg

Load the inventory from the given database or file, format: [service://]location

--db-disable

Do not use the database at all

Records

--record-driver-list

List all supported record stream drivers

-I, --record-url arg

The recordstream source URL, format: [service://]location[#type]. "service" is the name of the recordstream driver which can be queried with "--record-driver-list". If "service" is not given "file://" is used.

--record-file arg

Specify a file as record source.

--record-type arg

Specify a type for the records being read.

Mode

--offline

Do not connect to a messaging system.

Output

--ep

Do not connect to messing system and print processing results in XML format to standard out.

--progress

Print current processing time to stderr.

--progress-int arg

Set the time interval to print the execution progress. Units: s. Default: 3600 s.

--dump

Write each stage to file. Requires definition of configuration parameters in section 'output.dump'.