.. _xcorr-event-label:

Cross-correlation
=================

The purpose of the cross-correlation is to refine the exact time difference between two picks at a common station of an event pair, which allows for higher resolution event (re)locations. This time difference becomes the observed differential time part of a double-difference (see :ref:`multi-event-relocation-process-label`). When the cross-correlation is disabled or the correlation coefficient is below the configured threshold then the observed differential times are derived from the phase times (difference of their absolute travel times). 

The cross-correlation step is optional due to the expensive computation time. The improvement in hypocenter solution quality doesn't always improve drammatically, so we suggest to enable it only after the other parameters of rtDD have been optimized. The cross-correlation can be disabled by setting the ``crossCorrelation.maxStationDistance`` and/or ``crossCorrelation.maxInterEventDistance`` to 0. The cross-correlation is also skipped if the ``RecordStream`` parameter is not properly configured, because the waveform data will not be available.

------------------
Eval-xcorr command
------------------

The ``--eval-xcorr`` option should be used to properly configure the cross-correlation parameters. The optimization process involves running ``--eval-xcorr`` with different configuration and analyzes the results. The goal is to have as many matches as possible (increase correlation coefficient) avoiding bad/false matches (``lag`` values higher than the expected pick time uncertainty are probably an indication of false matches): this is a trade-off.

Example of ``--eval-xcorr`` command::

    scrtdd --eval-xcorr station.csv,event.csv,phase.csv --profile myProfile --verbosity=3 --console=1

Example output::

    [...]
    ---FINAL STATS--
    Total xcorr P phases   #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
                         41877   61126  0.77 (0.10)    0.77 (0.10)      -0 ( 36)        -0 ( 15)
    Total xcorr S phases   #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
                         30730   66292  0.85 (0.06)    0.85 (0.06)      -1 ( 42)        -0 ( 28)
    Xcorr P phases by inter-event distance in 0.10 km step
     EvDist [km]           #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
     0.00-0.10            4764    4508  0.82 (0.10)    0.84 (0.09)       0 ( 28)        -0 ( 11)
     0.10-0.20           13906   18615  0.78 (0.10)    0.78 (0.10)       0 ( 32)         0 ( 14)
     0.20-0.30           13633   21365  0.76 (0.10)    0.76 (0.09)      -1 ( 41)         0 ( 17)
     0.30-0.40            5445    9591  0.75 (0.09)    0.75 (0.09)      -5 ( 44)        -1 ( 20)
     0.40-0.50            2360    3807  0.75 (0.10)    0.75 (0.09)       5 ( 40)         1 ( 18)
     0.50-0.60            1010    1727  0.75 (0.10)    0.75 (0.10)       9 ( 35)         3 ( 14)
     0.60-0.70             553    1114  0.75 (0.10)    0.73 (0.10)       3 ( 37)         1 ( 14)
     0.70-0.80             142     247  0.74 (0.11)    0.70 (0.09)      20 ( 37)         4 ( 10)
     0.80-0.90              60     142  0.76 (0.12)    0.77 (0.13)      14 ( 36)         2 ( 10)
     0.90-1.00               4      10  0.79 (0.11)    0.80 (0.10)      25 ( 28)         7 (  1)
    Xcorr S phases by inter-event distance in 0.10 km step
     EvDist [km]           #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
     0.00-0.10            4024    4472  0.89 (0.06)    0.91 (0.05)      -0 ( 37)         0 ( 25)
     0.10-0.20           10521   20221  0.85 (0.06)    0.86 (0.06)       0 ( 40)        -0 ( 28)
     0.20-0.30            9961   23181  0.84 (0.06)    0.84 (0.05)      -0 ( 45)        -0 ( 31)
     0.30-0.40            3802   10307  0.83 (0.06)    0.83 (0.05)      -7 ( 47)        -4 ( 30)
     0.40-0.50            1430    4307  0.83 (0.06)    0.83 (0.05)       0 ( 43)        -0 ( 28)
     0.50-0.60             572    2002  0.83 (0.05)    0.83 (0.05)      16 ( 40)        10 ( 30)
     0.60-0.70             327    1357  0.83 (0.05)    0.83 (0.05)      -7 ( 42)        -7 ( 30)
     0.70-0.80              64     287  0.82 (0.05)    0.84 (0.04)       4 ( 33)         2 ( 24)
     0.80-0.90              26     150  0.83 (0.05)    0.84 (0.05)      13 ( 45)        -3 ( 26)
     0.90-1.00               3       8  0.80 (0.05)    0.83 (0.03)       9 (  8)        14 (  2)
    XCorr P phases by event to station distance in 3.00 km step
    StaDist [km]           #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
      3-6                   22      17  0.64 (0.04)    0.64 (0.04)      19 ( 23)         6 (  8)
      6-9                13487   12847  0.77 (0.11)    0.77 (0.11)       0 ( 26)         0 (  9)
      9-12                7942    9451  0.79 (0.11)    0.81 (0.11)      -1 ( 21)         0 (  9)
     12-15                7238   11380  0.73 (0.09)    0.72 (0.08)      -0 ( 31)         0 ( 18)
     15-18                 994     679  0.76 (0.07)    0.76 (0.07)      -5 ( 64)        -2 ( 36)
     18-21                3067    4218  0.78 (0.08)    0.79 (0.07)      -1 ( 35)        -0 ( 21)
     21-24                1318    5599  0.73 (0.10)    0.73 (0.09)       2 ( 90)         2 ( 66)
    [...]
    XCorr S phases by event to station distance in 3.00 km step
    StaDist [km]           #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
      3-6                   35       5  0.89 (0.04)    0.89 (0.04)      -5 ( 16)        -3 ( 14)
      6-9                 8307   14072  0.87 (0.06)    0.88 (0.05)       0 ( 28)         0 ( 22)
      9-12                7740   13058  0.84 (0.06)    0.84 (0.05)      -0 ( 44)        -0 ( 33)
     12-15                3384   10766  0.83 (0.06)    0.83 (0.05)      -1 ( 36)         0 ( 21)
     15-18                1207    1849  0.83 (0.06)    0.83 (0.05)       1 ( 52)         1 ( 37)
     18-21                 527    2601  0.82 (0.07)    0.81 (0.06)      -0 ( 54)         2 ( 39)
     21-24                2411    7921  0.82 (0.06)    0.81 (0.05)      -1 ( 48)        -2 ( 36)
    [...]
    XCorr P phases by station
    Station                #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
    8D.RAW1.              4254    5109  0.75 (0.09)    0.74 (0.09)      -0 ( 35)         1 ( 26)
    8D.RAW2.              6436    4086  0.75 (0.10)    0.74 (0.09)       0 ( 22)         0 ( 10)
    8D.RAW4.              2902    3045  0.79 (0.08)    0.79 (0.07)      -0 ( 30)         0 ( 20)
    C4.CERNS.                0       0  0.00 (0.00)    0.00 (0.00)       0 (  0)         0 (  0)
    CH.AIGLE.               41     211  0.80 (0.08)    0.84 (0.06)      -6 ( 78)         1 ( 31)
    CH.DIX.                687    5012  0.75 (0.09)    0.75 (0.08)       1 ( 48)         0 ( 21)
    [...]
    XCorr S phases by station
    Station                #CC   #Skip meanCC (MAD) medianCC (MAD) meanLag (MAD) medianLag (MAD)
    8D.RAW1.              2539    7670  0.83 (0.06)    0.83 (0.05)      -0 ( 25)        -0 ( 16)
    8D.RAW2.              6861    3732  0.88 (0.06)    0.89 (0.05)      -0 ( 28)         0 ( 23)
    8D.RAW4.                79     838  0.86 (0.06)    0.87 (0.06)      -5 ( 32)        -5 ( 27)
    CH.AIGLE.              113     288  0.82 (0.04)    0.82 (0.04)      -1 ( 85)        -5 ( 82)
    CH.DIX.               2394    2606  0.84 (0.06)    0.85 (0.05)       1 ( 35)         0 ( 22)
    [...]


