ccloc

Signal detection based on template matching by waveform cross-correlation.

Description

ccloc detects signals by matching template waveforms to the signals in order to find similarities. The templates are pre-defined as event, origin or phase pick objects along with the corresponding waveforms. Similarity is measured by cross-correlation of characteristic functions.

cclod declares a match, hence a detection when the detection parameters are above configured thresholds.

ccloc either creates new

  • Origins if the template is an origin or an event with a referenced origin. Location and depth of the new origin are inherited from the matched template whereas origin time is determined from the processed time window.

  • Picks, if the template is a pick object.

An efficient strategy for generated and configuring templates is described in the section Getting started.

Hint

ccloc in versions higher than 2022.258#92f623e can process data on multiple CPU threads in parallel or on the GPU. The benefit is a significant speed up allowing to use many templates in parallel. Section Compute Resources provides the related information.

Event type

New origins contain the event type of the template as a comment if the tempate is an event and if the event object contains an event type. The type comment is evaluated by the evccloc plugin for scevent [6] and applied to events containing this ccloc origin. In this way, ccloc can also contribute to event discrimination.

Magnitudes

ccloc computes a magnitude of type ccloc for a newly create origin if the template origin event. The ccloc magnitude type 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)ccloc = M_{master} + \frac{1}{N} \sum_{i=1}^{N} \log_{10} \frac{PGV_{continuous_i}}{PGV_{master_i}}

In order to allow the ccloc magnitudes to be considered in summary magnitudes or as preferred magnitude, configure scmag [7] and scevent [6], respectively.

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 [2],

  3. Declaration of origins,

  4. Optional pick refinement.

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 is available, the time windows are processed.

../_images/stepping.png

Figure 1: Processing of a data time window of continuous channels. The step of each processing step is the time of one sample. See Data Processing for the processing of each each time window.

Each processed time window is matched with the master event. If the overall fit exceeds the configured threshold, the detector is started searching for the maximum fit within the configured time window. 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 before applying cross-correlation consists of

  1. Data selection

  2. 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

Figure 2: Processing schema in the time domain. data are the template waveforms and continuous raw input waveforms corrected for sensitivity.

Note

The processing is equally applied to waveforms template events and waveforms on which detection are sought. Processing is done in the time domain as it is much faster than in the frequency domain.

The individual processing steps can be verified as set out in section Verify Processing Steps.

Data selection

The waveform data of the master event template and of the matched input data, e.g. real-time waveforms, 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 a 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.

In addition, binding parameter useAllC can be used to enable processing on all streams of a sensor location if for that sensor location at least one pick is defined by the master event.

Characteristic functions

Supported characteristic functions are:

  1. Processed waveforms where the processing can comprise any SeisComP Filter Grammar [1].

  2. Envelopes formed from processed waveforms.

  3. Logarithm applied to processed waveforms.

Note

Envelope functions can also be formed by SeisComP filters and added to the first filter stage instead of activating the envelope in the second stage. Read section Envelope for the details.

Processed waveforms

Processed waveforms can be used as characteristic function. Here, any available SeisComP Filter Grammar [1] or filter chains 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.

Bandstops at 50 Hz and 100 Hz are applied when enabling processing.filter.bandStop.

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

Envelope

The cross-correlation can be computed on the processed (filtered) seismograms or on the envelopes of the processed waveforms. Using the envelope of seismograms instead of the seismograms themselves, 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:

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

N will be set to 1 for a processing.envelope.hiFreq value less than or equal to 0.

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

Due to (2) envelope functions can also be formed from SeisComP Filter Grammar [1] and configured in processing.filter.definition like

self()^2>>AVG(T)^0.5

where T can be calculated from processing.envelope.samplingFrequency and processing.envelope.hiFreq inserting (3).

(4)T &= \frac{N}{\text{processing.envelope.samplingFrequency}}\\ &= \frac{\text{processing.envelope.samplingFrequency}}{\text{processing.envelope.hiFreq} * \text{processing.envelope.samplingFrequency}} \\ &= \frac{1}{\text{processing.envelope.hiFreq}}

Note

Currently, resampling is only available along with forming envelopes and processing.envelope.enable = true. In the future, resampling may become an independent processing step.

Logarithm

The logarithm trace can be computed from the processed waveforms or from envelopes.

By enabling processing.logarithm.enable the logarithm is computed and used as the characteristic function:

(5)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:

(6)\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:

(7)\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.

Detection by Cross Correlation

After data processing, the processed waveform templates are cross-correlated [2] with the measured waveform data searching for new detections. A detection is declared and a new origin is created if all of the configurable thresholds are reached:

Single trace correlation

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

(8)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

(9)R^j > R_1,

for at least Jmin channels. Rj is defined in equation (8). 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: This condition requires that the current time window and the master event show 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 correlation

In the next step ccloc computes the network cross-correlation with zero lag, where two normalization options are available. They are selected with processing.normalization:

  • trace normalization: ccloc computes the average single trace cross-correlation coefficient of the Jmin traces with the highest single trace cross-correlation coefficient:

    (10)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

  • total normalization: ccloc computes the matrix cross-correlation with zero lag, where one dimension of the matrix is time and the other dimension is the different traces:

    (11)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 (10) the relative amplitudes between stations and components are neglected. They are taken into account in equation (11), meaning that only events of similar magnitude are detected.

The second condition for a detection is either

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

or:

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

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

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.

Travel-time uncertainties

