SCRTDD(1)

NAME
scrtdd - rtDD: Real-time Double-Difference Documentation

Double-difference earthquake relocation module.

CONFIGURATION
etc/defaults/global.cfg
etc/defaults/scrtdd.cfg
etc/global.cfg
etc/scrtdd.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scrtdd.cfg

scrtdd inherits global options.

automaticOrigins
    Type: boolean

    Allow relocation of automatic origins. Default is true.

manualOrigins
    Type: boolean

    Allow relocation of manual origins. Default is true.

onlyPreferredOrigins
    Type: boolean

    Relocate only preferred origins. When disabled, scrtdd processes all origins received on the LOCATION messaging group. When enabled, it only processes preferred origins from events received on the EVENT group. Default is true.

acceptedOriginAuthors
    Type: list:string

    A comma-separated list of author IDs. Only origins from these authors will be considered for relocation. If empty, origins from all authors are considered.

activeProfiles
    Type: list:string

    Defines a list of active profiles for single-event (real-time) processing.

performance.delayTime
    Type: int

    Unit: sec

    Specifies a delay in seconds after an origin is created/updated to trigger the single-event relocation. Default is 10.

performance.profileTimeAlive
    Type: int

    Unit: sec

    Defines how long the profile data should be kept in memory (in seconds). This is useful to release memory (catalog waveform data) after a period of inactivity. A negative value force the profiles to stay always in memory. Default is 600.

performance.cacheWaveforms
    Type: boolean

    Save reference catalog waveforms to local disk after they have been loaded for the first time. This avoids re-reading them from the configured recordStream. Default is true.

performance.cacheDirectory
    Type: path

    Defines the base directory for the waveform cache. Each profile will store its waveforms in a subdirectory named after the profile (e.g., @cacheDirectory@/[profile_name]/wfcache). Default is @ROOTDIR@/var/lib/rtdd.

performance.cachedWaveformLength
    Type: double

    Unit: sec

    The waveform length (centered around pick time) to be used for the disk cache. Although the required waveform length is inferred from the cross-correlation settings, this option allows for a longer disk-cached trace that is useful if cross-correlation settings are changed in the future. Default is 10.

    NOTE: profile.* Each profile is a configuration set with an optional region. The region is used in real-time processing to select a profile for an incoming origin. If an origin falls into multiple profile regions, the profile defined first in the 'activeProfiles' list will be used. This allows for hierarchical regions, where specific regions are defined first and a broader region is defined last. A profile is only active in real-time processing when added to the 'activeProfiles' list.

    NOTE: profile.$name.* $name is a placeholder for the name to be used and needs to be added to rtdd.activeProfiles to become active.

    rtdd.activeProfiles = a,b
    profile.a.value1 = ...
    profile.b.value1 = ...
    # c is not active because it has not been added
    # to the list of rtdd.activeProfiles
    profile.c.value1 = ...

profile.$name.regionType
    Type: string

    Type of region: RECTANGULAR or CIRCULAR. Default is CIRCULAR.

profile.$name.region
    Type: list:double

    Optional. If regionType is RECTANGULAR, 4 comma-separated values are expected: min_lat, min_lon, max_lat, max_lon. If regionType is CIRCULAR, 3 comma-separated values are expected: lat, lon, radius in km. If left empty, the region is limitless.

profile.$name.methodID
    Type: string

    The methodID label to be stored in created origins. Default is RTDD.

profile.$name.tableType
    Type: string

    Travel-time table format type (e.g. homogeneous, NLLGrid, LOCSAT). Default is LOCSAT.

profile.$name.tableModel
    Type: string

    The model to be used. The format depends on tableType. Default is iasp91.

profile.$name.PSTableOnly
    Type: boolean

    If enabled, travel-time information is fetched using 'P' and 'S' tables only, and the specific phase type (e.g., Pg, Sg, Pn) is not considered. Default is true.

profile.$name.P-Phases
    Type: list:string

    A list of accepted P-wave phases. Phases not in this list will be ignored. Default is P,Pg,Pn.

profile.$name.S-Phases
    Type: list:string

    A list of accepted S-wave phases. Phases not in this list will be ignored. Default is S,Sg,Sn.

profile.$name.automaticOriginP
    Type: string

    Phase mapping of automatic origin P phase. This defines which specific catalog arrival (e.g., Pg, Pn) is paired with the generic P phase of automatic origins. Only catalog phases matching the selected type are used.

profile.$name.automaticOriginS
    Type: string

    Phase mapping of automatic origin S phase. This defines which specific catalog arrival (e.g., Sg, Sn) is paired with the generic S phase of automatic origins. Only catalog phases matching the selected type are used.

