scanloc¶
Module for locating local earthquakes and man-made seismicity by DBSCAN cluster search.
Description¶
Low-threshold monitoring¶
scanloc associates detected P and S phases from local and regional earthquakes and other seismic events for locating. It determines initial hypocenter solutions by cluster search based on DBSCAN [1]. Additional P and S phases are associated to existing internal solutions from cluster search or solutions incoming through the messaging system from external modules.
Due to the clustering and subsequent phase association scanloc facilitates low-threshold monitoring of high- and low-rate seismicity with high accuracy.

Figure 1: scolv Location tab with an automatic earthquake solution from scanloc based on P and S phases.¶
Teleseismic events¶
For teleseismic events scanloc can also be used to:
Associate more picks from P and S phases to external origins,
Suppress fake events due to detections from large earthquakes recorded by dense local networks at teleseismic distances. A dedicated section explains the setup and the requirements.
Travel-time tables¶
The scanloc package ships with densely sampled travel-time tables for LOCSAT [4] based on the IASP91 Earth model to enhance locating local earthquakes.
S phases¶
In order to deliver high-quality picks from S phases, the scanloc package also includes the saic plugin with the enhanced S-phase picker. The S-phase picker can be applied to detect S phases on the horizontal components or on the vertical component in case of 1-component sensors. In addition the scanloc package comes with the graphical debugger for the S-phase picker provided by the spickdbg plugin.
Auxiliary tools¶
The scanloc package also ships with auxiliary Python script for real-time or non-real-time playbacks or tuning. Read the dedicated section for more details.
Workflow¶
scanloc processes picks and origins in the following order:
Buffering of picks and origins,
Clustering of P picks:
cluster formation,
splitting of clusters in case of multiple P picks from the same station.
Clustering is skipped in case of an external origin.
Association of P and S picks to clusters and external origins.
Locating origins and formation of internal events,
Evaluation and sending of origins.

Figure 2: Simplified work flow of scanloc.¶
Pick and origin buffering¶
The entry point of scanloc is the addObject method which handles incoming objects from the messaging system. By default it is subscribed to the messaging group PICK and LOCATION. Depending on which object type (pick or origin) is incoming different working steps are proceeded.
In case a pick arrives, scanloc
tests the evaluation status. Rejected picks are ignored unless the command-line option
--allow-rejected-picks
is given.adds the pick to the pick buffer keeping it for the time given by
buffer.pickKeep
or--pick-keep
,tries to use the pick for clustering,
checks if the pick can be associate to origins in the origin buffer exceeding a configurable
minScore
. In case the pick can be associated, the scores for all new origins are calculated and the origin with the highest score is selected.
In case an origin arrives, scanloc
tests the evaluation mode. Manual origins are ignored unless
buffer.ignoreManualOrigins
= false,adds the origin to the origin buffer keeping it the time given by
buffer.originKeep
or--origin-keep
seconds,tries to associate additional picks to the origin.
Adjust the buffer.*
parameters according to the times these objects
are required for processing.
Clustering¶
In case the pick cannot be associated, the cluster search is started. The
cluster search is based on the algorithm DBSCAN [1] which
takes the required number of neighbours (clusterSearch.minSize
)
and clusterSearch.maxSearchDist
as configuration parameters.
The algorithm forms clusters of picks by searching for neighboring stations
that have picks. Internal origins are formed from clusters.
The number of origins from cluster search is limited by the configuration parameter
clusterSearch.maxOrigins
.
The cluster search considers picks from stations by with:
where maxSearchDist is configurable by clusterSearch.maxSearchDist
.
is the vector sum of the time difference
between the picks in units of seconds and of a potential travel time
between the stations in units of seconds:
and
where is the spatial distance between the stations in units of km and
is the
clusterSearch.averageVelocity
in units of km/s. Therefore
and
clusterSearch.maxSearchDist
take units of seconds.
As the cluster search is done over time and location, the additional configurable
velocity parameter, clusterSearch.averageVelocity
, is required to transform
the input parameters of the cluster search in the same dimension (time).
The velocity should represent the average apparent horizontal P-wave velocity of
the crust.
Warning
When the number of buffered cluster origins reaches clusterSearch.maxOrigins
,
no more new origins can be formed and warnings are issued. Adjust accordingly:
Limiting in time¶
In real time picks are received in the order of their creation times. They are
considered for clustering if their pick times are within a time window
before the cluster reference time. The time window is defined by
clusterSearch.maxPickDelay
but the cluster reference time is defined
either by the
Pick time of the latest pick of the received picks when
clusterSearch.referenceTimeMode
= ‘LastPick’ (default),Pick time of the latest received pick which defines are group of N picks within
clusterSearch.maxPickDelay
whenclusterSearch.referenceTimeMode
= ‘MaxPickDelay’. Here, N is the maximum ofclusterSearch.minSize
andassociation.minPhase
. This mode is relevant if only very few stations with significantly different data delay provide the picks. Otherwise picks may not be available for clustering at the same time preventing to form clusters and new origins.
Thus, when setting clusterSearch.referenceTimeMode
= ‘MaxPickDelay’ re-setting
the cluster reference time is delayed depending on the amount and density of incoming picks.
With this option picks which have a larger delay can be considered. Such delays
occur, e.g., due to larger data delays or larger record lengths.
where
:time at which the pick was made,
: actual time of the phase arrival.
Picks available within a trapezoid-like time window are considered for
clustering.
For a pick with zero delay, the cluster reference time is initially set and picks
within the blue trapezoid (figure below) are considered.
Normally, picks have some delay which delays defining the trapezoid. This makes accessible
other picks available with some delay, too, allowing these picks to be considered
(green trapezoid). Subsequently, the trapezoid is extended until the
cluster reference time is updated.
This may be the next pick with a larger pick time
(olive trapezoid, clusterSearch.referenceTimeMode
= ‘LastPick’) or
the time of the pick which is preceded by at least clusterSearch.minSize
picks within clusterSearch.maxPickDelay
(yellow trapezoid,
clusterSearch.referenceTimeMode
= ‘MinPickDelay’).
Thus, picks which have a long delay do not fall within the relevant trapezoid and
cannot be considered for clustering as they are not available at the time of clustering.
The trapezoid is set with respect to the cluster reference time, CRT1 in the figure below, considering the delay of the defining pick and the time until the next relevant pick which updates the reference time (CRT2):
CRT2 with
clusterSearch.referenceTimeMode
= ‘LastPick’ orDeleyed CRT2 since
clusterSearch.referenceTimeMode
= ‘MaxPickDelay’.
The longer the time until the update, the more picks with larger delays can be considered for clustering, e.g., the delayed clustered pick in the figure below.