When the template and the new event share an identical hypocenter, the travel times to the stations are equal and the relative phase arrival times of the template and the new event are the same for all stations. Generally, the hypocenters are not identical and differences in travel-times occur. This will degenerate the network correlation and prevent a detection if the differences are not tolerated. The parameter to control the tolerance for travel-time differences is detector.fitWindow. Set detector.fitWindow large enough to account for travel-time differences between new events and the template (see figure below). Very small values will confine the detections to events very close to the template hypocenter. Once a detection is made, travel-time differences can be further accounted for by refining phase picks.

Hint

detector.fitWindow is a crucial module configuration parameter. It can be overridden per template event.

../_images/ccloc-windows.png

Figure 3: Window parameters. window: detector.window, fitWindow: detector.fitWindow. signal window is the time window defined per template event by event.$name.signalBegin and event.$name.signalEnd. Relative time of matches may differ from relative arrivals predicted by the template. The beginning of detector.fitWindow and detector.window is defined by the first match.

Waveform complexity

Processed waveforms may be more complex than waveforms of template events. Some reasons are:

  • Noise,

  • Doublet events of overlapping signals due to multiple events,

  • Complex or long source time functions.

In such situations, ccloc may find multiple detections witin very short intervals which often belong to the same event. ccloc will select the best matching detection within a time window defined by detector.window and will only deliver one detection within this time window. detector.window refers to a shift in the assumed source time allowing to shift the template across the wave forms (see figure above).

Hint

Configure detector.window large enough to account for waveform complexity, e.g. the length of a source time function, but small enough to avoid overlapping with subsequent events. The choice of the value is driven by the expected signal durations and inter-event times.

Declaration of origins

Once the detector thresholds are met, a new origin is created containing

  • Origin time and hypocenter location: The hypocenter and the time of the new origin are not found by locating but are derived from the time of the master template and the time of the processed time window, the time of the detection.

  • Origin status: The status of the origin is by default preliminary which can be configured by output.origins.status. Relocate the origin for more precise parameters. For relocation provide the origin to other modules such as scanloc [4], screloc [10] or use scolv [9] for interactive analysis.

  • Event type of the template event as an origin comment.

  • Picks and arrivals: The pick times are derived from the traveltimes of the master event added to the origin time of the detection. They are further refined by the AIC method unless deactivated by repicking.enableAIC.

    In case of larger differences in source location, the matched and the 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. P, S, Pn, Sg, etc., originating from the template 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 origins found by template matching can only have phase detections/arrivals for which the template event also has arrivals. Thus,

    • if the template event misses, e.g., a P arrival at a station, then the found origin cannot have P, TP or AP arrivals for this station,

    • if use3C is active and the template misses arrivals on the horizontal components but only the horizontal components, not the vertical, have matches, then the new origin will have 0 arrivals. The same applies for the vertical component.

Pick Refinement

The T-picks found from template matching may be inaccurate. Therefore they should be re-picked by a second-stage AIC picker. Once the AIC can find a pick exceeding the configured minimum SNR, the leading T of the phase name is removed and the arrival is given a weight of 1. The re-picked phase picks are typically more accurate and can now be used for re-locating. AIC picks not exceeding the minimum SNR receive trailing A, e.g. APg instead of Pg and a weight of 0.

When repicking is enabled, sending the T and A picks is disabled by default. However, they may be useful for debugging or manual analysis. To enable the sending of T or A picks configure in the module configuration:

Then, one station may deliver two different picks for the same phase type with different given phase hints, e.g. P and TP or AP.

As for the T picks the A picks cannot be used automatically for re-locating e.g. by scanloc or screloc as typically no corresponding travel-time tables exist.

Note

Sending all T- and A-type picks (see below) may results in an unnecessary and large amount of output and is therefore disabled by default. On the other hand, the A picks may be considered by operators. Simply adjusting the phase names to supported ones allows to use them by SeisComP locators.

AIC setup

The AIC method is enabled by default with repicking.enableAIC. The AIC parameters are configured in the ccloc binding configuration:

  1. Create a new or use an existing processing profile.

  2. P-type phases: Set the profile.$name.ppicker.AIC.* parameters. The time window parameters are use with respect to the TP picks. Ensure that AIC windows for P wave do not overlap with S phases.

  3. S-type phases: Set the profile.$name.spicker.AIC.* parameters. The time window parameters are use with respect to the TS picks.

Interaction

The picks can be shown in scolv or scrttv:

  • Red for automatically re-picked picks with weight 1.

  • Gray for arrivals with weight 0: T or A picks.

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

../_images/ccloc_scolv_arrivals.png

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

To use the T or the A picks for re-locating, the phase names can be replaced interactively in the arrival table of scolv.

../_images/ccloc_scolv_main.png

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

Configuration and Setup

This section describes the main steps to configure ccloc.

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 sections Verify Processing Steps and Verify Processing Steps.

ccloc can be configured with the following hierarchy, the last read parameter value takes priority:

  • Module configuration:

    • general parameters

    • mandatory: template event parameters

    • data processing

    • event detection

  • Bindings configuration:

    • mandatory: data processing profile(s)

    • template event parameters

    • AIC re-picker parameters

Quick start