profile.$name.pickUncertaintyClasses
    Type: list:string

    Unit: s

    Defines pick time uncertainty thresholds (in seconds) used to classify picks for weighting. This parameter defines a list of interval boundaries. A pick's class is determined by the interval its uncertainty falls into. E.g., a pick with an uncertainty of 0.150s falls into the 4th interval (between 0.100 and 0.200) and is assigned class 4. If a pick's uncertainty is absent, the lowest class is used. The pick weight is computed as: 1 / 2^(class-1). Default is 0.000,0.025,0.050,0.100,0.200,0.400.

    NOTE: profile.$name.catalog.* Define the reference catalog for this profile.

profile.$name.catalog.eventFile
    Type: path

    Path to event file to be used for this profile. If this file contains just one column called "origin", then each line must be an existing origin id and neither phase.csv nor station.csv files are required. Alternatively the extended format requires all of event.csv, phase.csv and station.csv files to be provided

profile.$name.catalog.phaFile
    Type: path

    Path to catalog picks file to be used for this profile

profile.$name.catalog.stationFile
    Type: path

    Path to the stations file to be used for this profile

    NOTE: profile.$name.doubleDifferenceSystem.* Clustering configuration, which is responsible for selecting the event pairs and their phases to be used in the double-difference equation system.

    NOTE: profile.$name.doubleDifferenceSystem.eventFiltering.* Exclude poorly connected events (events with not enough phases and/or neighbours).

profile.$name.doubleDifferenceSystem.eventFiltering.minNumPhases
    Type: int

    Minimum number of phases at common stations required between an event pair. Pairs not satisfying this condition will not be used. Default is 8.

profile.$name.doubleDifferenceSystem.eventFiltering.minNumNeighbours
    Type: int

    Minimum number of neighbours required by an event. Events not satisfying this condition will not be used in the relocation. Default is 4.

    NOTE: profile.$name.doubleDifferenceSystem.phaseFiltering.* Exclude non-optimal phases from the DD system.

profile.$name.doubleDifferenceSystem.phaseFiltering.minStationToEventPairDistRatio
    Type: double

    Minimum ratio between the event-station distance and the inter-event distance. Phases from stations not satisfying this condition will not be used. Default is 3.

profile.$name.doubleDifferenceSystem.phaseFiltering.minStationDistance
    Type: double

    Unit: km

    Minimum distance (km) between an event and a station for a phase to be used. Phases from stations not satisfying this condition will not be used.

profile.$name.doubleDifferenceSystem.phaseFiltering.maxStationDistance
    Type: double

    Unit: km

    Maximum distance (km) between an event and a station for a phase to be used. Phases from stations not satisfying this condition will not be used. A value of 0 or less disables this limit.

    NOTE: profile.$name.doubleDifferenceSystem.eventPairSelection.* Controls how neighbouring events are selected. In the simplest form, 'numEllipsoids' is set to 0 and neighbours are selected on a nearest-neighbor basis within a search distance of 'maxNeighbourDistance'. When 'numEllipsoids' is not 0, the ellipsoid selection algorithm (Waldhauser, 2009) is used to ensure spatially homogeneous subsampling. Reference events are selected within concentric, vertically elongated ellipsoidal layers of increasing thickness. Each layer is split into eight quadrants (cells), and neighboring events are selected from each of the resulting cells in a round-robin fashion until 'maxNumNeighbours' is reached.

    NOTE: profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.* Configuration for single-event relocation.

profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.maxNumNeighbours
    Type: int

    Maximum number of neighbors per event. A value of 0 disables this limit. Default is 80.

profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.maxNeighbourDistance
    Type: double

    Unit: km

    Maximum distance between an event and its neighbouring events. If 'numEllipsoids' is greater than 0, this value is the horizontal axis length (km) of the outermost boundary. Each inner concentric layer axis will be half of the previous one. The vertical axis is twice as long as the horizontal ones. Default is 5.

profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.numEllipsoids
    Type: int

    If set to 0, the nearest-neighbor event selection is used. Otherwise, this is the number of concentric ellipsoidal layers to be used in the neighboring event selection. Default is 5.

    NOTE: profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.* Configuration for multi-event relocation.

profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.maxNumNeighbours
    Type: int

    Maximum number of neighbors per event. A value of 0 or less disables this limit. Default is 40.

profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.maxNeighbourDistance
    Type: double

    Unit: km

    Maximum distance between an event and its neighbouring events. If 'numEllipsoids' is greater than 0, this value is the horizontal axis length (km) of the outermost boundary. Each inner concentric layer axis will be half of the previous one. The vertical axis is twice as long as the horizontal ones. Default is 5.

profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.numEllipsoids
    Type: int

    If set to 0, the nearest-neighbor event selection is used. Otherwise, this is the number of concentric ellipsoidal layers to be used in the neighboring event selection. Default is 0.

    NOTE: profile.$name.crossCorrelation.* Waveform cross-correlation is used to improve the differential travel times used in the double-difference system.

profile.$name.crossCorrelation.enable
    Type: boolean

    Enable or disable waveform cross-correlation. Default is false.

profile.$name.crossCorrelation.minStationDistance
    Type: double

    Unit: km

    Minimum allowed distance between event and station. Phases belonging to closer stations will not be used in cross-correlation. Default is 0.

profile.$name.crossCorrelation.maxStationDistance
    Type: double

    Unit: km

    Maximum allowed distance between event and station. Phases belonging to more distant stations will not be used in cross-correlation. A value of -1 or less removes this limit. Default is 60.

profile.$name.crossCorrelation.maxInterEventDistance
    Type: double

    Unit: km

    Maximum allowed distance (km) between events for cross-correlation to be performed. Phases of event pairs whose inter-event distance is greater than this value will not be cross-correlated. A value of -1 or less removes this limit. Default is 2.

profile.$name.crossCorrelation.p-phase.minCCCoef
    Type: double

    Minimum cross-correlation coefficient required to use a differential travel time derived from cross-correlation. Default is 0.70.

profile.$name.crossCorrelation.p-phase.winStart
    Type: double

    Unit: sec

    Start of the data window to cross-correlate, relative to the pick time (+/- seconds). Default is -0.50.

profile.$name.crossCorrelation.p-phase.winEnd
    Type: double

    Unit: sec

    End of the data window to cross-correlate, relative to the pick time (+/- seconds). Default is 0.50.

profile.$name.crossCorrelation.p-phase.winScaling
    Type: double

    Window scaling coefficient. The final window length is calculated as: Window Length = (winEnd-winStart) + TravelTime * winScaling. Default is 0.02.

profile.$name.crossCorrelation.p-phase.maxDelay
    Type: double

    Unit: sec

    Maximum lag (in seconds) between data windows allowed. Default is 0.50.

profile.$name.crossCorrelation.p-phase.components
    Type: list:string

    Priority list of components to use for cross-correlation (e.g., Z,N,E,1,2,3). The first component in the list that exists for both phases is used. Special values: 'L2' computes the L2 norm of the horizontal components; 'T' and 'R' compute the transverse and radial components, respectively, relative to the event location. If empty, the component on which the phase was picked is used (if identical for both phases). Default is Z.

profile.$name.crossCorrelation.s-phase.minCCCoef
    Type: double

    Minimum cross-correlation coefficient required to use a differential travel time derived from cross-correlation. Default is 0.70.

profile.$name.crossCorrelation.s-phase.winStart
    Type: double

    Unit: sec

    Start of the data window to cross-correlate, relative to the pick time (+/- seconds). Default is -0.50.

profile.$name.crossCorrelation.s-phase.winEnd
    Type: double

    Unit: sec

    End of the data window to cross-correlate, relative to the pick time (+/- seconds). Default is 1.00.

profile.$name.crossCorrelation.s-phase.winScaling
    Type: double

    Window scaling coefficient. The final window length is calculated as: Window Length = (winEnd-winStart) + TravelTime * winScaling. Default is 0.04.

profile.$name.crossCorrelation.s-phase.maxDelay
    Type: double

    Unit: sec

    Maximum lag (in seconds) between data windows allowed. Default is 0.50.

profile.$name.crossCorrelation.s-phase.components
    Type: list:string

    Priority list of components to use for cross-correlation (e.g., Z,N,E,1,2,3). The first component in the list that exists for both phases is used. Special values: 'L2' computes the L2 norm of the horizontal components; 'T' and 'R' compute the transverse and radial components, respectively, relative to the event location. If empty, the component on which the phase was picked is used (if identical for both phases). Default is L2.

    NOTE: profile.$name.crossCorrelation.waveformFiltering.* Filter waveforms before performing cross-correlation.

profile.$name.crossCorrelation.waveformFiltering.filterString
    Type: string

    SeisComP string-based filter definition, e.g., "ITAPER(1)>>BW_HLP(2,1,20)". Set to "" to disable filtering.

profile.$name.crossCorrelation.waveformFiltering.margin
    Type: double

    Unit: sec

    Extra seconds of data to add to the waveform ends before applying the filter. This helps initialize the filter and allows for discarding potential artifacts at the trace ends. Default is 1.