Figure 3: Pick time vs. pick delay time for of picks for clustering.
The cluster reference time determines the trapezoid within which picks can be
considered for clustering.
Here, the delayed clustered pick only becomes part of the cluster with
clusterSearch.referenceTimeMode
= ‘MaxPickDelay’.¶
Note
For small and similar delays of all P picks,
clusterSearch.maxPickDelay
can be directly read from travel-time curves. A small margin should be added account for differences in delay.In XML playbacks, the creation times may not be representative of real-time conditions. Therefore, pick times may be used for the timing instead of creation times. Read the section Examples and Playbacks for more details and the consequences.
If picks arrive with a larger delay than others, there is a risk that they cannot
be condsidered anymore for the cluster. When only few picks are available the events
may then be missed. To overcome the issue, you may increase clusterSearch.maxPickDelay
or set the parameter clusterSearch.referenceTimeMode
= “MaxPickDelay”.
While increasing clusterSearch.maxPickDelay
may slow down the clustering
and increase the risk to cluster unrelated picks,
clusterSearch.referenceTimeMode
= “MaxPickDelay” will only increase the
cluster reference time if at least clusterSearch.minSize
P picks are
available in the considered time window. Run scanloc on the command line
with the --cluster-search-log-file
to learn about cluster reference
times and the considered picks. As suggestion for clusterSearch.maxPickDelay
is provided in the summary section at the end of the resulting output. For more
options read the section Tuning and optimization.
Within one cluster, the difference in the pick times between the
cluster reference time and any other pick must thus not exceed clusterSearch.maxPickDelay
.
Otherwise the pick is rejected from clustering. The parameter clusterSearch.maxPickDelay
has a big impact on the performance of the cluster search. Choosing the parameter
as small as possible will speed up scanloc and will reduce the complexity of the
cluster search.
The DBSCAN algorithm can deliver multiple pick clusters. The cluster search can
be disabled using clusterSearch.maxPickDelay
:
# Maximum allowed difference between P pick and cluster reference time(latest pick time).
# The cluster search ignores all picks which exceed the value. Using "-1" enables all picks
# regardless of the delay. Unit: seconds.
clusterSearch.maxPickDelay = 0
Then, only external origin can be considered for phase association.
Limiting in space¶
The cluster search can be constraint to stations within a region given by the
coordinate of a central point and the radius around that point. The region constraint
is configured through clusterSearch.regionFilter
. Applying this parameter
will disregard picks from stations outside the region for cluster search increasing
the speed and the complexity. Nevertheless, the excluded picks are available for
phase association.
For running the cluster search in several regions in parallel, different instances of scanloc taking picks from the same of different pickers can be created and started.
Cluster splitting¶
Clusters may contain P picks from the same station. Therefore, the clusters are
split separating clusters with only one pick per stations. All new clusters are
considered new origins. By activating clusterSearch.checkOrigins
, all
new clusters are checked again
and clusters not meeting the configured cluster criteria are removed from the buffer.
The check imposes an additional overhead on the cluster search but it typically
lowers the chance for fake solutions and it also lowers the load on the
phase association.
Tuning and optimization¶
Use the option --cluster-search-log-file
to store detailed information
on the clustering process in a file, e.g., cluster.log. The given values can be
used to optimize the cluster search parameters.
scanloc --ep picks.xml -d [database] --cluster-search-log-file cluster.log > origins.xml
For optimizing the configuration of the parameter clusterSearch.maxPickDelay
use the default value first:
clusterSearch.maxPickDelay = -1
The given output file contains the clusters with the pick details. After each cluster the maximum time interval between the first and the last pick in the cluster is provided. A summary at the end of the file shows the largest value, e.g.:
+ cluster source: -69.6279, -21.4715, 1231891115.191
+ pick ID: *20090113.235827.36-AIC-CX.PB01..HHZ X: -69.4874 Y: -21.0432 time: 1231891107.368 distance: 14.715 s
+ pick ID: 20090113.235832.91-AIC-CX.PB02..HHZ X: -69.8960 Y: -21.3197 time: 1231891112.918 distance: 8.443 s
+ pick ID: 20090113.235839.53-AIC-CX.PB07..HHZ X: -69.8862 Y: -21.7267 time: 1231891119.538 distance: 10.677 s
+ pick ID: 20090113.235840.94-AIC-CX.PB09..HHZ X: -69.2419 Y: -21.7964 time: 1231891120.940 distance: 14.645 s
+ 1 split cluster
+ cluster
+ 20090113.235827.36-AIC-CX.PB01..HHZ
+ 20090113.235832.91-AIC-CX.PB02..HHZ
+ 20090113.235839.53-AIC-CX.PB07..HHZ
+ 20090113.235840.94-AIC-CX.PB09..HHZ
+ maximum pick time interval for this cluster: 13.572 s
+ minimum maxPickDelay required for this cluster: 13.572 s
+ end
+ end
+ end
+ end
+ summary:
+ maximum experienced cluster time interval: 40.840 s
+ minimum value of clusterSearch.maxPickDelay for all clusters: 13.572 s
The summary value can be used as a lower proxy to set
clusterSearch.maxPickDelay
.
Locating¶
Clusters are located by the configured locator. If the
location fails, the origin is ignored unless clusterSearch.preliminary
is active. Then, preliminary values are chosen:
Origin location is the center of the detecting stations,
Origin time is the time of the first phase pick,
Status is set to preliminary.
The status will be unset if more phases can be associated and the new origin can be located.
Phase Association¶
When a cluster of P picks meeting association.minPhase
is found
or an external origin arrives, scanloc tries
to associates additional P- and S-type phase picks which are
buffered and which meet the association criteria:
P-type picks:
the epicentral distance does not exceed
association.maxDist
,no other P pick from the same channel exists in the origin,
the pick time,
, of the new pick is close to the arrival time predicted by the travel-time interface,
, considering
association.maxPResidual
:
S-type picks:
the epicentral distance does not exceed
association.maxDist
,the evaluation mode of the pick is manual or the pick references a P pick which has been already associated. The reference to a P pick is given as a comment of the S pick. Example:
<pick> ... <comment> <text>Pick/20230726100411.964268.1316601</text> <id>RefPickID</id> </comment> </pick>
The reference check serves as a quality control feature. I can be dropped by
--drop-reference-check
andassociation.dropReferenceCheck
.the pick time,
, of the new pick is close to the arrival time predicted by the travel-time interface,
, considering
association.maxSResidual
:
The new set of picks are used for relocating.
In case the buffered pick is a P pick the algorithm
directly attempts to associate the pick solely based on the residual. It tries
to relocate
the solution after each successful association. P picks with travel-time
residuals larger than association.maxResidual
are rejected.
After the P-picks are associated and relocated, scanloc tries to associate the
S picks. This association is not based
on the residual but on the P pick referenced by the S pick. The S pick is
only associated in case the reference P pick is already associated to the
origin. Also after each S pick a relocation is done. In case the relocation
fails or the event residual is larger than maxRMS
,
the S pick is associated with a weight of 0. The score of the resulting
origin is compared with scores of origins belonging to the same event. In case
the score is higher than the rest of the origins, the origin is
sent out.
In addition to origins from the cluster search, scanloc can also treat external origins that are created by other associators, e.g., scautoloc [9]. In case an such origin is received scanloc tries to associate all picks in the buffer to the origin. The association and the following processes are the same as described above. See figure Simplified work flow of scanloc. for an overview.
The maximum epicentral distance up to which picks are considered is configured
by association.maxDist
. However, this parameter can be overruled per
network and station by providing a station table in a file given by
association.stationConfig
. As in scautoloc [9] each line of the
table consists of the network code, the station code, a switch and the maximum
epicentral distance in degrees. Wildcards can be used for the network and the
station code. The switch causes the associator to consider (=1) or to ignore
(=0) a network or a station.
The last occurrence of an item in a table overrules previous ones, e.g.
* * 1 180
GR * 1 60
GR GRA1 1 20
Z3 * 0 180
For associating the picks, travel times from look-up tables are used. The
association.tableType
and the association.table
can be
configured to provide specific tables which may be more appropriate for specific
regions. Currently, only travel-time tables of association.tableType
from LOCSAT and libtau are supported. scanloc provides
densely-sampled travel-time tables for LOCSAT.
Travel times from other sources can be considered by a plugin exposing the travel times to the travel-time interface. The considered table must provide the time for all considered phases.
Example configuration (scanloc.cfg
):
# Type of travel-time tables for phase association. May be different from locator.
# Use e.g. libtau or LOCSAT.
association.tableType = LOCSAT
# Name of travel-time table used for phase association. May be different from locator
# profile.
association.table = iasp91_scanloc
location of |
|
---|---|
libtau |
@DATADIR@/ttt |
LOCSAT |
@DATADIR@/locsat/tables |
Note
Travel-time tables used during association and location may be different.
Therefore the travel-time residuals visible after relocating may be different
from the travel-time residuals considered during association.
The differences must be considered when configuring association.maxPResidual
and association.maxSResidual
.
In order to make the alternative locator available to scanloc, the respective plugin must be loaded. The list of available locators can be provided by scanloc:
scanloc --locator-list
Note: Computational speed can be an issue when alternative locators are used and when many picks are to be tested during association. In this case scanloc can be configured with LOCSAT [4] but screloc [17] may be used along with the preferred locator and profile to relocate the origin. The loator Lomax [25] is certainly too slow for being used in scanloc but is a good option for screloc.
Processing external origins¶
Origins received from other modules through the messaging or provided by XML files
can be processed and more phases can be associated. In
order to ignore such external origins set buffer.ignoreOrigins
:
buffer.ignoreOrigins = false
Processing of external origins may be undesired when
Involving other modules excepting origins by the messaging system, e.g., screloc [17]. These modules may run in a loop with scanloc.
Receiving origins from parallel systems.
Configure buffer.originAuthorWhiteList
with the author names of
origins which shall be processed, e.g., scautoloc [9]:
buffer.originAuthorWhiteList = scautoloc@localhost
Automatic origins from all other authors will be ignored.
Status of origins¶
The status of origins can be set during pick processing
Normally, the status of origins is unset.
The status of origins from cluster search which cannot be relocated is preliminary.
The status of origins which can be located is set to unset if the origin status of the origin was previously set.
However, the evaluation status may be later changed at different times by different modules, e.g., the gempa module sceval. In order to track this history a journal entry is created and sent when running scanloc with a connection to the messaging or added to the XML output long with the origins. In future versions of SeisComP such journal entries will be made accessible in scolv.
Sending of origins¶
Before sending a new internal origin to the messaging or to XML output (–ep) it is tested against the configuration:
Picks are removed when their travel-time residual >
association.maxResidual
and origins are relocated,Origins are skipped when the score <
minScore
,Origins are skipped when the depth >
ignoreDepth
.
The remaining internal origins are evaluated based on scoring.
The best origin of the same internal event is the one
which has the highest score at the time of availability. When meeting the parameters
ignoreDepth
, maxRMS
and minScore
it is sent to the
SeisComP messaging [6] or to stdout in case of XML playbacks
(–ep).
The sending of origins may be delayed allowing to find new origins with higher score.
The delay reduces the amount of origins in the SeisComP system and the load of other modules.
It is controlled by the publication.*
configuration parameters.
Note
In XML-based playbacks, the publication.*
configuration parameters
are ignored and all origins are sent.
Internal Origins and Events¶
scanloc forms
Internal origins from the locations and the associated picks (arrivals) of new arrival sets,
Internal events from internal origins based on the
eventAssociation.*
parameters. The procedure is similar to scevent [13]. An origin is compared to the preferred origin of an existing internal event. It is associated to the existing internal event if one of the criteria applies:the origins share a minimum of
eventAssociation.minMatchingArrivals
arrivals. Arrivals must be identical by the ID of the referenced pick unlesseventAssociation.compareAllArrivalTimes
= true. Then, a margin ofeventAssociation.maxMatchingArrivalTimeDiff
applies for considering different picks to be the same.the differences in origin time AND epicenter is within
eventAssociation.maxTimeSpan
ANDeventAssociation.maxDist
, respectively.
Only if the score of a new origin exceeds the score of the last sent origin of the same internal event, the new origin is sent out.
Locating Origins¶
scanloc locates internal origins based on the configuration by the locator.*
parameters.
Consider a fast locator (locator.type
), e.g., LOCSAT or Hypo71 [2]
and appropriate travel-time tables locator.profile
,
e.g., the provided dense travel-time tables.
If the location fails and locator.fixDepth
is active, the location
depth is fixed to defaultDepth
and the origin is relocated.
Example configuration (scanloc.cfg
):
# The locator type to use
locator.type = LOCSAT
# The locator profile to use
locator.profile = iasp91_scanloc
Scoring Origins¶
Each internal origin is evaluated by calculating a
.
The
is calculated as a weighted sum from the number of associated
P and S picks (pCount and pCount), of loosely associated P and S picks
(p0Count and s0Count) which are not used for locating, depth (depthFactor) and
residual (residualFactor):
The weight factors score.weights.p
, score.weights.p0
,
score.weights.s
, score.weights.s0
score.weights.depth
and score.weights.residual
can be configured.
The values for depthFactor and residualFactor are derived from considered
depth and residual and the configured values for
ignoreDepth
and association.maxResidual
.
Higher weight is given to origins with shallower depth. Adjust
score.weights.depth
to form the score
independent of depth, e.g., in regions with shallow and deep seismicity:
score.weights.depth = 0
Redundant Systems¶
In redundant systems where origins are received from other machines with idential or simialar setup you may wish to suppress re-processing these origins. Read section Processing external origins for the configuration.
Association of Teleseismic Phases¶
Dense local networks used to monitor local seismicity are often able to catch also a significant number of phases from earthquakes at teleseismic distances. Such phases include Pdiff or PKP. Especially PKP may contain a significant amount of energy at higher frequencies. Therefore PKP is often detected by networks that are tuned to detect local earthquakes. Due to the steep incidence and the low horizontal slowness of these phases, they are sometimes located as fake deep earthquakes below the network. scanloc can be used to suppress this type of fake events.
In a 2-pipeline setup, scanloc can associcate such teleseismic phases recorded by the local network with origins that were found by the pipeline for monitoring teleseismic earthquakes. Then scevent [13] will associate the origins from the teleseismic pipeline with the fake origins from the pipeline for local monitoring to the same event. The assumption is that the origins from the teleseismic pipeline win over the origins from pipeline for local monitoring because they have more associated arrivals. In this case the origins from pipeline for teleseismic monitoring that has most phases becomes the preferred origin for the event. This scanloc feature requires an extended license.
Setup of a 2-pipeline system
Generate a 2-pipeline system involving at least scautopick [10], scanloc and scevent [13] :
Pipeline 1 monitors teleseismic earthquakes using scautopick, scautoloc, scanloc and default message groups.
Pipeline 2 monitors local earthquakes using l1autopick, l1autoloc and l1scanloc using the message groups L1PICK and L1LOCATION.
Let scanloc not perform cluster search (
clusterSearch.maxOrigins
= 0) but allow scanloc to only associate P picks from pipelines 2 based on origins from scautoloc (connection.subscriptions = “LOCATION, L1PICK” in the global module parameters). Configure scanloc to associate the picks from pipeline 2 as picks with zero weight when they are, e.g., in the PKP or Pdiff distance range. Use one zeroWeight profiles per phase.In order to facilitate association of teleseismic picks, the picks and the origins must be kept in memory for sufficient time. Increase
buffer.pickKeep
andbuffer.originKeep
accordingly, e.g., to 1800 s.In this way zero-weight picks will not be used for locating the event but are part of the origin and can be considered by scevent.
Configure scevent to listen to the message groups from both pipelines (e.g. LOCATION and L1LOCATION) and activate the scevent module parameter eventAssociation.allowLooseAssociatedArrivals (
scevent.cfg
).Figure 4: Parameter exchange in a 2-pipeline system. The messaging system, responsible for the parameter exchange, is representated by the circles, indicating the message groups. Teleseismic monitoring is configured with scautopick, scanloc, scautoloc and local monitoring with l1autopick, l1scanloc, l1autoloc.¶
Playback using picks and amplitudes from 2-pipeline system (real-event examples)