To get started quickly, it is sufficient to define a template and a few general parameters. The tempate can be a single pick or an origin or an event with a referenced origin.

  1. Define the new template including waveforms in a miniSEED file and corresponding event parameters in an SCML file, respectively. The proceedure is set out in section Template Generation.

  2. Configure the template in the module configuration:

    1. Choose an existing ccloc instance for adding the template or create a new ccloc instance.

    2. Create an event profile (event.$name) for the new template in the module configuration. The name of the event profile is typically the eventID.

      For the new profile configure at least:

      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.

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

  3. Configure general module configuration parameters:

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

    • computeResources.numThreads or computeResources.useGPU deciding whether to compute on one or multiple threads or on the GPU to speed up processing. Read section Compute Resources for more details on multi-threading.

    • 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.

    • 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.

    • Re-picking: 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.

    Note

    Some general parameters can be overridden by the template event profiles and the profiles in the module and the bindings configration. The last occurrence takes higest priority. Once configured in any instance, the default values do not apply.

  4. Configure ccloc bindings:

    Only stations with ccloc bindings will be considered. Therefore, create at least one profile and configure the AIC parameters for the re-picker if activated.

  5. Update the bindings configration of the configured ccloc instance, e.g.

    seiscomp update-config ccloc

  6. First tests: execute ccloc on the command line for matching the template event to its own waveforms. Use an offline playback for testing.

    • The event must be found by its own template with a high match. The match is printed to the command line.

    • Compare the waveforms created by individual processing steps, read section Verify Processing Steps.

    • To compare the results, use the option --ep and redirect the output to a XML file which can be opened in scolv.

    • Inspect the waveform files. Dump the data of individual processing steps with the command-line option --dump and view them as set out in section Verify Processing Steps.

Important other parameters

  • Data processing:

    • 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.

    • Adjust event.$name.procMargin controlling how much data is added before event.$name.noiseBegin in order to compensate for the any artefact due to filtering and other data processing. Data in this range will not be considered for template matching.

  • Event specific parameters:

    • 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 sent to the messaging.

Multiple template events

Multiple template events can be defined in order to account for events of different sources for the same or for different regions.

  • Different sources in the same region and with similar procssing: Add all template events to the same ccloc instance. Adjust the configuration parameters separately for each template in the module and binding configuration.

  • Sources in different regions or with different processing: Create a new ccloc instance for each region or add to a existing instance. Configure individually.

One new event may be detected by several template event of the same ccloc instance. 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, template events can be grouped by event.$name.group. The best solution will then be selected from all solutions found from the template events of the same group arriving within a configured time window configured by detector.window.

Note

Grouping is only possible within one ccloc instance.

Verification

The results from processing template waveforms and new data can be evaluated step-by-step as set out in the section Verify Processing Steps.

Template Generation

For each template event you need to define the waveforms and event parameters. Event parameters must include an origin along with arrivals and phase picks. If available in the template, magnitudes are used for computing magnitudes of detected events. The origin can be the preferred origin of an event or any other origin. Waveforms can be read from recordstream or a single miniSEED file. Event parameters can be read from the SeisComP data base or a XML file. Read from files is recommended guaranteeing constant conditions.

Hint

While larger events can be detected clearly at many stations, small events will be often visible only at nearby stations. For detecting many small events it can be advisable to generate the template from very few nearby stations only with clear signals.

  1. Choose the event in scolv, re-pick P and S phases and disable picks (remove arrival) from stations which shall not participate in template matching. 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 are made, e.g. by scautopick.

    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.

  2. Relocate the origin.

  3. Set the event type of the template event to automatically set the event type of detection. This step required the plugin evccloc to be configured in scevent [6].

  4. Commit the solution, note the originID and the eventID: expand the event in the scolv Events list and read the IDs

  5. Dump the event XML using scxmldump [12].

  6. Dump the related template waveform into a miniSEED file. You can use a combination of scevtstreams and capstool or scart.

  7. Create a subdirectory of @DATADIR@ and save the XML and the miniSEED file therein. E.g.:

    mkdir -p $SEISCOMP_ROOT/share/ccloc/[eventID]
cp [XML file] [miniSEED file] $SEISCOMP_ROOT/share/ccloc/[eventID]

Note

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 above for the procedure.

Hint

You may write a skript and configure one of the configurable buttons in scolv to extract the template interactively by a mouse click.

Example script, e.g. @DATADIR@/ccloc/configure-ccloc-template.sh:

#!/bin/bash

cclocConfig="$SEISCOMP_ROOT/share/ccloc"

# Get the event and origin ID
eventID=$2
originID=$1

# database
db="-d mysql://sysop:sysop@localhost/seiscomp"

mkdir -p $cclocConfig/$eventID
cd $cclocConfig/$eventID

# Prepare template, provide miniSEED records sorted by time!
scxmldump -E $eventID -PAMf -vvvv $db > $eventID.xml
scevtstreams -i $eventID.xml -E $eventID -m 120 -vvvv -L 0 > $eventID.list

# Adjust the data source according to system setup
# waveforms must be sorted by end time
scart -I caps://localhost:18002 --list $eventID.list --stdout |\
scmssort -u -E > $eventID.mseed

if [ `stat --format %s $eventID.mseed` == 0 ]; then
  echo "no data found"
  rm -r $eventID.mseed
fi

echo "generated template in files in " $cclocConfig/$eventID
echo "  + files: " $eventID.xml $eventID.list $eventID.mseed
echo "use the files to configure ccloc"
echo "event ID: " $eventID
echo "origin ID: " $originID

Example scolv configuration in scolv.cfg:

# Label of button that triggers user defined script0.
button0 = MakeCclocTemplate

# Full path to the script executed when hitting the button labeled with button0.
scripts.script0 = "@DATADIR@/ccloc/configure-ccloc-template.sh"

Start scolv with --debug for information on the template when hitting the new button.

Verify Processing Steps

