.. highlight:: rst .. _scrtdd: ###### scrtdd ###### **Double-difference earthquake relocation module.** Configuration ============= | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/scrtdd.cfg` | :file:`etc/global.cfg` | :file:`etc/scrtdd.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/scrtdd.cfg` scrtdd inherits `global options `_. .. confval:: automaticOrigins Type: *boolean* Allow relocation of automatic origins. Default is ``true``. .. confval:: manualOrigins Type: *boolean* Allow relocation of manual origins. Default is ``true``. .. confval:: 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``. .. confval:: 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. .. confval:: activeProfiles Type: *list:string* Defines a list of active profiles for single\-event \(real\-time\) processing. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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 :confval:`rtdd.activeProfiles` to become active. .. code-block:: sh 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 = ... .. confval:: profile.$name.regionType Type: *string* Type of region: RECTANGULAR or CIRCULAR. Default is ``CIRCULAR``. .. confval:: 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. .. confval:: profile.$name.methodID Type: *string* The methodID label to be stored in created origins. Default is ``RTDD``. .. confval:: profile.$name.tableType Type: *string* Travel\-time table format type \(e.g. homogeneous, NLLGrid, LOCSAT\). Default is ``LOCSAT``. .. confval:: profile.$name.tableModel Type: *string* The model to be used. The format depends on tableType. Default is ``iasp91``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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. .. confval:: 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. .. confval:: 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.* .. confval:: 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 .. confval:: profile.$name.catalog.phaFile Type: *path* Path to catalog picks file to be used for this profile .. confval:: 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).* .. confval:: 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``. .. confval:: 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.* .. confval:: 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``. .. confval:: 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. .. confval:: 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.* .. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.maxNumNeighbours Type: *int* Maximum number of neighbors per event. A value of 0 disables this limit. Default is ``80``. .. confval:: 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``. .. confval:: 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.* .. confval:: 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``. .. confval:: 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``. .. confval:: 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.* .. confval:: profile.$name.crossCorrelation.enable Type: *boolean* Enable or disable waveform cross\-correlation. Default is ``false``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: profile.$name.crossCorrelation.p-phase.maxDelay Type: *double* Unit: *sec* Maximum lag \(in seconds\) between data windows allowed. Default is ``0.50``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: profile.$name.crossCorrelation.s-phase.maxDelay Type: *double* Unit: *sec* Maximum lag \(in seconds\) between data windows allowed. Default is ``0.50``. .. confval:: 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.* .. confval:: 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. .. confval:: 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``. .. confval:: 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.* .. confval:: profile.$name.solver.solverType Type: *string* Solver algorithm to use: either LSMR or LSQR. Default is ``LSMR``. .. confval:: profile.$name.solver.algoIterations Type: *int* Number of iterations for the solver to perform. Default is ``20``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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``. .. confval:: 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 --------- .. option:: --test Test mode, no messages are sent when relocating a single event Database -------- Records ------- Mode ---- .. option:: --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. .. option:: -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. .. option:: --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. .. option:: --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. .. option:: --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. .. option:: --load-profile-wf profile Load catalog waveforms from the configured recordstream and save them into the profile cache directory. Use in combination with \-\-profile. .. option:: --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 ----------- .. option:: --profile profile To be used in combination with other options: select the profile configuration to use. .. option:: --clusters clusters Specify a list of files containing precomputed events\/phases pairs. Use in combination with \-\-reloc\-catalog. .. option:: --xcorr-cache xcorr.csv Specify a file containing precomputed cross\-correlation values. Use in combination with \-\-reloc\-catalog. .. option:: --xmlout Enable XML output when combined with \-\-reloc\-catalog or \-\-origin\-id options. .. option:: --dump-diagnostics Generate a diagnostics report by creating a dedicated folder in the current directory containing detailed relocation diagnostic data. Catalog ------- .. option:: --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\). .. option:: --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. .. option:: --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.