Figure 5: Location tab in scolv with zero-weight picks associated by scanloc as PKP phases.¶

Figure 6: Event tab in scolv showing the origins from the pipelines for local and teleseseismic monitoring. The preferred origin located near the Solomon Islands is shown in bold on top. Fake origins in Europe located by pipeline for local monitoring based on PKP phases falsely considered P phases are associated to the event but do not form the preferred origin at any time.¶
Examples and Playbacks¶
Run scanloc during real-time processing:
seiscomp start scanloc
Run scanloc on the command line for real-time processing or message-based playbacks with debugging output:
scanloc --debug
Note
In playbacks of picks in XML files the performance of scanloc may differ from real-time operation based on messaging:
In real-time operation, the picks are made e.g., by scautopick at some time and considered by scanloc according to their creation times. Delayed picks may become irrelevant for the processing. Configure
buffer.pickKeep
andbuffer.originKeep
accordingly.However, the creation times of picks may be obscured when created in a scautopick playback and picks may have almost identical creation times independent of their pick times.
In message-based playbacks, picks are provided to scanloc via the messaging system. When created in real time, the creation times of picks form a realistic time reference for scanloc and is therefore considered.
In non-real-time XML playbacks (
--ep
), scanloc considers picks by default according to their actual pick times. For picks created in a non-real-time playback this is most reasonable as creation time is not a valid time reference anymore. However, referencing to pick time may result in a behavior which is different from real-time conditions.Therefore, for mimicking real-time conditions in playbacks of picks obtained in real-time conditions consider the command-line option
--timing creationTime
.
Real-time playbacks¶
Message-based real-time playbacks are useful to test the behavior of scanloc in real time based on picks generated before by:
Real-time picking where the order of the picks is represented by the creation time.
Picking in a non-real-time playback where picks are created at high speed and creation time is not a useful measure of the timing in real time.
This type of playbacks is supported by auxialiary scripts shipped with the scanloc package.
Picks from real-time picking: Use phase picks obtained in real-time.
Procedure:
Read real-time picks from the database and store them in SCML in a file,
picks.xml
, for later playback. Additional command-line options may be used to constrain the pick set:dump_picks -d [database] -t "2022-04-01 08:00:00.00~2022-04-01 08:05:00.00" -o picks.xml
Play back picks in the SCML file them to the SeisComP messaging. Start scanloc separately for debugging on the command line considering default timing by creation time of the picks:
seiscomp stop seiscomp start scmaster scamp scmag scevent scanloc --debug playback_picks picks.xml
Picks from playbacks: Play back picks and amplitudes created by a non-real-time playback possibly in different pipeline [7] sending them to the SeisComP messaging.
Picks and amplitudes are created in playbacks by scautoloc [9] and stored in XML files (SCML format).
Picks and amplitudes are sent to the separate message groups PICK, L1PICK and AMPLITUDE.
scanloc and l1scanloc listen to picks from PICK and L1PICKS, respectively.
scautoloc [9] additionally needs the pick amplitudes from the subscribed amplitude groups.
Procedure:
Create the pick files including picks and amplitudes in a non-real-time XML playback by the modules as in your 2-pipeline system. Since picks and amplitudes are created by the playback, their creation time is not a relevant measure of the order in which they were created.
scautopick -d [database] --ep --playback -I [your_waveforms] > picks.xml l1autopick -d [database] --ep --playback -I [your_waveforms] > l1picks.xml
Start all required modules including the scanloc instances
seiscomp start scmaster scamp scmag scevent scautoloc l1autoloc scanloc l1scanloc
Execute playback_picks with
--timing pickTime
for sending the picks and amplitudes created by different pickers at different times. Consider timing by pick time of the picks:--timing pickTime
is used as an approixmation of the timing since creation time is not meaningful in this XML playback.playback_picks picks.xml:PICK:AMPLITUDE l1picks.xml:L1PICK:AMPLITUDE --timing pickTime
Non-real-time playbacks¶
Non-real-time (XML) playbacks are used for very fast processing of picks in XML files. The picks were generated before in
Real time and read from the database e.g., by dump_picks or
By non-real-time playbacks, e.g., involving scautopick [10].
In XML playbacks, the picks are provided to scanloc
in a XML file (SCML format) with the option --ep
.
scanloc writes the results in SCML to stdout which can be re-directed
into a file for further processing.
Note
Execute scanloc always with the appropriate timing.
When picks are created in a non-real-time playback use scanloc with timing
by pick time corresponding to --timing pickTime
which is the default in
playbacks. For picks obtained
in real time you should use scanloc with the command-line option
--timing creationTime
for setting the timing to creation time.
Play back picks stored in XML format to locate events and to determined the magnitude. Intermediate results are stored in XML files. Inventory and bindings configuration are read from the database. The playback is indendent of the messaging. Execute scanloc with the appropriate timing.
Procedure:
Run the playback
scautopick -d [database] --ep --playback -I [your_waveforms]> picks.xml scanloc -d [database] --ep picks.xml --timing [timing] > origins.xml scamp -d [database] --ep origins.xml -I [your_waveforms] > amps.xml scmag -d [database] --ep amps.xml > mags.xml scevent -d [database] --ep mags.xml > events.xml
Enter the results into the SeisComP system. Either:
Events do not exist in the database, use scdb [11] to populate the database with all events in
events.xml
.scdb -i events.xml -d [database]
Events may exist in the database. Update existing events by associating new origins or create new events. Run the messaging system and all modules that shall process the new parameters, e.g. scamp [8], scmag [14] , scevent [13]. Use scdispatch [12] to send the new objects to the messaging system.
seiscomp start scmaster scamp scmag scevent scdispatch -H host -i mags.xml
Instead of the
mags.xml
, other parameters created by the playback may be dispatched, e.g., fromorigins.xml
.
Warning
Using scdb [11] for writing event information to the database may result in duplicates if the provided parameters, e.g., events, exist already with another ID. In this case use scdispatch [12] with
mags.xml
and running scmaster [15] and scevent [13] instead of scdb [11]. However, scdispatch in newer versions of SeisComP allows ignoring Event objects with the option-e
. Then, alsoevents.xml
can be dispatched.
Play back picks stored in XML format, without a database but inventory and bindings in SCML and with a local file for module configuration.
Procedure:
Set up a local module configuration file, e.g.,
./scanloc.cfg
containing all parameters includingcore.plugins
.Store the station inventory and the binding configuration from a database in SCML:
scxmldump -d [database] -fI -o inventory.xml scxmldump -d [database] -fC -o config.xml
Continue with the examples above replacing the database parameter
-d [database]
with--inventory-db inventory.xml
--config-db config.xml
and adding the module configuration inscanloc.cfg
. Set the timing accordingly:scanloc --inventory-db inventory.xml --config-db config.xml \ --ep picks.xml --timing [timing] \ --config-file scanloc.cfg > origins.xml
Module Configuration¶
etc/defaults/global.cfg
etc/defaults/scanloc.cfg
etc/global.cfg
etc/scanloc.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scanloc.cfg
scanloc 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
- defaultDepth¶
Default:
5.0
Unit: km
Type: float
Default source depth used for locating origins.
- ignoreDepth¶
Default:
650.0
Unit: km
Type: float
Maximum depth of an origin to be sent.
- maxRMS¶
Default:
1.5
Unit: s
Type: float
Maximum allowed overall residual of an origin to be sent.
- minScore¶
Default:
0.0
Type: float
Minimum score of an origin to be sent.
Note
buffer.* Define buffering of picks and origins. scanloc only treats picks and origins kept in the buffer.
- buffer.pickKeep¶
Default:
180.0
Unit: s
Type: float
Time to keep picks. Time comparison is based on the pick times. In non-real time playbacks the time to keep picks is usually compressed.
- buffer.pickIgnoreStreamID¶
Type: list::string
Ignore picks created on given stream ID(s). Stream IDs may contain wildcards. Separate multiple IDs by comma.
- buffer.originKeep¶
Default:
180.0
Unit: s
Type: float
Time to keep origins. Time comparison is based on the origin times. In non-real time playbacks the time to keep orgins is usually compressed.
- buffer.ignoreOrigins¶
Default:
false
Type: boolean
Ignore and do not buffer external origins received from messaging or from XML files.
Default: Accept external origins from messaging or XML and associate more phases.
- buffer.ignoreManualOrigins¶
Default:
true
Type: boolean
Ignore and do not buffer manual external origins received from messaging or from XML files.
The parameter "buffer.ignoreOrigins" must be inactive for this option to be effective.
- buffer.originStatusIgnore¶
Type: list:string
Ignore an external origin if its status has any of the given states. Supported states: rejected,reported,preliminary,confirmed,reviewed,final
The option is ignored for manual origins if buffer.ignoreManualOrigins = false.
- buffer.originAuthorWhiteList¶
Type: list:string
Only add external origins from the given authors to the buffer. Separate multiple authors by comma. If omitted, no filtering is applied. Manual origins are treated regardless of the author as defined by "buffer.ignoreManualOrigins".
The parameter "buffer.ignoreOrigins" must be inactive for this option to be effective.
Note
clusterSearch.* Parameters controlling the cluster search based on phase picks of configured phase type.
- clusterSearch.phaseType¶
Default:
P
Type: string
Phase type of considered picks. Valid types: P or Is.
- clusterSearch.minSize¶
Default:
4
Type: int
Minimum number of core points (picks) to form a cluster.
- clusterSearch.maxPickDelay¶
Default:
-1.0
Unit: s
Type: float
Maximum allowed difference between considered picks and cluster reference time (latest pick time). Optimum values can be derived from travel times.The cluster search ignores all picks which exceed the value. Using "-1" enables all picks regardless of the delay.
- clusterSearch.referenceTimeMode¶
Default:
LastPick
Type: string
Mode to set the cluster reference time. Read the documentation for the details. Available modes:
LastPick: The pick time of the last incoming P pick is the cluster reference time.
MaxPickDelay: Setting the cluster reference time is delayed until clusterSearch.minSize and association.minPhase picks are available.
- clusterSearch.regionFilter¶
Type: list:double
Cluster only picks which sensor locations are inside the defined region. The region is defined by latitude, longitude and a radius in km. By default the region filter is disabled.
Example: 50.1,12.3,20
- clusterSearch.averageVelocity¶
Default:
4.0
Unit: km/s
Type: float
Average velocity used for distance calculation.
- clusterSearch.maxSearchDist¶
Default:
60
Unit: s
Type: float
Maximum allowed distance over all core points and maximum allowed distance for neighborhood search. Both account for travel-time difference, inter-station distance and the configured averageVelocity.
- clusterSearch.maxOrigins¶
Default:
128
Type: uint
Maximum allowed origins derived from cluster search. Set this option to zero to disable the cluster search completly.
- clusterSearch.preliminary¶
Default:
false
Type: boolean
Send origins based on cluster search as preliminary origins if the location fails. Otherwise those origins are ignored. Consider activating "checkOrigins".
- clusterSearch.checkOrigins¶
Default:
false
Type: boolean
Check, if derived origins fulfill the cluster search criteria anymore. Activating this option may lower the number of events and suppress fake events.
- clusterSearch.ignorePickTimeDifference¶
Default:
0.0
Unit: s
Type: float
New clusters are formed when new picks arrive and previous clusters have already a pick with the same stream ID as the new pick. Use this option to ignore new picks with the given time difference to cluster picks with the same stream ID.
Note
association.* Parameters controlling the association of P and S phases to cluster origins or external origins.
- association.minPhase¶
Default:
4
Type: int
Number picks in cluster origin to be reached for starting to associate more P nd S picks.
- association.maxDist¶
Default:
1000.0
Unit: km
Type: float
Maximum epicentral distance to associate P and S picks.
- association.stationConfig¶
Type: path
The station configuration file contains lines consisting of network code, station code, weight (0 or 1) and maximum association distance given in degree. The maximum association distance is the distance in degrees from the origin up to which this station may contribute to a new origin. This parameter overrides the global parameter association.maxDist. If this distance is 180 deg, this station may contribute to new origins world-wide. However, if the distance is only 10 degree, the range of this station is limited. This is a helpful setting in case of mediocre stations in a region where there are numerous good and reliable stations nearby. The station will then not pose a risk for locations generated outside the maximum association distance. The last item found in the list overrules previous ones. Network and station codes may be wildcards (*) for convenience. E.g.:
* * 1 10
GE * 1 180
- association.maxPResidual¶
Default:
4.0
Unit: s
Type: float
Maximum allowed difference between measured and predicted arrival times for associating P phases to origin. Larger values allow significant correction of initial locations.
- association.dropReferenceCheck¶
Default:
false
Type: boolean
Allow S-type picks without checking for a reference pick. References to P picks are typically added to S picks by scautopick but picks from other modules may not have this feature. When this option is active, the reference pick is not tested at all.
- association.maxSResidual¶
Default:
4.0
Unit: s
Type: float
Maximum allowed difference between measured and predicted arrival time for associating S phases to origins. Larger values allow significant correction of initial locations.
- association.maxResidual¶
Default:
2.0
Unit: s
Type: float
Maximum allowed time residuals of picks after association and relocation. Picks will be removed at exceedance starting with largest residual and origins will be relocated.
- association.tableType¶
Default:
LOCSAT
Type: string
Type of travel-time tables for phase association. May be different from locator. Use e.g. libtau or LOCSAT.
- association.table¶
Default:
iasp91
Type: string
Name of travel-time table used for phase association. May be different from locator profile. Using a different table/profile may result in increased runtime.
- association.zeroWeightProfiles¶
Type: list:string
zeroWeight-profile name for associating the configured phases with zero weight to origins. Multiples profile names may be set separated by comma. The order of names determines order of checked phases. Each profile can have different parameters.
Note
association.zeroWeight.* zeroWeight profiles containing the parameters for associating phases with zero weight to origins.
Note
association.zeroWeight.$name.*
$name is a placeholder for the name to be used and needs to be added to zeroWeight.profiles
to become active.
zeroWeight.profiles = a,b
association.zeroWeight.a.value1 = ...
association.zeroWeight.b.value1 = ...
# c is not active because it has not been added
# to the list of zeroWeight.profiles
association.zeroWeight.c.value1 = ...
- association.zeroWeight.$name.phaseType¶
Type: String
One phase type to be associated with zero weight. Examples: PKP or Pdiff.
- association.zeroWeight.$name.minDistance¶
Default:
120.0
Unit: degree
Type: float
Minimum epicentral distance.
- association.zeroWeight.$name.maxResidual¶
Default:
5.0
Unit: s
Type: float
Maximum time residual of the associated phase.
Note
locator.* Parameters controlling the locator for locating scanloc origins.
- locator.type¶
Default:
LOCSAT
Type: string
The locator type to be used. Use e.g. LOCSAT or Hypo71.
- locator.profile¶
Default:
iasp91
Type: string
The locator profile to be used. Using a different profile/table for locating and associating may result in increased runtime.
- locator.fixDepth¶
Default:
false
Type: boolean
If enabled, the locator fixes the depth to the configured default value "defaultDepth" in case that all previous attempts to relocate fail. This option may result in many more origins. It prevents "ignoreDepth" from beeing effective if "defaultDepth" < "ignoreDepth".
Note
eventAssociation.* Parameters controlling the association of interal scanloc origins to internal scanloc events.
- eventAssociation.compareAllArrivalTimes¶
Default:
false
Type: boolean
This parameter is only used in conjunction with eventAssociation.maximumMatchingArrivalTimeDiff. If a station has multiple associated arrivals for a particular event, this flag defines if the time distance of a new pick to all arrivals must be within eventAssociation.maximumMatchingArrivalTimeDiff or if one matching arrival is enough.
- eventAssociation.minMatchingArrivals¶
Default:
3
Type: int
Minimum number of matching picks between two origins to be associated to the same event.
- eventAssociation.maxMatchingArrivalTimeDiff¶
Default:
-1
Unit: s
Type: float
If this time window in seconds is negative, pickIDs are compared to find matching arrivals. A non negative value (including 0) compares pick times regardless of the pickID. Pass: |pick1.time - pick2.time| <= threshold.
- eventAssociation.maxDist¶
Default:
500.0
Unit: km
Type: double
Allowed difference in epicenter between an incoming origin compared with preferred origins to get associated.
- eventAssociation.maxTimeSpan¶
Default:
60.0
Unit: s
Type: double
Associates an origin with an existing event if the origin time differs not more than 60 seconds unless the minimumMatchingArrivals criteria matches.
Note
score.weights.* Weight factors controlling the scoring of internal origins based on the following components: used P-phase (p), unused P-phase (p0), used S-phase (s), unused S-phase (s0), depth and residual.
- score.weights.p¶
Default:
1.0
Type: float
The weight of number of P arrivals. Also used for Is when considered for clustering.
- score.weights.p0¶
Default:
0.5
Type: float
The weight of number of added but unused P arrivals. Also used for Is when considered for clustering.
- score.weights.s¶
Default:
2.0
Type: float
The weight of number of S arrivals for scoring.
- score.weights.s0¶
Default:
0.5
Type: float
The weight of number of added but unused S arrivals.
- score.weights.depth¶
Default:
1.0
Type: float
The weight of origin depth.
- score.weights.residual¶
Default:
1.0
Type: float
The weight of origin RMS residual.
- score.weights.increaseManual¶
Default:
false
Type: boolean
Increase the weight for manual picks by a factor of 1.001. This gives preference to manual picks in case automatic ones co-exist for the same station.
Note
publication.* Parameters controlling the publication of internal scanloc events as new origins to the messaging system.
- publication.intervalTimeSlope¶
Default:
0.5
Unit: s/count
Type: double
Parameter "a" in the equation t = aN + b.
t: time interval between sending updates of an origin
N: arrival count of the origin
Increasing the value reduces the amount of sent origins. With the option --ep (playback mode) this value is set to 0.
- publication.intervalTimeIntercept¶
Default:
0.0
Unit: s
Type: double
Parameter "b" in the equation t = aN + b.
t: time interval between sending updates of an origin
N: arrival count of the origin
Increasing the value reduces the amount of sent origins. With the option --ep (playback mode) this value is set to 0.
- publication.wakeUpInterval¶
Default:
5
Unit: s
Type: int
Integer interval to check the origin buffer for sending origins if no other origins have been created.
Reducing the value may be required in EEW: it increases the load on scanloc but allows to send origins more rapidly.
Command-Line Options¶
scanloc [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 &.
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.
- --print-component arg¶
For each log entry print the component right after the log level. By default the component output is enabled for file output but disabled for console 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 .
- --trace¶
Execute in trace mode. Equivalent to --verbosity=4 --console=1 --print-component=1 --print-context=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¶
Set sending of a start and a stop message.
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
Input¶
- --pick-keep arg¶
Overrides configuration parameter
pickKeep
.
- --origin-keep arg¶
Overrides configuration parameter
originKeep
.
- --allow-rejected-picks¶
Allow processing of picks with evaluation status ‘rejected’. Otherwise these picks are ignored.
- --drop-reference-check¶
Allow S-type picks without checking for a reference pick. References to P picks are typically added to S picks by scautopick but picks from other modules may not have this feature. When this option is active, the reference pick is not tested at all. Manual picks are always considered without a reference chseck.
- --filter-pick-author¶
Filter picks by author and only consider picks created by the given author. Empty string considers all authors. The option allows operation of scanloc based on picks from a specific picker module where only picks from one picker should be used, e.g. in tuning scanloc for a pipeline.
- --ep arg¶
Name of input XML file (SCML) with all picks and origins for offline processing. The database connection is not received from messaging and must be provided. Results are sent as XML to stdout.
- --timing arg¶
Offline processing reference timing mode: Use pickTime and creationTime for sorting picks according to pick time and creation time, respectively. scanloc uses creationTime in real-time processing.
Default: pickTime
Locator¶
- --locator-type arg¶
Overrides configuration parameter
locator.type
. The locator type to use. Default: LOCSAT.
- --locator-profile arg¶
Overrides configuration parameter
locator.profile
. The locator profile to use. Default: iasp91.
- --locator-list¶
List all registered locators.
Output¶
- --final-only¶
Limit result set to final origins only. This option is available for offline processing only.
- --dump-origins¶
Don’t publish origins, write them to stdout. Useful for tuning.
- --cluster-search-log-file arg¶
File name to output detailed cluster search information. Useful for tuning.