Time windows of waveforms and processing steps can be verfied since ccloc allows you to dump the resulting waveforms for the template event and the actual data to processed. Use the command-line option --debug and configure output.dump.directory for dumping the waveforms. The waveforms will be stored below output.dump.directory in the subdirectories master and real for waveforms of the template event and actual data, respectively. The files have unique names and the sensor location codes of the records therein take the value of the file prefixes:

  • 0_raw.mseed.mseed: raw waveforms

  • 1_corrected.mseed: waveforms without gain

  • 2_demeaned.mseed: waveforms with subtracted mean

  • 3_filtered.mseed: filtered waveforms

  • 4_enveloped.mseed: enveloped waveforms (available only in case the envelop is formed)

  • 5_resampled.mseed: resampled waveforms (available only in case the envelop is formed and resampling is enabled)

  • 6_prepared.mseed: logarithm of waveforms (available only in case the logarithm is formed)

  • 7_prepared.mseed: prepared waveforms (mean of noise windows subtracted)

  • 8_signal.mseed: data used for cross-correlation (final processed data including time-windowing)

  • fit.mseed: final fit per stream, only provided in the directory real.

Actual details of found matches and origins are printed on the command line when executing ccloc, e.g.:

ccloc -d localhost -I data.mseed --ep > /tmp/origins.xml

...

*=========================================================*
  Origin count (first = 0): 44
  0.73 mean fit with template event gempa2017nmnfr
  4/21 channels, ratio: 0.19
  2/7 stations, ratio: 0.29
*---------------------------------------------------------*
  Time       : 2017-07-11 19:19:41.867500
  Hypocenter : 50 12 4.1km
  Magnitude  : 0.013
  Negative   : 0
*---------------------------------------------------------*
* channel fit >= detector.channelThreshold                *
  SX.GUNZ..HHN  0.62  0.62
  SX.GUNZ..HHZ  0.74  0.74
  SX.ROHR..HHE  0.9  0.9
  SX.ROHR..HHZ  0.68  0.68
*---------------------------------------------------------*
* origin score 1 < 2 - do not publish                     *
*=========================================================*

The details may be used for

  • Counting the number of found origins

  • Reading the characteristic match values which are compared against configured thresolds. The thresholds may then be adjusted accordingly.

A first verification test should include finding 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 considered master events.

    Example:

    1. Assume simple configuration for the master event gempa2018abcd:

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

    2. Run ccloc with option --ep dumping the waveforms from individual processing steps (--dump):

      ccloc -d localhost -I gempa2018abcd.mseed --dump --ep > /tmp/origins_ccloc.xml

  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

      scrttv /tmp/ccloc/gempa2018abcd/real/3_filtered.mseed /tmp/ccloc/gempa2018abcd/master/3_filtered.mseed
    ../_images/verify_windows.png

    Figure 6: Template and signal with noise and signal windows optimized for filtering.

    Note

    The purple background color indicates overlapping records since the stream codes in both read files are identical and the time windows overlap.

  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

      Note

      Since the stream codes in both files are not identical, the waveforms are shown in separate lines. In order to overlay them in scrttv [11] they need to be identical. You may rename stream codes using scart [5].

      • ccloc uses location code ‘08’ 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

    Figure 7: 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

Origin Evaluation

ccloc adds a comment field to the new origins containing the match parameters of the origin. These informations 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 and the other event lists. To show the comment configure a custom column in the scolv configuration 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

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

Pipeline or Multi-Area Application

ccloc can be applied in different processing pipelines and for different purposes simultaneously. In order 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 instance named “l1” create a ccloc alias and treat it separately.

seiscomp alias create l1ccloc ccloc

Note

Using aliases in separated pipelines can be most powerful when sending all phase picks, amplitudes, magnitudes and origins to a new message group as defined by connection.primaryGroup. The message group must be generated by configuration of scmaster [8]. The sent origins, picks, etc. can then be received by other modules such as scanloc [4] or scolv [9] or scrttv [11] when configuring connection.subscriptions for these modules.

Compute Resources

ccloc supports CPU multi-threading and GPU processing. The number of CPU threads can be configured with option computeResources.numThreads. By default, only a single CPU thread is used. GPU processing requires CUDA support by the GPU. GPU processing can be enabled with the option computeResources.useGPU disabling CPU processing and ignoring computeResources.numThreads.

Due to major refactorings, the single-threaded implementation ccloc in the current version is up to 3 times faster than in versions 2022.258#92f623e. The benchmark tests show that a significant speed-up is achieved by multi-threading and GPU computation.

../_images/benchmark.png

Figure 9: Benchmarking of the effect of multi-threading and GPU computation based on a single master event. Left: Short signal but many channels were defined by the master event. Right: Long signal but few channels were defined by the master event. The benchmark tests were executed on an Intel Core i7-2600K processor (3.40GHz, 4 Cores, 8 Threads) and an NVIDIA GeForce GTX 980 Ti graphics card. The results may differ on other systems and due to different CPU load.

Examples

  1. Print the command-line help of ccloc:

    ccloc -h

  2. Real-time applications

    • Run ccloc in real time on the command line with descriptive debug output and configured values:

      ccloc --debug

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

      seiscomp enable ccloc
seiscomp start ccloc

    • Run ccloc in real time on demand line while reading the binding configuration from a dedicated database on a specific host:

      ccloc -d mysql:/sysop:sysop@localhost/seiscomp
ccloc -d localhost

  3. Non-real-time applications

    You may process waveforms by ccloc at any time in non-real-time applications with or without connection to a messaging system.

    • Execute ccloc offline with a multiplexed miniSEED volume. Get the inventory from the database or an inventory and a bindings configuration XML file. No messaging connection is required. The resulting origin parameters are printed to stdout and can be redirected to an XML file (--ep). Examples

      ccloc --ep -I test-sorted.mseed -d localhost > /tmp/origins_ccloc.xml
