2025/share/man/man1/scanloc.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SCANLOC" "1" "Oct 08, 2025" "2025.281#4efc2c878" "scanloc: Phase Associator"
.SH NAME
scanloc \- scanloc: Phase Associator Documentation
.sp
\fBModule for locating local earthquakes and man\-made seismicity by DBSCAN
cluster search.\fP
.SH DESCRIPTION
.SS Low\-threshold monitoring
.sp
\fIscanloc\fP 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 [\fI\%2\fP]\&. Additional P and S phases are associated
to existing internal solutions from cluster search or solutions incoming through the messaging
system from external modules.
.sp
Due to the clustering and subsequent phase association scanloc facilitates low\-threshold
monitoring of high\- and low\-rate seismicity with high accuracy.
.INDENT 0.0
.INDENT 2.5
[image]
Figure 1: scolv Location tab with an automatic earthquake solution from scanloc based on
P and S phases..UNINDENT
.UNINDENT
.SS Teleseismic events
.sp
For teleseismic events \fIscanloc\fP can also be used to:
.INDENT 0.0
.IP \(bu 2
\fI\%Associate more picks from P and S phases\fP to external origins,
.IP \(bu 2
Suppress fake events due to detections from large earthquakes recorded by dense local networks at teleseismic distances.
A \fI\%dedicated section\fP explains the setup and the requirements.
.UNINDENT
.SS Travel\-time tables
.sp
The scanloc package ships with \fI\%densely sampled travel\-time tables\fP for
\fILOCSAT\fP [\fI\%5\fP] based on the IASP91 Earth model to enhance locating local earthquakes.
.SS S phases
.sp
In order to deliver high\-quality picks from S phases, the \fI\%scanloc\fP package
also includes the \fIsaic\fP plugin with the enhanced \fI\%S\-phase picker\fP\&.
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 \fI\%graphical debugger for the S\-phase picker\fP
provided by the \fIspickdbg\fP plugin.
.SS Array measurements
.sp
Detections from array measurements including detection time, slowness and
back azimuth can be fully considered by \fI\%scoring\fP
depending on the applied locator.
.SS Auxiliary tools
.sp
The scanloc package also ships with auxiliary Python script for
\fI\%real\-time or non\-real\-time playbacks\fP or tuning. Read the
\fI\%dedicated section\fP for more details.
.SH WORKFLOW
.sp
scanloc processes picks and origins in the following order:
.INDENT 0.0
.IP 1. 3
Buffering of \fI\%picks and origins\fP,
.IP 2. 3
\fI\%Clustering\fP of P picks:
.INDENT 3.0
.IP \(bu 2
cluster formation,
.IP \(bu 2
splitting of clusters in case of multiple P picks from the same station.
.UNINDENT
.sp
Clustering is skipped in case of an \fI\%external origin\fP\&.
.IP 3. 3
\fI\%Association\fP of P and S picks to clusters and external
origins.
.IP 4. 3
\fI\%Locating origins\fP and formation of
\fI\%internal events\fP,
.IP 5. 3
\fI\%Scoring of origins\fP and setting the preferred origin
accordingly of an internal events.
.IP 6. 3
Evaluation and \fI\%sending\fP of the preferred origin of an
internal event.
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image]
Figure 2: Simplified work flow of scanloc..UNINDENT
.UNINDENT
.SS Pick and origin buffering
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
scanloc processes picks with unique public IDs. However, the accuracy of
public IDs currently generated by \fIscautopick\fP [\fI\%15\fP] is limited to
10 ms by default. In systems with very frequent picks and in
\fI\%pipeline systems\fP
this limitation may result in clashes. Therefore, we recommend to let
scautopick use the same high\-resolution public ID scheme as all
other modules by configuring the ID pattern explicitly in global module
configuration (\fBglobal.cfg\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
publicIDPattern = @classname@/@time/%Y%m%d%H%M%S.%f@.@id@
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A solution for scautopick will be provided with \fISeisComP\fP in a future release
with version > 6.7.2.
.UNINDENT
.UNINDENT
.sp
The entry point of \fIscanloc\fP is the addObject method which handles incoming
objects from the messaging system. By default it is subscribed to the messaging
group \fBPICK\fP and \fBLOCATION\fP\&. Depending on which object type (pick or origin)
is incoming different working steps are proceeded.
.INDENT 0.0
.IP \(bu 2
In case a \fBpick\fP arrives, \fIscanloc\fP
.INDENT 2.0
.IP 1. 3
tests the pick:
.INDENT 2.0
.IP \(bu 2
evaluation status: Rejected picks are ignored unless the
command\-line option \fI\%\-\-allow\-rejected\-picks\fP is given.
.IP \(bu 2
tests the author information against \fI\%buffer.authorWhiteList\fP\&.
When the parameter is configured, the pick is ignored if its authors does
not match \fI\%buffer.authorWhiteList\fP\&.
.UNINDENT
.IP 2. 3
adds the pick after passing the tests to the pick buffer keeping it
for the time given by
\fI\%buffer.pickKeep\fP or \fI\%\-\-pick\-keep\fP,
.IP 3. 3
tries to use the pick for \fI\%clustering\fP,
.IP 4. 3
checks if the pick can be \fI\%associate to origins\fP in
the origin buffer exceeding a configurable \fI\%minScore\fP\&.
In case the pick can be associated, the scores for all new origins are
calculated and the origin with the highest score is selected.
.UNINDENT
.IP \(bu 2
In case an \fBorigin\fP arrives, \fIscanloc\fP
.INDENT 2.0
.IP 1. 3
tests the origin:
.INDENT 2.0
.IP \(bu 2
tests the evaluation mode. Manual origins are ignored unless
\fI\%buffer.ignoreManualOrigins\fP = \fIfalse\fP,
.IP \(bu 2
tests the author information against \fI\%buffer.authorWhiteList\fP
and \fI\%buffer.originAuthorWhiteList\fP\&. When the parameters are
configured, the origin is ignored if its authors does not match the
configured values.
.UNINDENT
.IP 2. 3
adds the origin after passing the tests to the origin buffer keeping it the time given by
\fI\%buffer.originKeep\fP or \fI\%\-\-origin\-keep\fP seconds,
.IP 3. 3
tries to \fI\%associate additional picks\fP to the origin.
.UNINDENT
.UNINDENT
.sp
Adjust the \fBbuffer.*\fP parameters according to the times these objects
are required for processing.
.sp
\fBHINT:\fP
.INDENT 0.0
.INDENT 3.5
You may use \fI\%playback_picks\fP for printing
information on picks and amplitudes contained in XML files used, e.g., for
tuning or playbacks:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
playback_picks \-\-print picks.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Clustering
.sp
In case the pick cannot be associated, the cluster search is started. The
cluster search is based on the algorithm \fIDBSCAN\fP [\fI\%2\fP] which
takes the required number of neighbours (\fI\%clusterSearch.minSize\fP)
and \fI\%clusterSearch.maxSearchDist\fP as configuration parameters.
.sp
The algorithm forms clusters of picks by searching for neighboring stations
that have picks. \fI\%Internal origins\fP are formed from clusters.
The number of origins from cluster search is limited by the configuration parameter
\fI\%clusterSearch.maxOrigins\fP\&.
.sp
The cluster search considers picks from stations by distance with:
.sp
.ce
distance \ele maxSearchDist
.ce 0
.sp
where maxSearchDist is configurable by \fI\%clusterSearch.maxSearchDist\fP\&.
distance is the vector sum of the time difference \eDelta t
between the picks in units of seconds and of a potential travel time
tt between the stations in units of seconds:
.sp
.ce
distance = \esqrt{\eDelta t^2 + tt^2}
.ce 0
.sp
and
.sp
.ce
tt = \eDelta x / v
.ce 0
.sp
where \eDelta x is the horizontal distance between the sensor locations
of stations in units of km and v is the
\fI\%clusterSearch.averageVelocity\fP in units of km/s. Activate
\fI\%use3D\fP for considering 3D distances between sensor
locations. Therefore, distance and
\fI\%clusterSearch.maxSearchDist\fP take units of seconds.
.sp
As the cluster search is done over time and location, the additional configurable
velocity parameter, \fI\%clusterSearch.averageVelocity\fP, is required to transform
the input parameters of the cluster search in the same dimension (time).
The velocity is a weighting factor between inter\-station distances and
travel\-time differences. A starting value should represent the average apparent
horizontal or the total medium P\-wave velocity of the crust.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
When the number of buffered cluster origins reaches \fI\%clusterSearch.maxOrigins\fP,
no more new origins can be formed and warnings are issued. Adjust accordingly:
.INDENT 0.0
.IP \(bu 2
\fI\%buffer.originKeep\fP,
.IP \(bu 2
\fI\%buffer.pickKeep\fP,
.IP \(bu 2
\fI\%clusterSearch.maxOrigins\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Limiting in time
.sp
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 \fBcluster reference time\fP\&. The time window is defined by
\fI\%clusterSearch.maxPickDelay\fP but the \fBcluster reference time\fP is defined
either by the
.INDENT 0.0
.IP \(bu 2
Pick time of the latest pick of the received picks when
\fI\%clusterSearch.referenceTimeMode\fP = \(aqLastPick\(aq (default),
.IP \(bu 2
Pick time of the latest received pick which defines are group of \fIN\fP
picks within \fI\%clusterSearch.maxPickDelay\fP when
\fI\%clusterSearch.referenceTimeMode\fP = \(aqMaxPickDelay\(aq. Here, \fIN\fP is the
maximum of \fI\%clusterSearch.minSize\fP
and \fI\%association.minPhase\fP\&. \fBThis mode is relevant if only very few
stations with significantly different data delay provide the picks.\fP
Otherwise picks may not be available for clustering at the same time
preventing to form clusters and new origins.
.UNINDENT
.sp
Thus, when setting \fI\%clusterSearch.referenceTimeMode\fP = \(aqMaxPickDelay\(aq
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.
.sp
.ce
pick delay = creationTime \- pickTime
.ce 0
.sp
where
.INDENT 0.0
.IP \(bu 2
pick.creationTime:time at which the pick was made,
.IP \(bu 2
pickTime: actual time of the phase arrival.
.UNINDENT
.sp
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 \fBblue trapezoid\fP (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
(\fBgreen trapezoid\fP). Subsequently, the trapezoid is extended until the
cluster reference time is updated.
This may be the next pick with a larger pick time
(\fBolive trapezoid\fP, \fI\%clusterSearch.referenceTimeMode\fP = \(aqLastPick\(aq) or
the time of the pick which is preceded by at least \fI\%clusterSearch.minSize\fP
picks within \fI\%clusterSearch.maxPickDelay\fP (\fByellow trapezoid\fP,
\fI\%clusterSearch.referenceTimeMode\fP = \(aqMinPickDelay\(aq).
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.
.sp
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):
.INDENT 0.0
.IP \(bu 2
CRT2 with \fI\%clusterSearch.referenceTimeMode\fP = \(aqLastPick\(aq or
.IP \(bu 2
Deleyed CRT2 since \fI\%clusterSearch.referenceTimeMode\fP = \(aqMaxPickDelay\(aq.
.UNINDENT
.sp
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.
.INDENT 0.0
.INDENT 2.5
[image]
Figure 3: Schematic view of pick time vs. pick delay time 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
\fI\%clusterSearch.referenceTimeMode\fP = \(aqMaxPickDelay\(aq..UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image]
Figure 4: clusterSearch.maxPickDelay = 10 s..UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image]
Figure 5: clusterSearch.maxPickDelay = 20 s.
Real\-life examples of picks considered for clustering with different values
for \fI\%clusterSearch.maxPickDelay\fP and
\fI\%clusterSearch.referenceTimeMode\fP = \(aqMaxPickDelay\(aq. P picks with
green symbols are considered for clustering, picks with red symbols are not.
Clearly, the larger \fI\%clusterSearch.maxPickDelay\fP the more picks are
available for clustering but the more clusters from unrelated picks (false
clusters) may be created..UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
For small and similar delays of all P picks, \fI\%clusterSearch.maxPickDelay\fP
can be directly read from travel\-time curves. A small margin should be added
account for differences in delay.
.IP \(bu 2
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 \fI\%Real\-Time Applications\fP for more details
and the consequences.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If picks arrive with a larger delay than others, there is a risk that they cannot
be considered anymore for the cluster. When only few picks are available the events
may then be missed. To overcome the issue, you may increase \fI\%clusterSearch.maxPickDelay\fP
or set the parameter \fI\%clusterSearch.referenceTimeMode\fP = \(dqMaxPickDelay\(dq.
While increasing \fI\%clusterSearch.maxPickDelay\fP may slow down the clustering
and increase the risk to cluster unrelated picks,
\fI\%clusterSearch.referenceTimeMode\fP = \(dqMaxPickDelay\(dq will only increase the
cluster reference time if at least \fI\%clusterSearch.minSize\fP P picks are
available in the considered time window. Run \fBscanloc\fP on the command line
with the \fI\%\-\-cluster\-search\-log\-file\fP to learn about cluster reference
times and the considered picks. A suggestion for \fI\%clusterSearch.maxPickDelay\fP
is provided in the summary section at the end of the resulting output. For more
options read the section \fI\%Tuning and optimization\fP\&.
.sp
Within one cluster, the difference in the pick times between the
cluster reference time and any other pick must thus not exceed \fI\%clusterSearch.maxPickDelay\fP\&.
Otherwise the pick is rejected from clustering. The parameter \fI\%clusterSearch.maxPickDelay\fP
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.
.sp
The DBSCAN algorithm can deliver multiple pick clusters. The cluster search can
be disabled using \fI\%clusterSearch.maxPickDelay\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Maximum allowed difference between P pick and cluster reference time(latest pick time).
# The cluster search ignores all picks which exceed the value. Using \(dq\-1\(dq enables all picks
# regardless of the delay. Unit: seconds.

clusterSearch.maxPickDelay = 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, only \fI\%external origin\fP can be considered for
\fI\%phase association\fP\&.
.sp
In combination with \fI\%buffer.futureTimeDelta\fP or
\fI\%\-\-future\-time\-delta\fP
applying \fI\%clusterSearch.referenceTimeMode\fP = \(dqMaxPickDelay\(dq may make
updating the cluster reference time more robust to singular data timing issues.
However, the timing issue of the waveforms and the pick times remain and may
impact the clustering itself. Therefore, \fI\%buffer.futureTimeDelta\fP
should only be configured with positive values only in extraordinary
circumstances.
.SS Limiting in space
.sp
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 \fI\%clusterSearch.regionFilter\fP\&. 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
\fI\%phase association\fP\&.
.sp
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.
.SS Cluster splitting
.sp
Originally, clusters may contain multiple phase picks from the same sensor but
only one pick per sensor shall be accepted. Therefore, the clusters with picks
from the same sensor are split into separate clusters with only one pick per
sensor.
.sp
Typcially, the sensors are discriminated by their sensor location codes, LOC, as
defined in the SEED manual [\fI\%29\fP] using the NET.STA.LOC.CHA stream
representation. Since some stations provide data for different sensors on the
same sensor location code but with different channel codes (e.g. seismic and
infrasound sensors), the channel code, CHA, may be a better discrimination
measure for sensor identity. On the other hand, picks made on different sensor
location of the same station could be attributed to the same site, e.g., in
regional or telseismic monitoring. Then, the station code, STA, would be
preferred for discrimination. The parameter
\fBclusterSearch.streamCheckLevel\fP allows defining the stream level on
which to check sensor identity.
.sp
\fBHINT:\fP
.INDENT 0.0
.INDENT 3.5
In order to consider picks from equal sensor location codes but with
different channel IDs, configure scanloc with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
clusterSearch.streamCheckLevel = cha
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
All new clusters are considered new origins. By activating
\fI\%clusterSearch.checkOrigins\fP, all new clusters are checked again.
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
\fI\%phase association\fP and scanloc in general.
.SS Tuning and optimization
.sp
Use the option \fI\%\-\-cluster\-search\-log\-file\fP to store detailed information
on the clustering process in a file, e.g., \fIcluster.log\fP\&. The given values can be
used to optimize the cluster search parameters.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
scanloc \-\-ep picks.xml \-d [database] \-\-cluster\-search\-log\-file cluster.log > origins.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For optimizing the configuration of the parameter \fI\%clusterSearch.maxPickDelay\fP
use the default value first:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
clusterSearch.maxPickDelay = \-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+ 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The summary value can be used as a lower proxy to set
\fI\%clusterSearch.maxPickDelay\fP\&.
.SS Locating
.sp
Clusters are located by the configured \fI\%locator\fP\&. If the
location fails, the origin is ignored unless \fI\%clusterSearch.preliminary\fP
is active. Then, preliminary values are chosen:
.INDENT 0.0
.IP \(bu 2
Origin location is the center of the detecting stations,
.IP \(bu 2
Origin time is the time of the first phase pick,
.IP \(bu 2
Status is set to \fIpreliminary\fP\&.
.UNINDENT
.sp
The status will be unset if more phases can be associated and the new origin can
be located.
.SS Phase Association
.sp
When a cluster of P picks meeting \fI\%association.minPhase\fP is found
or an \fI\%external origin\fP arrives, \fBscanloc\fP tries
to associates additional P\- and S\-type phase picks which are
\fI\%buffered\fP and which meet the association criteria:
.INDENT 0.0
.IP \(bu 2
\fBP\-type picks:\fP
.INDENT 2.0
.IP \(bu 2
the epicentral distance does not exceed \fI\%association.maxDist\fP,
.IP \(bu 2
no other P pick from the same channel exists in the origin,
.IP \(bu 2
the pick time, t_p, of the new pick is close to the arrival time
predicted by the travel\-time interface, t_p^{pred}, considering
\fI\%association.maxPResidual\fP:
.sp
.ce
t_p^{pred} \- association.maxPResidual \ele t_p \ele t_p^{pred} + association.maxPResidual
.ce 0
.UNINDENT
.IP \(bu 2
\fBS\-type picks:\fP
.INDENT 2.0
.IP \(bu 2
the epicentral distance does not exceed \fI\%association.maxDist\fP,
.IP \(bu 2
the evaluation mode of the pick is manual \fBor\fP 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:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
<pick>
    ...
    <comment>
        <text>Pick/20230726100411.964268.1316601</text>
        <id>RefPickID</id>
    </comment>
</pick>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The reference check serves as a quality control feature. I can be dropped by
\fI\%\-\-drop\-reference\-check\fP and
\fI\%association.dropReferenceCheck\fP\&.
.IP \(bu 2
the pick time, t_s, of the new pick is close to the arrival time
predicted by the travel\-time interface, t_s^{pred}, considering
\fI\%association.maxSResidual\fP:
.sp
.ce
t_s^{pred} \- association.maxSResidual \ele t_s \ele t_s^{pred} + association.maxSResidual
.ce 0
.UNINDENT
.UNINDENT
.sp
The new set of picks are used for \fI\%relocating\fP\&.
.sp
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 \fI\%association.maxResidual\fP are rejected.
After the P\-picks are associated and relocated, \fIscanloc\fP 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 \fI\%maxRMS\fP,
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
\fI\%sent out\fP\&.
.sp
In addition to origins from the cluster search, \fIscanloc\fP can also treat external
origins that are created by other associators, e.g., \fIscautoloc\fP [\fI\%14\fP]\&.
In case an such origin is received \fIscanloc\fP 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 \fI\%Simplified work flow of scanloc.\fP for an overview.
.sp
The maximum epicentral distance up to which picks are considered is configured
by \fI\%association.maxDist\fP\&. However, this parameter can be overruled per
network and station by providing a station table in a file given by
\fI\%association.stationConfig\fP\&. As in \fIscautoloc\fP [\fI\%14\fP] 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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
* * 1 180
GR * 1 60
GR GRA1 1 20
Z3 * 0 180
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For associating the picks, travel times from look\-up tables are used. The
\fI\%association.tableType\fP and the \fI\%association.table\fP can be
configured to provide specific tables which may be more appropriate for specific
regions. Currently, only a limited number of travel\-time table types
(\fI\%association.tableType\fP) are supported. scanloc provides
\fI\%densely\-sampled travel\-time tables\fP for LOCSAT.
.TS
center;
|l|l|.
_
T{
types supported by association.tableType
T}	T{
location of tables for association.table
T}
_
T{
homogeneous
T}	T{
model is defined by \fBttt.homogeneous.$name.*\fP in global module configuration
T}
_
T{
libtau
T}	T{
@DATADIR@/ttt
T}
_
T{
LOCSAT
T}	T{
@DATADIR@/locsat/tables, tables should not be modified
T}
_
.TE
.sp
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.
.sp
Example configuration (\fBscanloc.cfg\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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 \fI\%association.maxPResidual\fP
and \fI\%association.maxSResidual\fP\&.
.UNINDENT
.UNINDENT
.SS Processing external origins
.sp
Origins received from other modules through the messaging or provided by XML files
can be processed and \fI\%more phases can be associated\fP\&. In
order to ignore such external origins set \fI\%buffer.ignoreOrigins\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
buffer.ignoreOrigins = true
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Processing of external origins may be undesired when
.INDENT 0.0
.IP \(bu 2
Involving other modules excepting origins by the messaging system, e.g.,
\fIscreloc\fP [\fI\%25\fP]\&. These modules may run in a loop with scanloc.
.IP \(bu 2
Receiving origins from other systems.
.UNINDENT
.sp
Configure \fI\%buffer.authorWhiteList\fP with the author names of
origins \fBwhich shall be processed\fP, e.g., \fIscautoloc\fP [\fI\%14\fP]:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
buffer.authorWhiteList = scautoloc@localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Automatic and manual origins from all other authors will be ignored.
.SS Status of origins
.sp
The status of origins can be set during pick processing
.INDENT 0.0
.IP \(bu 2
Normally, the status of origins is \fBunset\fP\&.
.IP \(bu 2
The status of origins from cluster search which only be located with fixed
depth (\fBfixDepth\fP, \fBforceFixDepth\fP) is set to
\fBpreliminary\fP\&.
.IP \(bu 2
The status of origins which can be relocated with a free\-depth solution is set
to \fBunset\fP if the origin status of the origin was previously set.
.UNINDENT
.sp
However, the evaluation status may be later changed at
different times by different modules, e.g., the gempa module \fBsceval\fP\&.
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
\fBscolv\fP\&.
.SS Sending of origins
.sp
Before sending a new \fI\%internal origin\fP to the
messaging or to XML output (\fI\%\-\-ep\fP) it is tested against the
configuration:
.INDENT 0.0
.IP \(bu 2
Picks are removed when their travel\-time residual > \fI\%association.maxResidual\fP
and origins are \fI\%relocated\fP,
.IP \(bu 2
Origins are skipped when the score < \fI\%minScore\fP,
.IP \(bu 2
Origins are skipped when the depth > \fI\%ignoreDepth\fP\&.
.UNINDENT
.sp
The remaining internal origins are evaluated based on \fI\%scoring\fP\&.
The best origin of the same \fI\%internal event\fP is the one
which has the highest score. When meeting the parameters
\fI\%ignoreDepth\fP, \fI\%maxRMS\fP and \fI\%minScore\fP it is sent to the
SeisComP \fImessaging\fP [\fI\%10\fP] or to stdout in case of non\-real\-time playbacks
(\fI\%\-\-ep\fP).
.sp
In real\-time operation, the sending of origins may be delayed allowing to find
new origins with higher score.
The delay reduces the amount of origins in SeisComP systems and the load of
other modules. The send interval is controlled by the \fBpublication\fP
configuration parameters.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In non\-real\-time (\fI\%\-\-ep\fP) playbacks, the \fBpublication\fP
configuration parameters are ignored and all origins are sent without delay.
.UNINDENT
.UNINDENT
.SS Performance considerations
.sp
In case of dense large\-N networks and high seismicity situations,
very many phase picks, e.g., hundreds of picks for a single event may be
provided to and processed by scanloc. In such situations, scanloc was observed
to slow down with default parameters but a sensible configuration of
\fI\%clusterSearch.maxSize\fP and \fI\%association.arrivalCountMinRes\fP
could overcome the obstacles.
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fIclusterSearch.maxSize\fP controls the maximum number of picks in a cluster
after selecting core points and before adding more picks. Since core points
are first collected, clusters may have a higher number of picks. The goal of
this parameter is to speed up scanloc. The parameter may help to increase the
performance of scanloc in case of dense large\-N networks where very many
cluster can be formed due to the proximity of stations or generous
configuration.
.UNINDENT
.IP \(bu 2
\fIassociation.arrivalCountMinRes\fP controls the association of picks to origins.
For origins with a larger number of arrivals than configured, the association
of P and S picks is controlled by the minimum of (\fIassociation.maxPResidual\fP,
\fIassociation.maxResidual\fP) and (\fIassociation.maxSResidual\fP,
\fIassociation.maxResidual\fP), respectively. The goal of this parameter is to
speed up scanloc by only associating picks to already stable origins defined
by many arrivals where new picks later on are unlikely to be removed again
from origins by residual checks. The parameter may help to increase the
performance of scanloc in case of dense large\-N networks where very stations
provide phase picks.
.UNINDENT
.SH INTERNAL ORIGINS AND EVENTS
.sp
\fIscanloc\fP forms
.INDENT 0.0
.IP \(bu 2
\fBInternal origins\fP from the locations and the associated picks (arrivals) of
new arrival sets,
.IP \(bu 2
\fBInternal events\fP from internal origins based on the
\fBeventAssociation.*\fP parameters. The procedure is similar to
\fIscevent\fP [\fI\%19\fP]\&. 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:
.INDENT 2.0
.IP \(bu 2
the origins share a minimum of
\fI\%eventAssociation.minMatchingArrivals\fP \fI\%arrivals\fP\&.
Arrivals must be identical by the ID of the referenced \fI\%pick\fP unless
\fI\%eventAssociation.compareAllArrivalTimes\fP = \fItrue\fP\&. Then, a margin
of \fI\%eventAssociation.maxMatchingArrivalTimeDiff\fP applies for
considering different picks to be the same.
.IP \(bu 2
the differences in origin time \fBAND\fP \fI\%epicenter\fP is within
\fI\%eventAssociation.maxTimeSpan\fP \fBAND\fP
\fI\%eventAssociation.maxDist\fP, respectively.
.UNINDENT
.sp
Only if the \fI\%score\fP of a new origin exceeds the score
of the last sent origin of the same internal event, the new origin is
\fI\%sent out\fP\&.
.UNINDENT
.SH LOCATING ORIGINS
.sp
scanloc locates internal origins based on the configuration by the
\fI\%locator.type\fP and \fI\%locator.profile\fP parameters. The list of
available locators can be printed by \fIscanloc\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
scanloc \-\-locator\-list
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In order to make an alternative locator available to \fIscanloc\fP, the respective
plugin must be loaded.
.sp
Consider a fast locator (\fI\%locator.type\fP), e.g., LOCSAT or
\fIHypo71\fP [\fI\%3\fP] with an appropriate profile (\fI\%locator.profile\fP).
For LOCSAT dense the provided \fI\%dense travel\-time tables\fP may
be more appropriate at short epicentral distance than the default one.
.sp
Example configuration (\fBscanloc.cfg\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# The locator type to use
locator.type = LOCSAT

# The locator profile to use
locator.profile = iasp91_scanloc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Computational speed can be an issue when alternative locators are used
and when many picks are to be tested during association. In this case \fIscanloc\fP
can be configured with \fILOCSAT\fP [\fI\%5\fP] but \fIscreloc\fP [\fI\%25\fP] may be used
along with the preferred locator and profile to relocate the origin. The
locator NonLinLoc [\fI\%34\fP] is certainly too slow for being used in
\fBscanloc\fP but is a good option for \fBscreloc\fP\&.
.UNINDENT
.UNINDENT
.sp
If the locator fails to locate and \fI\%locator.fixDepth\fP is active, the
hypocenter depth is fixed to \fI\%defaultDepth\fP and the origin is relocated.
.SH SCORING ORIGINS
.sp
Each \fI\%internal origin\fP is evaluated and ranked by
calculating a score in order for scanloc to define the preferred origin
of an internal event and for comparison against \fI\%minScore\fP before
eventually \fI\%sending an origin\fP\&.
.sp
The score is calculated by a score processor which
is provided by a plugin. Score plugins shipped with scanloc can be equally
applied to \fBscanloc\fP and \fIscevent\fP [\fI\%19\fP]\&. The plugins currently
provided along with \fBscanloc\fP are:
.INDENT 0.0
.IP \(bu 2
\fIscoresum\fP (default): \fI\%OriginSum\fP calculating
the score as a weighted sum of \fI\%Origin\fP attributes.
.IP \(bu 2
\fIscoremf\fP: \fI\%OriginMultiFeature\fP calculating
the score as a weighted sum of \fI\%Origin\fP attributes like in
\fI\%OriginSum\fP but allowing to add additional
contributions by picks from infrasound, strong motion and low\-gain
instruments, authors, gap, etc.
.UNINDENT
.sp
but more processors can be implemented by \fIgempa\fP or anyone else. Read the
section \fI\%Plugin development\fP for the details.
.SS OriginSum
.sp
The OriginSum score processor is provided by the plugin \fIscoresum\fP located in
\fB@DATADIR@/plugins/scevent/scoresum.so\fP\&. The plugin calculates the
score for origins as a weighted sum from
.INDENT 0.0
.IP \(bu 2
The number of associated and used P\- (Is\-) and S\-phase picks considering
separately the number of used pick times, slowness and backazimuth
(\fIpTimeCount\fP, \fIpSloCount\fP, \fIpBazCount\fP and \fIsTimeCount\fP, \fIsSloCount\fP, \fIsBazCount\fP),
.IP \(bu 2
The number of loosely associated P and S picks  (\fIp0Count\fP and \fIs0Count\fP).
Such picks are arrivals with 0 weight. They are not used at all for origin
location,
.IP \(bu 2
Source \fIdepth\fP represented by \fIdepthFactor\fP (see below) and
.IP \(bu 2
\fIRMS\fP time residual represented by \fIresidualFactor\fP (see below).
.UNINDENT
.SS Methodology
.sp
The score is computed as
.sp
.ce
score =\e &score.sum.p[0] \etimes pTimeCount + score.sum.p[1] \etimes pSloCount + score.sum.p[2] \etimes pBazCount \e\e
      +\e &score.sum.p0 \etimes p0Count \e\e
      +\e &score.sum.s[0] \etimes sTimeCount + score.sum.s[1] \etimes sSloCount + score.sum.s[2] \etimes sBazCount \e\e
      +\e &score.sum.s0 \etimes s0Count \e\e
      +\e &score.sum.depth \etimes depthFactor \e\e
      +\e &score.sum.residual \etimes residualFactor
.ce 0
.sp
with
.sp
.ce
residualFactor =\e \eleft(\efrac{score.sum.normalizationRMS}{RMS + score.sum.normalizationRMS}\eright)^4 \e\e
depthFactor =\e \eleft(\efrac{score.sum.normalizationDepth}{depth + score.sum.normalizationDepth}\eright)^4.
.ce 0
.sp
where the weight factors \fI\%score.sum.p\fP [0:2], \fI\%score.sum.p0\fP ,
\fI\%score.sum.s\fP [0:2], \fI\%score.sum.s0\fP ,
\fI\%score.sum.depth\fP and \fI\%score.sum.residual\fP can be configured.
The values for \fIdepthFactor\fP and \fIresidualFactor\fP are derived from origin
\fIdepth\fP and \fItime residual\fP and the configured values for
\fI\%score.sum.normalizationDepth\fP and \fI\%score.sum.normalizationRMS\fP\&.
Higher weight is given to origins with shallower depth. You may set
\fI\%score.sum.depth\fP to form the score independent of depth in regions with
shallow and deep seismicity:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
score.sum.depth = 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Phase picks may not only provide measurements of time but also of slowness
and back azimuth. The existence of these additional values, if used by the
locator, may impact the solution quality which can be considered by the score.
If you believe that slowness and back azimuth may provide valuable information,
the contribution to score by these picks may be increased by configuring
\fI\%score.sum.p\fP and \fI\%score.sum.s\fP with additional weights for slowness
and backazimuth like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
score.sum.p = 1,0.5,0.5
score.sum.s = 1,0.5,0.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Read the documentation of the locators in \fISeisComP\fP in order to understand if
slowness and back azimuth are considered. An overview over locators is given in
the concepts section of the \fISeisComP documentation\fP [\fI\%6\fP]\&.
.SS Configuration
.sp
For utilizing the \fIscorsum\fP plugin with the OriginSum score processor in scanloc
configure scanloc as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},scoresum
score = OriginSum
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For utilizing the \fIscoresum\fP plugin with the OriginSum score processor
in scevent configure scevent as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},scoresum
eventAssociation.score = OriginSum
eventAssociation.properties = ...,SCORE,...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OriginMultiFeature
.sp
The OriginMultiFeature score processor is provided by the plugin \fIscoremf\fP
located in \fB@DATADIR@/plugins/scevent/scoremf.so\fP\&. The plugin calculates
the score for origins similar to
\fI\%OriginSum\fP but allowing to add additional
contributions by picks from infrasound, strong motion and low\-gain instruments,
authors, azimuthal gap, etc.
.SS Methodology
.sp
The score is computed as
.sp
.ce
score =\e &score.mf.weights.p[0] \etimes pTimeCount + score.mf.weights.p[1] \etimes pSloCount + score.mf.weights.p[2] \etimes pBazCount \e\e
      +\e &score.mf.weights.p0 \etimes p0Count \e\e
      +\e &score.mf.weights.s \etimes sTimeCount \e\e
      +\e &score.mf.weights.s0 \etimes s0Count \e\e
      +\e &score.mf.weights.strongMotion \etimes strongMotionCount \e\e
      +\e &score.mf.weights.infrasound \etimes infrasoundCount \e\e
      +\e &score.mf.weights.depth \etimes depthFactor \e\e
      +\e &score.mf.weights.residual \etimes residualFactor \e\e
      +\e &score.mf.weights.gaps \etimes gapFactor \e\e
      +\e &authorfactor
.ce 0
.sp
with
.sp
.ce
depthFactor =\e \eleft(\efrac{score.mf.weights.normalizationDepth}{depth + score.mf.weights.normalizationDepth}\eright) \e\e
residualFactor =\e \eleft(\efrac{score.mf.weights.normalizationRMS}{RMS + score.mf.weights.normalizationRMS}\eright) \e\e
gapsFactor =\e 1.0 \- score.mf.weights.gap * \eleft(\efrac{azimuthal gap}{360.0}\eright)
.ce 0
.sp
.ce
authorfactor =\e
\ebegin{cases}
0 & \etext{if author of pick is not found in score.mf.weights.authors.author} \e\e
score.mf.weights.authors.score & \etext{if author of pick is found as score.mf.weights.authors.author}
\eend{cases}
.ce 0
.sp
However, when origin time residual or depth exceed
\fI\%score.mf.weights.normalizationRMS\fP and
\fI\%score.mf.weights.normalizationDepth\fP, respectively, then
.sp
.ce
score = score.mf.defaultScore
.ce 0
.sp
which typically assigns a very low priority to an origin.
.sp
Phase picks may not only provide measurements of time but also of slowness
and back azimuth. The existence of these additional values, if used by the
locator, may impact the solution quality which can be considered by the score.
If you believe that slowness and back azimuth may provide valuable information,
the contribution to score by these picks may be increased by configuring
\fI\%score.sum.p\fP with weights for slowness and backazimuth like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
score.mf.weights.p = 1,0.5,0.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
All elements in the equations above starting with \fIscore.mf.\fP are
configurable parameters. Read the section \fI\%ScoreMF plugin\fP for the full
description of parameters.
.UNINDENT
.UNINDENT
.SS Configuration
.sp
For utilizing the \fIscoremf\fP plugin with the OriginMultiFeature score processor
in scanloc configure scanloc as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},scoremf
score = OriginMultiFeature
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For utilizing the \fIscoremf\fP plugin with the OriginMultiFeature score processor
in scevent configure scevent as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},scoremf
eventAssociation.score = OriginMultiFeature
eventAssociation.properties = ...,SCORE,...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Plugin development
.sp
Custom score processors may be implemented by additional plugins. You may
develop such plugins yourself or request a development from
\fI\%gempa GmbH\fP\&. An
introduction into the development is given on:
\fI\%GitHub\fP .
.sp
For utilizing the \fIpluginName\fP plugin with the \fIprocessorName\fP processor in
scanloc configure scanloc as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},scoresum
score = OriginSum
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For utilizing the \fIpluginName\fP plugin with the processorName processor in scevent
configure scevent as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plugins = ${plugins},pluginName
eventAssociation.score = processorName
eventAssociation.properties = ...,SCORE,...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH PIPELINE SYSTEMS
.sp
When operating scanloc in a pipeline, configure \fI\%connection.subscriptions\fP
to receive picks and origins from and \fI\%connection.primaryGroup\fP to send
origins to the right message group.
.sp
Alternatively you may configure \fI\%buffer.authorWhiteList\fP for receiving
picks and origins from modules with the listed authors. In this case, configuring
new message groups for receiving and sending objects may not be required depending
on the other modules involved in the pipeline.
.sp
Please also understand the note on public IDs of the
\fI\%buffer section\fP\&.
.SH REDUNDANT SYSTEMS
.sp
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 \fI\%Processing external origins\fP for the configuration.
.SH ASSOCIATION OF TELESEISMIC PHASES
.sp
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.
\fIscanloc\fP can be used to suppress this type of fake events.
.sp
In a 2\-pipeline setup, \fIscanloc\fP can associate such teleseismic phases recorded
by the local network with origins that were found by the pipeline for
monitoring teleseismic earthquakes. Then \fIscevent\fP [\fI\%19\fP]
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 \fI\%scanloc\fP feature requires an extended license.
.sp
\fISetup of a 2\-pipeline system\fP
.INDENT 0.0
.IP 1. 3
Generate a 2\-pipeline system involving at least \fIscautopick\fP [\fI\%15\fP],
\fBscanloc\fP and \fIscevent\fP [\fI\%19\fP] :
.INDENT 3.0
.IP \(bu 2
\fBPipeline 1\fP monitors teleseismic earthquakes using \fBscautopick\fP,
\fBscautoloc\fP, \fBscanloc\fP and default message groups.
.IP \(bu 2
\fBPipeline 2\fP monitors local earthquakes using \fIl1autopick\fP, \fIl1autoloc\fP
and \fIl1scanloc\fP using the message groups L1PICK and L1LOCATION.
.UNINDENT
.IP 2. 3
Let \fIscanloc\fP not perform cluster search (\fI\%clusterSearch.maxOrigins\fP = 0)
but allow \fIscanloc\fP to only associate P picks from pipelines 2 based on origins
from \fBscautoloc\fP (connection.subscriptions = \(dqLOCATION, L1PICK\(dq in the global
module parameters). Configure \fIscanloc\fP 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.
.sp
In order to facilitate association of teleseismic picks, the picks and the origins
must be kept in memory for sufficient time. Increase \fI\%buffer.pickKeep\fP
and \fI\%buffer.originKeep\fP accordingly, e.g., to 1800 s.
.sp
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 \fIscevent\fP\&.
.IP 3. 3
Configure \fIscevent\fP to listen to the message groups from both pipelines (e.g.
LOCATION and L1LOCATION) and activate the \fIscevent\fP module parameter
\fIeventAssociation.allowLooseAssociatedArrivals\fP (\fBscevent.cfg\fP).
.INDENT 3.0
.INDENT 2.5
[image]
Figure 6: 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..UNINDENT
.UNINDENT
.UNINDENT
.sp
\fIPlayback using picks and amplitudes from 2\-pipeline system (real\-event examples)\fP
.INDENT 0.0
.INDENT 2.5
[image]
Figure 7: Location tab in \fIscolv\fP with zero\-weight picks associated by \fIscanloc\fP as PKP phases..UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image]
Figure 8: Event tab in \fIscolv\fP showing the origins from the pipelines for local and
teleseismic 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..UNINDENT
.UNINDENT
.SH REAL-TIME APPLICATIONS
.INDENT 0.0
.IP \(bu 2
Run \fIscanloc\fP during real\-time processing:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
seiscomp start scanloc
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Run \fIscanloc\fP  on the command line for real\-time processing or message\-based
playbacks with debugging output:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
scanloc \-\-debug
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SH PLAYBACKS
.sp
Playbacks are used to process waveforms or other data on demand as in real time
or non\-real time, with or without connection to the \fISeisComP\fP messaging. Objects
like picks and origins may be provided to scanloc by XML files or through the
messaging.
.sp
In playbacks of picks in XML files the performance of scanloc may differ
from real\-time operation based on messaging:
.INDENT 0.0
.IP \(bu 2
In real\-time operation, the picks are made e.g., by \fBscautopick\fP at
some time and considered by scanloc according to
their creation times. Delayed picks may become irrelevant for the processing.
Configure \fI\%buffer.pickKeep\fP and \fI\%buffer.originKeep\fP accordingly.
.sp
However, the \fBcreation times of picks and origins may be obscured\fP when
created in a non\-real\-time playback or manually. Objects from non\-real\-time
playbacks may have almost identical creation times independent of their object
times (pick time, origin time, etc.).
.IP \(bu 2
\fI\%In message\-based playbacks\fP, picks and
origins are provided to scanloc via the messaging system. When created in real
time, the \fBcreation times\fP of these objects form a
realistic time reference for scanloc and should therefore considered using
\fI\%\-\-timing\fP\&.
.IP \(bu 2
\fI\%In non\-real\-time XML playbacks\fP
(\fI\%\-\-ep\fP), scanloc considers picks and origins by default according to
their actual \fBtimes\fP\&.
For objects created in a non\-real\-time playback object times are most
reasonable as creation time is not a valid time reference anymore.
\fBHowever, referencing to object time may result in a behavior which is
different from real\-time conditions.\fP
.sp
Therefore, for mimicking real\-time conditions in playbacks of objects obtained
in real\-time conditions consider the command\-line option
\fI\%\-\-timing\fP with \fIcreationTime\fP\&.
.UNINDENT
.SS Real\-time playbacks
.sp
Message\-based real\-time playbacks are useful to test the behavior of scanloc in
real time based on objects like Picks, Origins and/or
Amplitudes generated before by picking/processing:
.INDENT 0.0
.IP \(bu 2
\fBReal time\fP where the order of the objects is represented by their
creation time.
.IP \(bu 2
\fBNon\-real time\fP, e.g. manually or by playbacks at high speed. In these cases
creation time is not a useful measure of the timing in real time.
.UNINDENT
.sp
Real\-time playbacks are supported by
\fI\%auxiliary scripts\fP shipped with the scanloc
package.
.INDENT 0.0
.IP \(bu 2
\fBObjects from real\-time picking/processing:\fP Obtain phase picks and origins
obtained in real\-time and play them back using \fBdump_picks\fP\&.
Amplitudes are useful if other modules such as \fIscautoloc\fP [\fI\%14\fP],
\fIscamp\fP [\fI\%12\fP] or \fIscmag\fP [\fI\%22\fP] are involved as well.
.sp
\fBProcedure:\fP
.INDENT 2.0
.IP 1. 3
Read picks, origins and amplitudes from the database and store them as
\fI\%SCML\fP in a file, \fBpicks.xml\fP, for later playbacks. Additional
command\-line options may be used to confine the retrieval:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
dump_picks \-d [database] \-t \(dq2022\-04\-01 08:00:00.00~2022\-04\-01 08:05:00.00\(dq \-o objects.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBHINT:\fP
.INDENT 2.0
.INDENT 3.5
\fBdump_picks\fP allows playing back the objects at high speed by
\fI\%\-\-speed\fP and jumping in time by :\fI\%\-j\fP\&.
.UNINDENT
.UNINDENT
.IP 2. 3
Play back all objects sending them to the \fISeisComP\fP messaging. Start
\fIscanloc\fP separately for debugging on the command line \fBconsidering
default timing\fP by creation time of all objects. When done, send all
objects to the messaging by \fBplayback_picks\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
seiscomp stop
seiscomp start scmaster scamp scmag scevent

scanloc \-\-debug
playback_picks picks.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBPicks from playbacks:\fP Play back picks and amplitudes created by a
non\-real\-time playback possibly in different
\fIpipeline\fP [\fI\%11\fP] sending them to the SeisComP messaging.
.INDENT 2.0
.IP \(bu 2
Picks and amplitudes are created in playbacks by \fIscautoloc\fP [\fI\%14\fP] and
stored in XML files (\fI\%SCML\fP format).
.IP \(bu 2
Picks and amplitudes are sent specifically to the message groups PICK, L1PICK
and AMPLITUDE.
.IP \(bu 2
\fIscanloc\fP and \fIl1scanloc\fP listen to picks from PICK and L1PICKS, respectively.
.IP \(bu 2
\fIscautoloc\fP [\fI\%14\fP] additionally needs the pick amplitudes from the
subscribed amplitude groups.
.UNINDENT
.sp
\fBProcedure:\fP
.INDENT 2.0
.IP 1. 3
Create the XML files by \fIscautopick\fP [\fI\%15\fP] including picks and
amplitudes in a non\-real\-time playback by the modules as in your 2\-pipeline
system. Since picks and amplitudes are created by the playback, their
creation times are not a relevant measure of the order in which they were
created.
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
scautopick \-d [database] \-\-ep \-\-playback \-I [your_waveforms] > picks.xml
l1autopick \-d [database] \-\-ep \-\-playback \-I [your_waveforms] > l1picks.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Start all required modules including the scanloc instances
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
seiscomp start scmaster scamp scmag scevent scautoloc l1autoloc scanloc l1scanloc
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Execute \fI\%playback_picks\fP with
\fI\%\-\-timing pickTime\fP for sending the picks and
amplitudes created by different pickers at different times.
\fBConsider timing by pick time of the picks:\fP
\fI\%\-\-timing pickTime\fP is used as an approixmation of the timing since
creation time is not meaningful in this XML playback.
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
playback_picks picks.xml:PICK:AMPLITUDE l1picks.xml:L1PICK:AMPLITUDE \-\-timing pickTime
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Non\-real\-time playbacks
.sp
Non\-real\-time (\fI\%\-\-ep\fP) playbacks are used for very fast processing of
picks and origins which are provided in XML files (\fI\%SCML\fP format).
The objects were generated before in
.INDENT 0.0
.IP \(bu 2
Real time and read from the database e.g., by
\fI\%dump_picks\fP or
.IP \(bu 2
By non\-real\-time playbacks, e.g., involving \fIscautopick\fP [\fI\%15\fP]\&.
.IP \(bu 2
Manually by \fIscolv\fP [\fI\%24\fP], \fILAMBDA\fP [\fI\%4\fP], etc.
.UNINDENT
.sp
In such playbacks, all objects are provided to scanloc
in an XML file with the option \fI\%\-\-ep\fP\&.
scanloc writes the results in \fI\%SCML\fP to stdout which can be re\-directed
into another file for further processing.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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 \fI\%\-\-timing pickTime\fP which is the default in
playbacks. For picks obtained
in real time you should use scanloc with the command\-line option
\fI\%\-\-timing creationTime\fP for setting the timing to creation time.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
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 independent of the messaging. Execute scanloc with the
appropriate timing.
.sp
\fBProcedure:\fP
.INDENT 2.0
.IP 1. 3
Run the playback
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You may jointly process picks from multiple instances of phase detectors
which are executed first. The picks and origins are provided to scanloc
after merging the XML files. Example:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
scautopick \-d [database] \-\-ep \-\-playback \-I [your_waveforms] > picks_sp.xml
dlpick \-d [database] \-\-ep \-\-playback \-I [your_waveforms] > picks_dl.xml
ccloc \-d [database] \-\-offline \-\-ep \-I [your_waveforms] > picks_origins_ccloc.xml
autothor \-d [database] \-\-offline \-\-ep \-I [your_waveforms] > picks_origins_autothor.xml
scxmlmerge picks_sp.xml picks_dl.xml picks_origins_ccloc.xml picks_origins_autothor.xml > objects.xml
scanloc \-d [database] \-\-ep objects.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
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Enter the results into the SeisComP system. Either:
.INDENT 2.0
.IP \(bu 2
\fBPreferred: Events may exist\fP 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.
\fIscamp\fP [\fI\%12\fP], \fIscmag\fP [\fI\%22\fP] , \fIscevent\fP [\fI\%19\fP]\&.
Use \fIscdispatch\fP [\fI\%17\fP] to send the new objects to
the messaging system.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
seiscomp start scmaster scamp scmag scevent
scdispatch \-H host \-i mags.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead of the \fBmags.xml\fP, other parameters created by the
playback may be dispatched, e.g., from \fBorigins.xml\fP\&. Use
\fIscdispatch\fP [\fI\%17\fP] with \fI\-e\fP to ultimately prevent sending event
objects.
.IP \(bu 2
\fBEvents do not exist\fP in the database, use \fIscdb\fP [\fI\%16\fP] to populate
the database with all events in \fBevents.xml\fP\&.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
scdb \-i events.xml \-d [database]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 2.0
.INDENT 3.5
Using \fIscdb\fP [\fI\%16\fP] 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 \fIscdispatch\fP [\fI\%17\fP] with \fBmags.xml\fP
and running \fIscmaster\fP [\fI\%23\fP] and \fIscevent\fP [\fI\%19\fP]
instead of \fIscdb\fP [\fI\%16\fP]\&. However, \fIscdispatch\fP in newer versions of
SeisComP allows ignoring Event objects with the option \fB\-e\fP\&. Then, also
\fBevents.xml\fP can be dispatched.
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
Play back picks stored in XML format, without a database but inventory and
bindings in \fI\%SCML\fP and with a local file for module configuration.
.sp
\fBProcedure:\fP
.INDENT 2.0
.IP 1. 3
Set up a local module configuration file, e.g., \fB\&./scanloc.cfg\fP
containing all parameters including \fI\%core.plugins\fP\&.
.IP 2. 3
Store the station inventory and the binding configuration from a database
in \fI\%SCML\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
scxmldump \-d [database] \-fI \-o inventory.xml
scxmldump \-d [database] \-fC \-o config.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Continue with the examples above replacing the database parameter
\fI\%\-d [database]\fP with \fI\%\-\-inventory\-db inventory.xml\fP
\fI\%\-\-config\-db config.xml\fP
and adding the module configuration in \fBscanloc.cfg\fP\&. Set the timing
accordingly:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
scanloc \-\-inventory\-db inventory.xml \-\-config\-db config.xml \e
        \-\-ep picks.xml \-\-timing [timing] \e
        \-\-config\-file scanloc.cfg > origins.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH MODULE CONFIGURATION
.nf
\fBetc/defaults/global.cfg\fP
\fBetc/defaults/scanloc.cfg\fP
\fBetc/global.cfg\fP
\fBetc/scanloc.cfg\fP
\fB~/.seiscomp/global.cfg\fP
\fB~/.seiscomp/scanloc.cfg\fP
.fi
.sp
.sp
scanloc inherits \fI\%global options\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Modules/plugins may require a license file. The default path to license
files is \fB@DATADIR@/licenses/\fP which can be overridden by global
configuration of the parameter \fBgempa.licensePath\fP\&. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gempa.licensePath = @CONFIGDIR@/licenses
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B defaultDepth
Default: \fB0.0\fP
.sp
Unit: \fIkm\fP
.sp
Type: \fIdouble\fP
.sp
Default source depth used for locating origins. The range of
supported values depends on the configured
travel\-time interface and locator.
.sp
When origin depth after locating is 0.0 or undefined, the depth
is corrected to \(dqdefaultDepth\(dq without relocating
since the situation indicates issues.
.sp
Note: A similar parameter may require configuration for score
plugins.
.UNINDENT
.INDENT 0.0
.TP
.B ignoreDepth
Default: \fB650.0\fP
.sp
Unit: \fIkm\fP
.sp
Type: \fIdouble\fP
.sp
Maximum depth of an origin to be sent.
.sp
Note: A similar parameter may require configuration for score
plugins.
.UNINDENT
.INDENT 0.0
.TP
.B use3D
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
Compute distances in 3D for cluster search,
phase association and internal event association. Otherwise,
distances are measured from geographic coordinates ignoring elevation.
.UNINDENT
.INDENT 0.0
.TP
.B maxRMS
Default: \fB1.5\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Maximum allowed overall residual of an origin to be sent.
.UNINDENT
.INDENT 0.0
.TP
.B minScore
Default: \fB0.0\fP
.sp
Type: \fIdouble\fP
.sp
Minimum score of an origin to be sent.
.UNINDENT
.INDENT 0.0
.TP
.B score
Default: \fBOriginSum\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBOriginSum,OriginMultiFeature\fP
.sp
Defines the score processor to be used for ranking origins of
events. Additional configuration of the plugin and the plugin
parameters is required.
.UNINDENT
.INDENT 0.0
.TP
.B pickComparisonLevel
Default: \fBloc\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBsta,loc,cha\fP
.sp
The level up to which compare stream IDs of multiple picks in
order to avoid origins with multiple picks from identical stream
level, e.g., station (sta), sensor location (loc) or channel
(cha).
.sp
The level is derived from the NET.STA.LOC.CHA stream
representation. Picks with equal stream IDs on the given level
are treated as originating from the same stream no matter of the
ID on a lower level. Clusters having picks on streams equal on
the given level are split into new clusters with unique streams.
During association picks equal on the given level are ignored \-
the first assigned pick is considered.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBbuffer.*\fP
\fIDefine buffering of picks and origins. scanloc only treats picks\fP
\fIand origins kept in the buffer.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B buffer.pickKeep
Default: \fB180.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.pickIgnoreStreamID
Type: \fIlist:string\fP
.sp
Ignore picks created on given stream ID(s). Stream IDs may
contain wildcards. Separate multiple IDs by comma.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.ignorePickTimeDifference
Default: \fB0.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Generally, all available picks are added to the buffer and
made available for processing. Use this option to ignore new
picks made on the same data stream within the given time
difference to a previously buffered pick. A value of 0.0 s
ignores all picks with identical times.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.originKeep
Default: \fB180.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.ignoreOrigins
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
Ignore and do not buffer external origins received from
messaging or from XML files.
.sp
Default: Accept external origins from messaging or XML and
associate more phases.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.ignoreManualOrigins
Default: \fBtrue\fP
.sp
Type: \fIboolean\fP
.sp
Ignore and do not buffer manual external origins received
from messaging or from XML files.
.sp
The parameter \(dqbuffer.ignoreOrigins\(dq must be
inactive for this option to be effective.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.originStatusIgnore
Type: \fIlist:string\fP
.sp
Values: \fBrejected,reported,preliminary,confirmed,reviewed,final\fP
.sp
Ignore an external origin if its status has any of the given
states.      The option is ignored for manual origins if
buffer.ignoreManualOrigins = false.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.authorWhiteList
Type: \fIlist:string\fP
.sp
Only buffer picks or origins from the given authors.
Separate multiple authors by comma. Picks and origins from
other authors will be ignored. Wildcards are supported.
This parameter overrides
\(dqbuffer.originAuthorWhiteList\(dq. Manual origins are
treated regardless of the author as defined by
\(dqbuffer.ignoreManualOrigins\(dq.
The parameter allows operation of scanloc based on picks and
origins from a specific module, e.g., in a pipeline.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.originAuthorWhiteList
Type: \fIlist:string\fP
.sp
Deprecated parameter which will be removed in 2025. Use
\(dqbuffer.authorWhiteList\(dq instead which overrides
this parameter!
.sp
Only buffer external origins from the given authors to the.
Separate multiple authors by comma. Manual origins
are treated regardless of the author as defined by
\(dqbuffer.ignoreManualOrigins\(dq.
.sp
The parameter \(dqbuffer.ignoreOrigins\(dq must be
inactive for this option to be effective.
.UNINDENT
.INDENT 0.0
.TP
.B buffer.futureTimeDelta
Default: \fB0.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
The time delta to the future. Positive values allow objects
with times in the future to be buffered when the difference
to current time or to creation time is not larger than the
given value.
.sp
Normally, objects like picks and origins are created after
their actual times and all other objects are spurious and
should be ignored. In case of wrong sensor timing or
faster\-than\-real\-time waveform playbacks, objects may be
generated with actual times (pick time or origin time) in
the future.
.sp
If less or equal to 0.0, then all objects created before
time of the object or with object times in the future are
ignored.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBclusterSearch.*\fP
\fIParameters controlling the cluster search based on phase\fP
\fIpicks of configured phase type.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.phaseType
Default: \fBP\fP
.sp
Type: \fIstring\fP
.sp
Phase type of considered picks. Valid types: P or Is.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.minSize
Default: \fB4\fP
.sp
Type: \fIint\fP
.sp
Minimum number of core points (picks) to form a cluster.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.maxSize
Default: \fB\-1\fP
.sp
Type: \fIint\fP
.sp
Maximum number of picks in a cluster when stopping
clustering. Eventual clusters may still be larger from core
points. Using values < 0 deactivates the feature.
.sp
The parameter is meant to support large\-N networks where the
high network density results in very many clusters with high
computational load effectively slowing down the processing
of picks. Using reasonable values such as 10 or 15 will
reduce the number of clusters while maintaining high quality
initial origins.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.maxPickDelay
Default: \fB\-1.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
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 \(dq\-1\(dq enables all picks
regardless of the delay.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.referenceTimeMode
Default: \fBLastPick\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBLastPick,MaxPickDelay\fP
.sp
Mode to set the cluster reference time. Read the documentation
for the details. Available modes:
.sp
LastPick: The pick time of the last incoming P pick is the
cluster reference time.
.sp
MaxPickDelay: Setting the cluster reference time is delayed
until clusterSearch.minSize and association.minPhase picks
are available.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.regionFilter
Type: \fIlist:double\fP
.sp
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.
.sp
Example: 50.1,12.3,20
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.averageVelocity
Default: \fB7.0\fP
.sp
Unit: \fIkm/s\fP
.sp
Type: \fIdouble\fP
.sp
Average velocity used for distance calculation.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.maxSearchDist
Default: \fB60\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.maxOrigins
Default: \fB128\fP
.sp
Type: \fIuint\fP
.sp
Maximum allowed origins derived from cluster search. Set this
option to zero to disable the cluster search completely.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.preliminary
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
Send origins based on cluster search as preliminary origins
if the location fails. Otherwise those origins are ignored.
Consider activating \(dqcheckOrigins\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B clusterSearch.checkOrigins
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
Check, if derived origins fulfill the cluster search criteria
anymore. Activating this option may lower the number of events
and suppress fake events.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBassociation.*\fP
\fIParameters controlling the association of P and S phases to cluster\fP
\fIorigins or external origins.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B association.minPhase
Default: \fB4\fP
.sp
Type: \fIint\fP
.sp
Number picks in cluster origin to be reached for starting to
associate more P and S picks.
.UNINDENT
.INDENT 0.0
.TP
.B association.maxDist
Default: \fB1000.0\fP
.sp
Unit: \fIkm\fP
.sp
Type: \fIdouble\fP
.sp
Maximum distance from origin to stations
for associating P and S picks.
.UNINDENT
.INDENT 0.0
.TP
.B association.stationConfig
Type: \fIfile\fP
.sp
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
\(dqassociation.maxDist\(dq.
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. Example:
.sp
* * 1 10
.sp
GE * 1 180
.UNINDENT
.INDENT 0.0
.TP
.B association.maxPResidual
Default: \fB4.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Maximum allowed difference between measured and predicted arrival
times for associating P phases to origin.
Larger values allow significant correction of initial locations.
.UNINDENT
.INDENT 0.0
.TP
.B association.dropReferenceCheck
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
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 check.
.UNINDENT
.INDENT 0.0
.TP
.B association.maxSResidual
Default: \fB4.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Maximum allowed difference between measured and predicted arrival
time for associating S phases to origins. Larger values allow
significant correction of initial locations.
.UNINDENT
.INDENT 0.0
.TP
.B association.maxResidual
Default: \fB2.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Maximum allowed time residuals of picks after association and
relocation. Picks will be removed at exceedence starting with
largest residual and origins will be relocated.
.UNINDENT
.INDENT 0.0
.TP
.B association.arrivalCountMinRes
Default: \fB\-1\fP
.sp
Type: \fIint\fP
.sp
The number of arrivals of an origin for controlling the
association of more picks. Beyond this number, the minimum
of maxPResidual or maxSResidual and maxResidual for
associating P or S phases, respectively, is tested before
association.
.sp
The parameter also speeds up the evaluation of origins with
more arrivals than configured: Instead of
testing residuals of arrivals individually and relocating
thereafter, all arrivals not passing the residual check are
removed in a bulk.
.sp
The parameter is meant to support large\-N networks where the
high network density results in very many picks and high
computational load, effectively slowing down the quality
check of picks. Setting a reasonable value, e.g., >20 will
only associate the best picks to origins already well
constraint.
.sp
Using values <= 0 deactivates the feature.
.UNINDENT
.INDENT 0.0
.TP
.B association.tableType
Default: \fBLOCSAT\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBLOCSAT,libtau,homogeneous\fP
.sp
Type of travel\-time tables for phase association.
May be different from locator.
.UNINDENT
.INDENT 0.0
.TP
.B association.table
Default: \fBiasp91\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBiasp91,iasp91_scanloc\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B association.zeroWeightProfiles
Type: \fIlist:string\fP
.sp
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.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBassociation.zeroWeight.*\fP
\fIZero\-weight profiles containing the parameters for associating\fP
\fIphases with zero weight to origins.\fP
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBassociation.zeroWeight.$name.*\fP
$name is a placeholder for the name to be used and needs to be added to \fBzeroWeight.profiles\fP to become active.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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 = ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B association.zeroWeight.$name.phaseType
Type: \fIString\fP
.sp
One phase type to be associated with zero weight.
Examples: PKP or Pdiff.
.UNINDENT
.INDENT 0.0
.TP
.B association.zeroWeight.$name.minDistance
Default: \fB120.0\fP
.sp
Unit: \fIdegree\fP
.sp
Type: \fIdouble\fP
.sp
Minimum distance from origin to stations.
.UNINDENT
.INDENT 0.0
.TP
.B association.zeroWeight.$name.maxResidual
Default: \fB5.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Maximum time residual of the associated phase.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBlocator.*\fP
\fIParameters controlling the locator for locating scanloc\fP
\fIorigins.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B locator.type
Default: \fBLOCSAT\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBExternal,FixedHypocenter,Hypo71,iLoc,LOCSAT,NonLinLoc,Router,StdLoc\fP
.sp
The locator type to be used.
.UNINDENT
.INDENT 0.0
.TP
.B locator.profile
Default: \fBiasp91\fP
.sp
Type: \fIstring\fP
.sp
Values: \fBiasp91,iasp91_scanloc\fP
.sp
The locator profile to be used. Using a different profile/table
for locating and associating may result in increased runtime.
.UNINDENT
.INDENT 0.0
.TP
.B locator.fixDepth
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
If enabled, the locator fixes the depth to the configured
default value \(dqdefaultDepth\(dq in case that all
previous attempts to relocate fail.
This option may result in many more origins. It
prevents \(dqignoreDepth\(dq from beeing
effective if \(dqdefaultDepth\(dq < \(dqignoreDepth\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B locator.forceFixDepth
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
If enabled, the locator is forced to fix the depth to the
value configured by \(dqdefaultDepth\(dq. Free\-depth
solutions are thus excluded. Activating this option may be
useful for sources with known depths or in case of sparse
networks.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBeventAssociation.*\fP
\fIParameters controlling the association of interval scanloc\fP
\fIorigins to internal scanloc events.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B eventAssociation.compareAllArrivalTimes
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
This parameter is only used in conjunction with
\(dqeventAssociation.maximumMatchingArrivalTimeDiff\(dq.
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
\(dqeventAssociation.maximumMatchingArrivalTimeDiff\(dq
or if one matching arrival is enough.
.UNINDENT
.INDENT 0.0
.TP
.B eventAssociation.minMatchingArrivals
Default: \fB3\fP
.sp
Type: \fIint\fP
.sp
Minimum number of matching picks between two origins to be
associated to the same event.
.UNINDENT
.INDENT 0.0
.TP
.B eventAssociation.maxMatchingArrivalTimeDiff
Default: \fB\-1\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B eventAssociation.maxDist
Default: \fB500.0\fP
.sp
Unit: \fIkm\fP
.sp
Type: \fIdouble\fP
.sp
Allowed difference in epicenter between an incoming origin
compared with preferred origins to get associated.
.UNINDENT
.INDENT 0.0
.TP
.B eventAssociation.maxTimeSpan
Default: \fB60.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Associates an origin with an existing event if the origin
time differs not more than 60 seconds unless the
minimumMatchingArrivals criteria matches.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBpublication.*\fP
\fIParameters controlling the publication delay of origin for\fP
\fIinternal events to the messaging system. The delay\fP
\fItime, t, is calculated as t = a x N + b where N is the number\fP
\fIof arrivals of the origin. After t seconds, the best origin\fP
\fIis published. The first origin is always published.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B publication.intervalTimeSlope
Default: \fB0.5\fP
.sp
Unit: \fIs/count\fP
.sp
Type: \fIdouble\fP
.sp
Parameter \(dqa\(dq in the equation t = a x N + b.
.sp
Increasing the value reduces the amount of sent origins.
With the option \-\-ep (playback mode) this value is set to 0.
.UNINDENT
.INDENT 0.0
.TP
.B publication.intervalTimeIntercept
Default: \fB0.0\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Parameter \(dqb\(dq  in the equation t = a x N + b.
.sp
Increasing the value reduces the amount of sent origins.
With the option \-\-ep (playback mode) this value is set to 0.
.UNINDENT
.INDENT 0.0
.TP
.B publication.wakeUpInterval
Default: \fB5\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIint\fP
.sp
Integer interval to check the origin buffer for sending
origins if no other origins have been created.
.sp
Reducing the value may be required in EEW: it increases the
load on scanloc but allows to send origins more rapidly.
.UNINDENT
.SS ScoreMF plugin
.sp
Plugin for computing a score for an origin by the OriginMultiFeature
score processor.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBscore.*\fP
\fIOrigin score processor \(dqOriginMultiFeature\(dq returning a score\fP
\fIfor an origin as a measure of goodness. The score is\fP
\fIthen compared against minScore.     Requires to configure\fP
\fIthe global parameter *plugins\fP with \(dqscoremf\(dq in order to*
\fIload this gempa plugin and to set *minScore\fP and \fIscore*\fP
\fIaccordingly.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.defaultScore
Default: \fB0.0\fP
.sp
Type: \fIdouble\fP
.sp
The default score returned for an origin that fails
completely or is filtered out by thresholds such as for
depth and RMS.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.strongMotionCodes
Default: \fBL,N\fP
.sp
Type: \fIlist:string\fP
.sp
List of one\-letter instrument codes (2nd letter) in
channel codes identifying strong motion sensors, e.g.,
in HL?, HN?.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.infrasoundCodes
Default: \fBD\fP
.sp
Type: \fIlist:string\fP
.sp
List of one\-letter instrument codes (2nd letter) in
channel codes identifying infrasound sensors, e.g., in
HDF.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.p
Default: \fB1.0,0.0,0.0\fP
.sp
Type: \fIlist:double\fP
.sp
The weight for number of used P arrival measures.
Assumes only arrival time when exactly 1 value is set.
Use a comma\-separated list, wT,wSlo,wBaz, for giving
specific weight to pick time, slowness and back azimuth,
respectively.
Example: 1.0,0.0,0.0 .
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.p0
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
Weight per unused P pick.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.s
Default: \fB2.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight per used S pick.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.s0
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
Weight per unused S pick.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.normalizationDepth
Default: \fB650.0\fP
.sp
Type: \fIdouble\fP
.sp
Origin depth is normalized to this value for
computing the score contribution. Shallower depths
contribute to larger score.
This is also the maximum allowed depth. Origins with
depth greater then this value get a score equal to
\(dqdefaultScore\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.depth
Default: \fB1.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight for depth\-based quality score.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.normalizationRMS
Default: \fB1.5\fP
.sp
Type: \fIdouble\fP
.sp
Origin RMS is normalized to this value for computing
the score contribution. Lower RMS contribute to
larger score.
This is also the maximum allowed RMS. Origins with
residual greater than this value score equal to
\(dqdefaultScore\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.residual
Default: \fB1.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight for RMS\-based quality score.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.gap
Default: \fB1.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight for azimuthal gap score. The smaller the gap
the larger the score.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.manualPick
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
Weight per used manual pick.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.strongMotion
Default: \fB0.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight per used strong motion pick as defined in
\(dqstrongMotionCodes\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.infrasound
Default: \fB0.0\fP
.sp
Type: \fIdouble\fP
.sp
Weight per used infrasound pick as defined in
\(dqinfrasoundCodes\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B score.mf.weights.authors
Unit: \fIauthor:score\fP
.sp
Type: \fIlist:string\fP
.sp
List of tuple of authors and score contribution.
If an author matches, the corresponding score
contribution is added to the final score.
.sp
Example: \(dqscautoloc:1,scanloc:10,ccloc:100\(dq.
.UNINDENT
.SS ScoreSum plugin
.sp
Plugin for scoring origins in scanloc by score processor OriginSum
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBscore.sum.*\fP
\fIOrigin score processor \(dqOriginSum\(dq: Compute origin scores as\fP
\fIweighted averages of number of used\fP
\fIP phases (p), number of unused P phases (p0), number of used\fP
\fIS phases (s), number of unused S phases (s0), origin depth and\fP
\fIresidual. The score applies for ranking origins of events. Add\fP
\fIthe plugin \(dqscoresum\(dq to the global parameter \(dqplugins\(dq and\fP
\fI\(dqOriginSum\(dq to the scanloc parameter \(dqscore\(dq for applying this\fP
\fIscore processor.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.p
Default: \fB1.0\fP
.sp
Type: \fIlist:double\fP
.sp
The weight for number of used P arrival measures.
Assumes only arrival time when exactly 1 value is set.
Use a comma\-separated list, wT,wSlo,wBaz, for giving
specific weight to pick time, slowness and back azimuth,
respectively.
Example: 1.0,0.0,0.0 .
.sp
The usage of slowness and back azimuth depends on locator.
They are not considered by Hypo71, NonLinLoc, StdLoc and
FixedHypocenter.
.sp
The parameter is used for Is infrasound phases when
considered in clustering.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.p0
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
The weight for number of added but unused P arrivals.
.sp
The parameter is used for Is infrasound phases when
considered in clustering.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.s
Default: \fB2.0\fP
.sp
Type: \fIlist:double\fP
.sp
The weight for number of used S arrival measures.
Assumes only arrival time when exactly 1 value is set.
Use a comma\-separated list, wT,wSlo,wBaz, for giving
specific weight to pick time, slowness and back azimuth,
respectively.
Example: 2.0,0.0,0.0 .
.sp
The usage of slowness and back azimuth depends on locator.
They are not considered by Hypo71, NonLinLoc, StdLoc and
FixedHypocenter.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.s0
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
The weight for number of added but unused S arrivals.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.normalizationDepth
Default: \fB650.0\fP
.sp
Unit: \fIkm\fP
.sp
Type: \fIdouble\fP
.sp
Origin depth is normalized to this value for computing the
score contribution. Shallower depths contribute to larger
score.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.depth
Default: \fB1.0\fP
.sp
Type: \fIdouble\fP
.sp
The weight of origin depth. Set this value to 0.0 for
scoring origins independent of depth whenever shallow and
deep sources are equally expected.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.normalizationRMS
Default: \fB1.5\fP
.sp
Unit: \fIs\fP
.sp
Type: \fIdouble\fP
.sp
Origin RMS is normalized to this value for computing the
score contribution. Lower RMS contribute to larger score.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.residual
Default: \fB1.0\fP
.sp
Type: \fIdouble\fP
.sp
The weight of origin RMS residual.
.UNINDENT
.INDENT 0.0
.TP
.B score.sum.increaseManual
Default: \fBfalse\fP
.sp
Type: \fIboolean\fP
.sp
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.
.UNINDENT
.SH COMMAND-LINE OPTIONS
.sp
\fBscanloc [options]\fP
.SS Generic
.INDENT 0.0
.TP
.B \-h, \-\-help
Show help message.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-version
Show version information.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-plugins arg
Load given plugins.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-daemon
Run as daemon. This means the application will fork itself
and doesn\(aqt need to be started with &.
.UNINDENT
.SS Verbosity
.INDENT 0.0
.TP
.B \-\-verbosity arg
Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
4:debug.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-v
Increase verbosity level (may be repeated, eg. \-vv).
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Quiet mode: no logging output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-component arg
Limit the logging to a certain component. This option can
be given more than once.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-syslog
Use syslog logging backend. The output usually goes to
/var/lib/messages.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-lockfile arg
Path to lock file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-console arg
Send log output to stdout.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug
Execute in debug mode.
Equivalent to \-\-verbosity=4 \-\-console=1 .
.UNINDENT
.INDENT 0.0
.TP
.B \-\-trace
Execute in trace mode.
Equivalent to \-\-verbosity=4 \-\-console=1 \-\-print\-component=1
\-\-print\-context=1 .
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file arg
Use alternative log file.
.UNINDENT
.SS Messaging
.INDENT 0.0
.TP
.B \-u, \-\-user arg
Overrides configuration parameter \fI\%connection.username\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-host arg
Overrides configuration parameter \fI\%connection.server\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-timeout arg
Overrides configuration parameter \fI\%connection.timeout\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-g, \-\-primary\-group arg
Overrides configuration parameter \fI\%connection.primaryGroup\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-S, \-\-subscribe\-group arg
A group to subscribe to.
This option can be given more than once.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-start\-stop\-msg arg
Default: \fB0\fP
.sp
Set sending of a start and a stop message.
.UNINDENT
.SS Database
.INDENT 0.0
.TP
.B \-\-db\-driver\-list
List all supported database drivers.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-database arg
The database connection string, format:
\fI\%service://user:pwd@host/database\fP\&.
\(dqservice\(dq is the name of the database driver which
can be queried with \(dq\-\-db\-driver\-list\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-config\-module arg
The config module to use.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-inventory\-db arg
Load the inventory from the given database or file, format:
[\fI\%service://]location\fP .
.UNINDENT
.INDENT 0.0
.TP
.B \-\-db\-disable
Do not use the database at all.
.UNINDENT
.SS Input
.INDENT 0.0
.TP
.B \-\-ep arg
Type: \fIstring\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-timing arg
Default: \fBpickTime\fP
.sp
Values: \fBcreationTime,pickTime\fP
.sp
Timing reference in offline processing with \-\-ep: Use
pickTime and creationTime for sorting picks according to
pick time and creation time, respectively. pickTime is
assumed if no timing is specified. Note: In real\-time
processing picks are treated as they arrive corresponding to
creationTime and this option is irrelevant.
.UNINDENT
.SS Buffer
.INDENT 0.0
.TP
.B \-\-allow\-rejected\-picks
Allow processing of picks with evaluation status \(aqrejected\(aq.
Otherwise these picks are ignored and not buffered.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-drop\-reference\-check
Overrides configuration parameter \fI\%association.dropReferenceCheck\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-author\-whitelist arg
Type: \fIlist:string\fP
.sp
Only consider picks and origins created by the given
author(s). Separate multiple authors by
comma. Wildcards are supported.Empty strings
allow all authors. Manual origins are treated regardless of
the author as defined by
\(dqbuffer.ignoreManualOrigins\(dq. The option allows
operating scanloc based on picks and origins from a specific
module, e.g., in a pipeline.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-future\-time\-delta arg
Overrides configuration parameter \fI\%buffer.futureTimeDelta\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-origin\-keep arg
Overrides configuration parameter \fI\%buffer.originKeep\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pick\-keep arg
Overrides configuration parameter \fI\%buffer.pickKeep\fP\&.
.UNINDENT
.SS Locator
.INDENT 0.0
.TP
.B \-\-locator\-type arg
Overrides configuration parameter \fI\%locator.type\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-locator\-profile arg
Overrides configuration parameter \fI\%locator.profile\fP\&.
.sp
Type: \fIstring\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-locator\-list
List all registered locators.
.UNINDENT
.SS Output
.INDENT 0.0
.TP
.B \-\-final\-only
Limit result set to final origins only. This option is
available for non\-real\-time (\-\-ep) processing only.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dump\-origins
Don\(aqt publish origins, write them to stdout. Useful for
tuning.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cluster\-search\-log\-file arg
Type: \fIstring\fP
.sp
File name to output detailed cluster search information.
Useful for tuning.
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-formatted
Use formatted XML output along with  \(aq\-\-ep\(aq. Otherwise XML
is unformatted.
.UNINDENT
.SH AUTHOR
gempa GmbH
.SH COPYRIGHT
2014, gempa GmbH
.\" Generated by docutils manpage writer.
.