profile.$name.crossCorrelation.waveformFiltering.resampling
    Type: double

    Unit: Hz

    Resample all traces to this sampling frequency (Hz). Set to 0 to disable resampling. Default is 0.

    NOTE: profile.$name.solver.* These options control the double-difference system solver. The solution is found through an iterative process: a system is built from the initial locations and solved. The hypocenters are then updated, and a new system is built and solved again. This is repeated until 'algoIterations' is reached.

profile.$name.solver.solverType
    Type: string

    Solver algorithm to use: either LSMR or LSQR. Default is LSMR.

profile.$name.solver.algoIterations
    Type: int

    Number of iterations for the solver to perform. Default is 20.

profile.$name.solver.downWeightingByResidual
    Type: list:double

    Specifies residual thresholds for down-weighting equations. Equations with residuals smaller than this value (in standard deviations) are down-weighted and the rest discarded (0 weighed). A value of 0 disables this. If two values are given, are used for the first and last iterations respectively, with intermediate iterations using interpolated values. Default is 10,5.

profile.$name.solver.dampingFactor
    Type: list:double

    A non-zero value enables a damped (regularized) least-squares system. If two values are given, they are for the first and last iterations, with interpolation in between. Default is 0.01.

profile.$name.solver.absoluteLocationConstraint
    Type: list:double

    If greater than 0, the system is modified to solve for both absolute and relative locations by adding equations that constrain absolute travel-time residuals. This option sets the weight for these equations. If two values are given, they are for the first and last iterations, with interpolation in between. Default is 0.3.

profile.$name.solver.xcorrWeightScaler
    Type: double

    Weight scaling factor for equations that use cross-correlation differential times relative to equations that use only differential pick times. For example, a value of 2 means they are weighted twice as much Default is 2.0.

profile.$name.solver.usePickUncertainties
    Type: boolean

    Whether to use pick time uncertainty to weigh each pick according to 'pickUncertaintyClasses'. If enabled, each double-difference equation weight will be the average of its constituent pick weights. Default is false.

COMMAND LINE

  Generic

  Verbosity

  Messaging

--test
    Test mode, no messages are sent when relocating a single event

  Database

  Records

  Mode

--reloc-catalog profile
    Relocate the catalog passed as argument in multi-event mode. The input can be a single file (containing seiscomp origin ids) or a file triplet (station.csv,event.csv,phase.csv). For input events stored in a XML files add the --ep option. Use in combination with --profile.

-O, --origin-id origin-id
    Relocate the origin (or multiple comma-separated origins) in single-event mode and send a message. Each origin will be processed accordingly to the matching profile region unless the --profile option is used.

--ep scxml-file
    Relocate contained origins in single-event mode, unless --reloc-catalog is provided. In single-event mode, each origin will be processed accordingly to the matching profile region unless the --profile option is used. Together with --reloc-catalog option, the parameters XML file is used to fetch the input catalog data.

--dump-clusters profile
    Find clusters in the catalog passed as argument and save them in the working directory. The catalog can be a single file (containing seiscomp origin ids) or a file triplet (station.csv,event.csv,phase.csv). Use in combination with --profile.

--dump-wf profile
    Dump processed waveforms of the catalog passed as argument in the current working directory. The catalog can be a single file (containing seiscomp origin ids) or a file triplet (station.csv,event.csv,phase.csv). Use in combination with --profile.

--load-profile-wf profile
    Load catalog waveforms from the configured recordstream and save them into the profile cache directory. Use in combination with --profile.

--send-reload-profile-msg
    Send a message to any running scrtdd module requesting to reload a specific profile passed as argument. Useful to reload the catalog without restarting the module.

  ModeOptions

--profile profile
    To be used in combination with other options: select the profile configuration to use.

--clusters clusters
    Specify a list of files containing precomputed events/phases pairs. Use in combination with --reloc-catalog.

--xcorr-cache xcorr.csv
    Specify a file containing precomputed cross-correlation values. Use in combination with --reloc-catalog.

--xmlout
    Enable XML output when combined with --reloc-catalog or --origin-id options.

--dump-diagnostics
    Generate a diagnostics report by creating a dedicated folder in the current directory containing detailed relocation diagnostic data.

  Catalog

--dump-catalog catalog-file
    Dump the seiscomp event/origin id file passed as argument into a catalog file triplet (station.csv,event.csv,phase.csv).

--merge-catalogs catalog-files
    Merge in a single catalog all the catalog file triplets (station1.csv,event1.csv,phase1.csv,station2.csv,event2.csv, phase2.csv,...) passed as arguments.

--merge-catalogs-keepid catalog-files
    Similar to the --merge-catalogs option but events keep their ids. If multiple events share the same id, subsequent events will be discarded.

AUTHOR
GFZ Potsdam

COPYRIGHT
2020, SED