ccloc --ep -I test-sorted.mseed --inventory-db inventory.xml --config-db config.xml > /tmp/origins_ccloc.xml

      The inventory and config XML files can be generated by scxmldump [12]. The results can be treated in --ep playbacks by modules such as scanloc [4], screloc [10], scamp [3], scmag [7] or scevent [6].

      Send the results to the messaging for automatic processing by connected modules or write them to the database without further processing by other modules. Example:

      scdispatch -i /tmp/origins_ccloc.xml -H localhost
scdb -i /tmp/origins_ccloc.xml -d localhost

    • Execute ccloc offline (--offline) with a multiplexed miniSEED volume. Do not generate any XML output but only information on the processing. A messaging system is not required and the inventory and bindings can be read from the database or XML files as in the example above. Example:

      ccloc --offline -d localhost -I test-sorted.mseed

Module Configuration

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

ccloc inherits global options.

Note

Modules/plugins may require a license file. The default path to license files is @DATADIR@/licenses/ which can be overridden by global configuration of the parameter gempa.licensePath. Example:

gempa.licensePath = @CONFIGDIR@/licenses
events

Type: list:string

Profile names for one or more templates 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

Add one or more available processing profiles defined in the profile section below. It can be a single name or a list of profile names.

Processing profiles can be created and used for processing with different templates. Profiles must be registered here for further use.

Note: This option is deprecated. Please configure per channel properties in the ccloc bindings.

before

Default: 0

Unit: s

The timespan in seconds before now to start processing. Use -1 to let ccloc choose a timespan to speed up the initial window filling.

Note

computeResources.* Configuration of compute resources.

computeResources.numThreads

Default: 1

Type: int

Number of CPU threads used for processing. Only relevant if GPU processing is disabled.

computeResources.useGPU

Default: false

Type: boolean

Enables GPU processing. If enabled, ‘numThreads’ will be ignored.

Note

restart.* ccloc can save its state on module shutdown to be able to continue seamlessly after a restart. This section provides options to configure the restart behavior.

restart.maxTimeGap

Default: 0

Unit: min

Type: double

Defines the maximum time duration between last shutdown and current restart that is tolerated by ccloc. The saved state will be reset if this threshold is exceeded. Missed events may get lost.

Use a value of 0 to disable stateful restarts entirely.

Note

processing.* Data processing before correlation detection.

Many of these parameters can be overwritten per template event in the module configuration and per processing profile in the ccloc bindings.

processing.bufferSize

Default: 600

Unit: s

Type: int

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

processing.interval

Default: 0

Unit: s

Type: int

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

processing.maximumLatency

Default: 30

Unit: s

Type: double

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.

processing.maximumStepFrequency

Default: 0

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.

Please note: Changing this parameter might have a strong negative impact on the matching results. Choose carefully.

processing.maxAllowedGap

Default: 0.5

Unit: s

Type: double

Sets the maximum allowed gap between two samples.

This parameter can be overwritten per template.

processing.maxAllowedOverlap

Default: 0.5

Unit: s

Type: double

Sets the maximum allowed overlap between two samples.

This parameter can be overwritten per template.

processing.normalization

Default: trace

Type: string

Flag for normalization: trace or total.

processing.filter.definition

Type: string

Filter applied to the raw waveforms. Make sure to define a margin by ‘procMargin’ per event profile which is large enough allowing to compensate for all filter artefacts before the beginning of the noise and signal windows.

Filtering can be overwritten per template event and processing profile.

processing.filter.bandStop

Default: false

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. For more specific frequencies use the SeisComP filter BW_BS().

This parameter can be overwritten per template event and processing profile.

Note

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

processing.envelope.enable

Default: true

Type: boolean

Use envelope as characteristic function for fitting.

This parameter can be overwritten per template and processing profile.

processing.envelope.samplingFrequency

Default: 20

Unit: Hz

Type: int

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.

This parameter can be overwritten per template and processing profile.

processing.envelope.hiFreq

Default: 20

Unit: Hz

Type: double

Frequency for smoothing the envelope (0 = no smoothing). This parameter will be set to the samplingFrequency for values less than or equal to 0. See documentation section "Envelope" for details.

This parameter can be overwritten per template and processing profile.

processing.envelope.resampleAverage

Default: false

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.

This parameter can be overwritten per template and processing profile.

processing.logarithm.enable

Default: false

Type: boolean

Use the logarithm of the characteristic function (either waveforms or envelope).

This parameter can be overwritten per template and processing profile.

Note

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

Many of these parameters can be overwritten per template.

detector.channelThreshold

Default: 0.70

Type: double

Minimum channel fit to be reached for declaring a match on the channel. Formed by cross-correlating with waveforms of the template. Parameter range: 0 - 1.

This parameter can be overwritten per template.

detector.threshold

Default: 0.75

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. Parameter range: 0 - 1.

This parameter can be overwritten per template.

detector.minimumChannelRatio

Default: 0.60

Type: double

Minimum ratio of the number of all matched channels vs. the number of all channels in the template. Needs to be reached to declare a new origin. Parameter range: 0 - 1.

This parameter can be overwritten per template.

detector.minimumStationRatio

Default: 0.60

Type: double

Minimum ratio of the number of all matched stations vs. the number of stations in the template. A station is matched if the ratio of matched channels exceeds the ratio defined with parameter minimumChannelsPerStationRatio. Needs to be reached to declare a new origin. Parameter range: 0 - 1.