* ``#CC``: number of cross-correlations performed
* ``#Skip``: number of cross-correlations whose results do not account for the computation of the statistics
* ``coeff``: correlation coefficient between phase waveforms 
* ``lag``: cross-correlation lag between phase waveforms in milliseconds

There could be several reasons why the cross-correlation between 2 phase waveforms is not considered for computing the statistics: the correlation coefficient is below the configured threshold (see ``crossCorrelation.x-phase.minCCCoef``), the SNR of one or both the waveforms is below the configured threshold (see ``crossCorrelation.snr.minSnr``), the waveform data for one or both the phases is not available and in general when the it is not possible to perform the cross-correlation. It is possible to know the exact reason by looking at the logs at debug level (--verbosity=4).

The SNR is particularly important to reject bad automatic picks or picks detected via cross-correlation (see :ref:`phase-update-label`), but but it is not so relevant when relocating manually reviewed origins since the picks are checked already and bad ones discarded.


.. _reusing-xcorr-label:

---------------------------------
Reusing cross-correlation results
---------------------------------

When cross-correlation settings are not changed, it might be useful to reuse the cross-correlation results to save processing time. Both the ``--eval-xcorr`` and ``--reloc-catalog`` options save a ``xcorr.csv`` file after finishing their execution (thay overwrite it if already present!). That file contains the computed cross-correlation results and can be given back to rtDD via the command line option ``--xcorr-cache``. It is safe to change the value of ``crossCorrelation.x-phase.minCCCoef`` and reuse the cross-correlation results to see how performance change at varying correlation coefficient threshold.

--------------------
Waveforms inspection
--------------------

The ``--dump-wf`` option will make rtDD dump to disk the waveforms of the catalog passed as argument. Those files are in miniseed format and can be viewed with an external tool (e.g. ``scrttv waveform.mseed``) or obspy). The waveforms are written to disk after the filtering and resampling have been applied::

    scrtdd --help
      --dump-wf arg                         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.


e.g.::

    scrtdd --dump-wf station.csv,event.csv,phase.csv --profile myProfile --verbosity=3 --console=1
    
    17:59:28 [info] Writing ev1.8D.RAW2..HHT.Sg.manual.mseed
    17:59:28 [info] Writing ev1.CH.SAYF2..HGT.Sg.manual.mseed
    17:59:28 [info] Writing ev1.CH.SENIN..HHT.Sg.manual.mseed
    17:59:28 [info] Writing ev1.XY.LEO01..HHT.Sg.manual.mseed
    17:59:28 [info] Writing ev1.XY.LEO01..HHZ.Sg.manual.mseed
    17:59:28 [info] Writing ev1.FR.OGSI.00.HHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev1.GU.REMY..HHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev1.CH.FIESA..HHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev1.CH.TORNY..HHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev1.8D.AMIDI..EHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev2.CH.DIX..HHT.Sg.manual.mseed
    17:59:28 [info] Writing ev2.8D.RAW2..HHZ.Pg.manual.mseed
    17:59:28 [info] Writing ev2.CH.SAYF2..HGZ.Pg.manual.mseed
    17:59:28 [info] Writing ev2.CH.STSW2..HGZ.Pg.manual.mseed
    [...]

