relmt.align module#

relmt.align.complete_paired_s_lag_times(evpairs, dd, cc, dd_res, method='median')[source]#

Pair-wise from triplet-wise lag times from complete set.

Compute pair-wise from the triplet-wise lag times dd returned by mccc_align(). Assume all combinations are present, i.e. npair = events * (events-1) * (events-2) / 3

Parameters:

  • ev_pair – (npair, 2) event indices

  • dd (ndarray) – Corresponding (npair,) pairwise differential arrival times

  • cc (ndarray) – (events, events, events) Cross correlation matrix

  • dd_res (ndarray) – (npair,) residuals of the alignment

  • method (str) –

    • ‘median’: take the median of the tripletwise lag times

    • ’residual’ choose the one with the lowest residual

    • ’cc’ choose the one with the highest cross-correlation coefficient

  • evpairs (ndarray)

Returns:

  • ev_pair (numpy.ndarray) – (events * (events-1) / 2, 2) event indices

  • dd_pair (numpy.ndarray) – Corresponding median differential arrival times

  • cc_pair (numpy.ndarray) – Corresponding average cross correlation coefficient

  • res_pair (numpy.ndarray) – Corresponding residuals of the differential arrival times. If ‘method’ is ‘median’, the RMS of all lag times

relmt.align.incomplete_paired_s_lag_times(evpairs, dd, cc, dd_res, combinations, method='cc')[source]#

Pair-wise from triplet-wise lag times from incomplete set.

Compute pair-wise from the triplet-wise lag times dd returned by mccc_align() with a combinations list parsed. Do not attempt to compute implicit combinations

Parameters:

  • evpairs (ndarray) – (npair, 2) event indices

  • dd (ndarray) – Corresponding pairwise differential arrival times

  • cc (ndarray) – (events, events, events) Cross correlation matrix

  • dd_res (ndarray) – (npair,) residuals of the alignment

  • combinations (ndarray) – (npair/2, 3) triplet combinations that form the incomplete observations

  • method (str) –

    • ‘residual’ choose the one with the lowest residual

    • ’cc’ choose the one with the highest cross-correlation coefficient

Returns:

  • ev_pair (numpy.ndarray) – (events * (events-1) / 2, 2) event indices

  • dd_pair (numpy.ndarray) – Corresponding median differential arrival times

  • cc_pair (numpy.ndarray) – Corresponding average cross correlation coefficient

  • res_pair (numpy.ndarray) – Corresponding residuals of the differential arrival times.

relmt.align.mccc_align(mtx, phase, sampling_rate, maxshift, ndec=1, combinations=array([], dtype=float64), do_scc=True, verbose=False)[source]#

Compute time shifts that align the seismogram matrix

Applies the multi-channel cross-correlation method (Bostock et al. 2021, BSSA)

Parameters:

  • mtx (ndarray) – Waveform matrix of shape (events, samples), with time aligned along last axis

  • phase (str) – Seismic phase (‘P’ or ‘S’)

  • sampling_rate (float) – Sampling rate of the wavefrom matrix (Hertz)

  • maxshift (float) – Maximum shift to test (seconds)

  • ndec (int) – Test correlation function at every ndec’th point

  • combinations (ndarray) – Only combine these indices of mtx. (combinations, 2) for P-waves, (combinations, 3) for S-waves. When empty, combine all events.

  • do_scc (bool) – Compute S-wave correlation coefficients. May be slow. Else, returned cc values are all zero

  • verbose (bool) – Print diagnostic output

Returns:

  • time_shifts (numpy.ndarray) – Zero-mean time shifts of shape (events,) that maximize cc

  • cc (numpy.ndarray) – Nominal correlation coefficients between events at optimal time lag

  • dd (numpy.ndarray) – Pairwise differential arrival times

  • dd_res (numpy.ndarray) – Resiudal when computing time lags from pairwise differential arrival times

  • pairs (numpy.ndarray) – Pairwise event combination indices pointing into mtx of shape (C,2), where C is events * (events-1) / 2 for P waves and events * (events-1) * (events-2)/ 3 for S waves

Raises:

  • IndexError: – When mtx contains less than 2 events for P waves, or less than 3 for S waves

  • ValueError: – When phase is not ‘P’ or ‘S’

relmt.align.pca_align(mtx, sampling_rate, phase, iterations=50, dphi=0, dtime=0)[source]#

Align waveforms by principal component analysis

Implements method of Bostock et al. (2021, BSSA).

For P-waves, we maximize the first of the singular values \(s\) of \(n\) waveforms:

\[\phi = s_0^2 / n\]

For S-waves, we maximize the sum of the first two singular values:

\[\phi = 1 - s_2 / (s_0 + s_1),\]

where \(\phi\) ranges from 0 (worst) to 1 (best)

Parameters:

  • mtx (ndarray) – Waveform matrix of shape (events, samples), with time aligned along last axis

  • sampling_rate (float) – Sampling rate of the wavefrom matrix (Hertz)

  • phase (str) – Which seismic phase to consider (‘P’ or ‘S’)

  • iterations (int) – Maximum number of iterations

  • dphi (float) – Minimum change in objective function to stop iteration

  • dtime (float) – Smallest maximal time shift to stop iteration

Returns:

  • time_shifts (numpy.ndarray) – Zero-mean time shifts of shape (events,) that maximize phi

  • phi (float) – Value of objective function

Raises:

  • IndexError: – When mtx contains less than 2 events for P waves, or less than 3 for S waves

  • ValueError: – When phase is not ‘P’ or ‘S’

relmt.align.pca_objective(sigma, phase, ns)[source]#

Principal component alignment objective function

for P phases:

\[\phi = s_0^2 / n\]

For S phases:

\[\phi = 1 - s_2 / (s_0 + s_1)\]
Parameters:

  • sigma (ndarray) – Singular value vector of the singular value decompostion

  • phase (str) – Seismic phase to consider. ‘P’ or ‘S’.

  • ns (int) – Number of seismograms

Returns:

float – The objective value

relmt.align.run(wvarr, header, destination, do_mccc=True, do_pca=True, mccc_combinations=array([], dtype=float64), lag_times=[])[source]#

Align waveforms and save results to disk

Parameters:

  • wvarr (ndarray) – (events, channels, samples) waveform array

  • header (Header) – Dictionary holding the processing parameters

  • destination (tuple[str, str, int, str]) – Tuple holding station name, phase type, alignment iteration number and destination root directory

  • do_mccc (bool) – Align using multi-channel cross correlation.

  • do_pca (bool) – Align using principal component analyses. This allows for sub-sample alignment, but impedes to combine cross correlation lag times of two successive runs.

  • mccc_combinations (ndarray) – When aligning using mccc, only combine these pairs (P-waves) or triplets (S-waves).

  • lag_times (list[str]) –

    MCCC lag times to save to file:

    • ”P”: P lag times

    • ”S-median”: median of S lag time triplets

    • ”S-residual”: S lag times with lowest residuals

    • ”S-cc”: S lag times with highest cross-correlation values

relmt.align.run_limited(*args)[source]#

Run the alignment with limited threadpool to avoid oversubscription

See run() for details on the arguments.