This parameter can be overwritten per template.

detector.minimumChannelsPerStationRatio

Default: 0

Type: double

Minimum ratio of the number of matched channels of a station vs. the number of channels of a station. Parameter range: 0 - 1.

This parameter can be overwritten per template.

detector.fitWindow

Default: 0.5

Unit: s

Type: double

Time window to search for the best match on all waveforms for a given detection. Important parameter to account for traveltime uncertainties w.r.t. the template.

detector.window

Default: 2

Unit: s

Type: double

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.

detector.minimumProcessingWindow

Default: 20

Unit: s

Type: double

Sets the minimum processing time window length to minimize processing steps on each record arrival. With 0s data processing starts as soon as possible. Higher values may increase processing speed in non-real-time scenarios.

This parameter can be overwritten per template.

detector.groupPublicationTimeout

Default: 10

Unit: s

Type: int

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.

Note

repicking.* Refinement of picks after detection.

repicking.enableAIC

Default: true

Type: boolean

Run AIC to refine P and S picks found from template matching. The AIC parameters can be configured via ccloc station bindings.

This parameter can be overwritten per template.

repicking.sendTheoreticalPicks

Default: false

Type: boolean

Send theoretical picks from template matching like TP and TS.

repicking.sendAICPicks

Default: false

Type: boolean

Send picks repicked by AIC after template matching which do not reach the minimum SNR as AP, AS, etc..

Note

repicking.score.* Score parameters to be applied to origins based on picks. They require to activate ‘repicking.enableAIC’.

repicking.score.minScore

Default: 0

Type: double

Score to be reached to send origin.

repicking.score.pWeight

Default: 1

Type: double

Defines the weight of P arrivals for scoring.

repicking.score.sWeight

Default: 2

Type: double

Defines the weight of S arrivals for scoring.

Note

output.* Output origin properties and auxiliary information for debugging and tuning.

output.events.file

Type: string

Output file for reporting 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.

output.origins.status

Default: preliminary

Type: string

Status given to new origins. "preliminary" is default since origins by ccloc are not located. Empty value: do not set the status.

Possible values:

"", rejected, reported, preliminary, confirmed, reviewed, final

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.

Note

event.* Define template events, origins or picks by ID and waveforms and waveform processing per template. Processing profiles can be defined and used instead of defining the parameters per template.

Note

event.$name.* Parameters of one template event, origin or pick. A template contains the object ID, and event type (optional), the origin parameters, arrivals and picks or just 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 event or pick ID to use.

event ID: This is the default operating mode. The processing is based on a given origin which is configured by parameter originID.

pick ID: In this mode, a single channel template, which is defined by the given pick, will be used for pattern matching on all enabled channels (pick mode). As a result, only picks and no origins will be sent out by ccloc.

Event or pick will be read from the database if no XML file is defined. Otherwise, the it will be 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 selected, the parameters are read from the SeisComP database.

EXAMPLE: @DATADIR@/ccloc/baseID/baseID.xml

event.$name.originID

Default: preferred

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.

Unused in pick mode.

event.$name.magnitudeID

Default: preferred

Type: string

Defines the magnitude ID. The magnitude will be read from the database if no XML file is defined. Otherwise, it will be loaded from the XML file.

Unused in pick mode.

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.procMargin

Unit: s

Type: double

Defines the begin of the master template relative to the first P arrival. It should be used to add a margin in front of the noise and signal window allowing to compensate for all filter artefacts before detection. The value must be less than noiseBegin and signalBegin.

By default, a margin of the same length as the noise window is prepended to the implicitly defined template begin. If procMargin and noise window are unconfigured, 2 seconds are prepended.

This parameter can be overwritten in a processing profile.

event.$name.noiseBegin

Unit: s

Type: double

Defines the begin of the noise window. 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.

This parameter can be overwritten in a processing profile.

event.$name.noiseEnd

Unit: s

Type: double

Defines the end of the noise window. 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, noiseEnd is set to signalBegin + 1. The minimum mean of both defined noise windows is used finally.

This parameter can be overwritten in a processing profile.

event.$name.noise2Begin

Unit: s

Type: double

Defines the begin of the second noise window. This value is relative to the first P arrival. If not given, 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.

Please note: In most cases it is not necessary to set this parameter.

This parameter can be overwritten in a processing profile.

event.$name.noise2End

Unit: s

Type: double

Defines the end of the second noise window. This value is relative to the first P arrival. If not given, 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.

Please note: In most cases it is not necessary to set this parameter.

This parameter can be overwritten in a processing profile.

event.$name.signalBegin

Unit: s

Type: double

Defines the begin of the signal window used for cross-correlation. Relative to the first P arrival. Mandatory unless defined in a processing profile.

This parameter can be overwritten in a processing profile.

event.$name.signalEnd

Unit: s

Type: double

Defines the end of the signal window used for cross-correlation. Relative to the first S arrival. Mandatory unless defined in a processing profile.

This parameter can be overwritten in a processing profile.

event.$name.deltaM

Type: double

Defines a magnitude offset which is applied to the final magnitude.

event.$name.enable

Default: true

Type: boolean

Enables or disables processing of template 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.

event.$name.profiles

Type: list:string

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

Note: This option is deprecated. Please configure per channel properties in the ccloc bindings.

event.$name.group

Type: string

Defines a group name for detected events. Results from template events belonging to the same group are jointly evaluated. Only the result with the best match is considered. Therefore, 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

Default: false

Type: boolean

If enabled, this event is a negative event. Negative event detections don’t create an origin. They can be used to suppress false alarms.

Note

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

event.$name.tolerances.maxImproperChannels

Default: 0

Type: int

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

event.$name.tolerances.maxImproperStations

Default: 0

Type: int

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

event.$name.tolerances.minProperChannels

Default: 0

Type: int

Sets the minimum required number of properly configured channels.

event.$name.tolerances.minProperStations

Default: 0

Type: int

Sets the minimum required number of properly configured stations.

event.$name.tolerances.ignoreImproperEvent

Default: false

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.

event.$name.processing.maxAllowedGap

Unit: s

Type: double

Sets the maximum allowed gap between two samples.

event.$name.processing.maxAllowedOverlap

Unit: s

Type: double

Sets the maximum allowed overlap between two samples.

event.$name.processing.filter.definition

Type: string

Filter applied to the raw waveforms. Make sure to define a margin by procMargin per event profile which is large enough to compensate for all filter artefacts before the beginning of the noise and signal windows.

This parameter can be overwritten in a processing profile.

event.$name.processing.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. For more specific frequencies use the SeisComP filter BW_BS().

This parameter can be overwritten in a processing profile.

Note

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

event.$name.processing.envelope.enable

Type: boolean

Compute envelope to be used for fitting.

This parameter can be overwritten in a processing profile.

event.$name.processing.envelope.samplingFrequency

Unit: Hz

Type: int

Defines the target sampling frequency of the envelope (0 = no resampling).

This parameter can be overwritten in a processing profile.

event.$name.processing.envelope.hiFreq

Unit: Hz

Type: double

Frequency for smoothing the envelope (0 = no smoothing). This parameter will be set to the samplingFrequency for values less than or equal to 0. See documentation section "Envelope" for details.

This parameter can be overwritten in a processing profile.

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.

This parameter can be overwritten in a processing profile.

event.$name.processing.logarithm.enable

Type: boolean

Use the logarithm of the characteristic function (either waveforms or envelope).

This parameter can be overwritten in a processing profile.

Note

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

These parameters overwrite the corresponding entries of the global configuration. The general settings are used for parameters that are not explicitly defined here.

event.$name.detector.channelThreshold

Type: double

Minimum channel fit to be reached for declaring a match on the channel. Formed by cross-correlating with the template waveforms.

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.

event.$name.detector.minimumChannelRatio

Type: double

Minimum ratio of the number of all matched channels vs. the number of all proper channels in the template. Needs to be reached to declare a new origin.

event.$name.detector.minimumStationRatio

Type: double

Minimum ratio of the number of all matched stations vs. the number of proper stations in the template. A station is matched if the ratio of matched channels exceeds the ratio defined with parameter minimumChannelsPerStationRatio. Needs to be reached to declare a new origin.

event.$name.detector.minimumChannelsPerStationRatio

Type: double

Minimum ratio of the number of matched channels of a station vs. the number of channels of a station.

event.$name.detector.fitWindow

Unit: s

Type: double

Time window to search for the best match on all waveforms for a given detection. Important parameter to account for traveltime uncertainties w.r.t. the template.

event.$name.detector.minimumProcessingWindow

Unit: s

Type: double

Sets the minimum processing time window length in seconds to minimize processing steps on each record arrival. With 0s data processing starts as soon as possible. Higher values may increase processing speed in non-real-time scenarios.

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 the ccloc station bindings. A processing profile is required to change the default filter settings.

event.$name.array.referenceLocation

Type: string

Enables array processing and configures the array’s reference location. The value must include network, station and sensor location ("{net}.{sta}.{loc}").

Note

profile.* Processing profiles can be referenced by event profiles allowing the same parameters to be used by multiple templates. The profile parameters overwrite parameters in the event definition.

Important: Processing profiles are deprecated. Please configure per channel properties via the ccloc bindings.

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

Filter applied to the raw waveforms. Make sure to define a margin by procMargin per event profile which is large enough allowing to compensate for all filter artefacts before the beginning of the noise and signal windows.

profile.$name.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. For more specific frequencies use the SeisComP filter BW_BS().

Bindings Parameters

detecEnable

Default: true

Type: boolean

Enable data processing. If disabled, the station is not considered.

use3C

Default: true

Type: boolean

Use all three components for processing. If disabled, ccloc uses only the channel on which the pick in the template was made.

useAllC

Default: false

Type: boolean

Use all channels of a sensor location for processing. If enabled and at least one pick is defined for a sensor location, all channels of that sensor location will be used for processing.

profiles

Type: list:string

Add one or more processing profiles defined in the profiles section below. It can be a single name or a list of profile names. Profiles must be defined here for further use.

Example: profile1,profile2

Note

profile.* Definition of processing profiles. The profile parameters overwrite parameters with the same name from the event definition in the module configuration.

A profile definition is required to set custom AIC filter settings.

Note

profile.$name.* Definition of the named profile. Parameters can be overwritten on a per stream basis, otherwise the global values are used. Add profile name to the list of profiles for using it. $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.events

Default: *

Type: list:string

Defines a list of events for which parameter values shall be overwritten. Wildcards can be used to declare multiple events per list entry. By default, all defined events will be used.

profile.$name.streams

Default: *

Type: list:string

Defines a list of streams for which parameter values shall be overwritten. Wildcards can be used to declare multiple streams per list entry. By default, all available streams will be used.

profile.$name.detecEnable

Default: true

Type: boolean

Enable data processing. If disabled, the selected streams are not considered.

profile.$name.procMargin

Unit: s

Type: double

Defines the begin of the master template relative to the first P arrival time. It should be used to add a margin before the noise and the signal window to avoid filter artefacts. The value must be less than the begin of the signal and noise windows.

By default, a margin of the same length as the noise window is prepended to the implicitly defined template begin. If procMargin and noise window are unconfigured, 2 seconds are prepended.

profile.$name.noiseBegin

Unit: s

Type: double

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, noiseBegin is set to signalBegin. The minimum mean of both defined noise windows is used finally.

profile.$name.noiseEnd

Unit: s

Type: double

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, noiseEnd is set to signalBegin + 1. The minimum mean of both defined noise windows is used finally.

profile.$name.noise2Begin

Unit: s

Type: double

Defines the begin of the second noise window if envelope is enabled. This value is relative to the first P arrival. If not given, 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.

Please note: In most cases it is not necessary to set this parameter.

profile.$name.noise2End

Unit: s

Type: double

Defines the end of the second noise window if envelope is enabled. This value is relative to the first P arrival. If not given, 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.

Please note: In most cases it is not necessary to set this parameter.

profile.$name.signalBegin

Unit: s

Type: double

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

Mandatory if not specified in the module configuration.

profile.$name.signalEnd

Unit: s

Type: double

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

Mandatory if not specified in the module configuration.

Note

profile.$name.processing.* Data processing before matching. These parameters overwrite the corresponding entries of the module configuration. If a parameter is not defined, it will be used from the module configuration.

Note

profile.$name.processing.filter.* Data filtering. If envelope calculation is disabled, the filtering can be used to create any characteristic function for data matching.

profile.$name.processing.filter.definition

Type: string

Filter applied to the raw waveforms. Make sure to define a margin by procMargin per event profile which is large enough allowing to compensate for all filter artefacts before the beginning of the noise and signal windows.

The deprecated parameters order and hiFreq of this group are ignored if a value is set.

profile.$name.processing.filter.bandStop

Type: boolean

Enables a bandstop filter at 50Hz and 100Hz. For more specific frequencies use the SeisComP filter BW_BS().

Note

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

profile.$name.processing.envelope.enable

Type: boolean

Compute envelope to be used for fitting.

profile.$name.processing.envelope.samplingFrequency

Unit: Hz

Type: int

Defines the target sampling frequency of the envelope (0 = no resampling).

profile.$name.processing.envelope.hiFreq

Unit: Hz

Type: double

Frequency for smoothing the envelope (0 = no smoothing). This parameter will be set to the samplingFrequency for values less than or equal to 0. See documentation section "Envelope" for details.

profile.$name.processing.envelope.resampleAverage

Type: boolean

Enables averaging of neighbor samples when downsampling. The width of the kernel is the ratio of SR/samplingFrequency.

profile.$name.processing.logarithm.enable

Type: boolean

Use the logarithm of the characteristic function (either waveforms or envelope).

Note

profile.$name.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 event was made.

profile.$name.ppicker.procMargin

Default: -3

Unit: s

Type: double

Begin of processing time window relative to the TP pick. The processing window should start before the AIC window allowing all filter artefacts to be diminished.

profile.$name.ppicker.signalBegin

Default: -1

Unit: s

Type: double

Begin of AIC time window relative to the TP pick.

profile.$name.ppicker.signalEnd

Default: 1

Unit: s

Type: double

End of AIC time window relative to the TP pick.

profile.$name.ppicker.filter

Default: RMHP(2)>>ITAPER(1)>>BW(3,2,20)

Type: string

Filter applied to the data before AIC analysis. Filtering starts at procMargin allowing to compensate for all filter artefacts.

This parameter also accepts a list of filters separated by semicolon. In this case multiple AIC runs will be performed and the result with the highest SNR value will be used further.

profile.$name.ppicker.minSNR

Default: 3

Type: double

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

Note

profile.$name.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 an 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 if the S pick was made on the vertical component.

profile.$name.spicker.procMargin

Default: -3

Unit: s

Type: double

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 diminished.

profile.$name.spicker.signalBegin

Default: -1

Unit: s

Type: double

Begin of AIC time window relative to the TS pick.

profile.$name.spicker.signalEnd

Default: 1

Unit: s

Type: double

End of AIC time window relative to the TS pick.

profile.$name.spicker.filter

Default: RMHP(2)>>ITAPER(1)>>BW(3,2,10)

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 allowing to compensate for all filter artefacts before phase picking.

This parameter also accepts a list of filters separated by semicolon. In this case multiple AIC runs will be performed and the result with the highest SNR value will be used further.

Please note that the number of filters must either be one or match the number of filters defined in parameter detecFilter.

profile.$name.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.

This parameter also accepts a list of filters separated by semicolon. In this case multiple AIC runs will be performed and the result with the highest SNR value will be used further.

Please note that the number of filters must either be one or match the number of filters defined in parameter filter.

profile.$name.spicker.minSNR

Default: 5

Type: double

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

Command-Line Options

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. Example: 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

Set 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

Set 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

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

-s, --syslog

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

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Execute in debug mode. Equivalent to --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.

--start-stop-msg arg

Default: 0

Set 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 config module 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 the messaging system. Implied with --ep.

Output

--ep

Print resulting event parameters in SCML format to standard out and do not connect to the messaging system. --offline applies implicitly.

--progress

Print current processing time to stderr.

--progress-int arg

Default: 3600

Unit: s

Set the time interval to print the execution progress.

--dump

Write each processing stage to file. Requires configuration of ‘output.dump.directory’.

Processing

--num-threads arg

Overrides configuration parameter computeResources.numThreads.