correlate

function of dascore.proc.correlate source

correlate(
    self ,
    samples: bool = False,
    lag_dim: str | None[str, None] = None,
    normalize: bool = False,
    other: dascore.core.patch.Patch | None[Patch, None] = None,
    **kwargs ,
)-> ‘Self’

Correlate source row/columns in a patch with all other row/columns.

The correlation runs in the frequency domain, transforming the target dimension when needed. For an already transformed patch, apply Patch.correlate_shift after the inverse transform. The output gains one new, last source dimension; Patch.squeeze removes it for a single source. Given other instead of sources, each trace is correlated with the matching trace of that patch, and no source dimension is added.

Parameters

Parameter Description
samples Interpret source selectors as sample indices rather than coordinate
values.
lag_dim The dimension to correlate along. A 2D patch defaults to the
dimension not named in kwargs; a patch with more dimensions
must name it, and every other dimension is correlated separately.
normalize If True, divide each correlation by sqrt(E_trace * E_source),
where E is the whole-trace energy (sum of squared magnitudes)
along lag_dim, so |cc| <= 1 and the result is dimensionless.
The mean is not removed, and the energies do not change with lag:
for traces with their mean removed, this equals the Pearson
coefficient only at zero lag. A trace with no energy gives zeros.
other A patch to correlate each trace with along lag_dim, which both
must share with the same step but may differ in length. Other
dimensions broadcast and align as in patch * other, so a
template with only lag_dim is matched against every trace.
lag_dim is required unless the patch is 1D. Lags, in
lag_dim’s units, cover -(len(other) - 1) to
len(patch) - 1 steps, plus a few zeros from padding to a fast
length; they are offsets from each patch’s first sample, so the
start times are ignored. A positive lag means the waveform appears
that much later in the patch than in other. Cannot be combined
with sources, or with a patch transformed along lag_dim.
**kwargs Source dimension mapped to one or more source values or indices.

Examples

import dascore as dc
from dascore.units import m
patch = dc.get_example_patch(
    "sin_wav",
    sample_rate=100,
    frequency=range(10, 20),
    duration=5,
    channel_count=10,
).taper(time=0.05).set_units(distance="m")

# Correlate every channel with the 10 m channel.
cc_patch = patch.correlate(distance=10 * m).squeeze()

# Keep -2 through 2 seconds of lag.
cc_patch = (
    patch.correlate(distance=10 * m)
    .select(lag_time=(-2, 2))
)

# Normalized correlation, keeping -0.5 through 0.5 seconds of lag.
cc_patch = patch.correlate(distance=10 * m, normalize=True).select(
    lag_time=(-0.5, 0.5)
)

# Select a source by sample index after decimation.
cc_patch = (
    patch.decimate(distance=2, filter_type=None)
    .correlate(distance=1, samples=True)
)

cc_patch = patch.correlate(time=100, samples=True)

# Correlate several sources in a frequency-domain pipeline.
padded_patch = patch.pad(time="correlate")
dft_patch = padded_patch.dft("time", real=True)
cc_patch = dft_patch.correlate(distance=[1, 3, 7], samples=True)
cc_out = cc_patch.idft().correlate_shift("time")

# Correlate along time separately for each source of a 3D patch.
import numpy as np
patch_3d = dc.Patch(
    data=np.random.rand(3, 2, 400),
    coords={"source": [0, 1, 2], "distance": [0.0, 1.0], "time": range(400)},
    dims=("source", "distance", "time"),
)
cc_patch = patch_3d.correlate(distance=0, samples=True, lag_dim="time")

# Match a half-second template from the 10 m channel to every channel.
template = patch.sel(distance=10).select(time=(1, 1.5), relative=True)
cc_patch = patch.correlate(other=template, lag_dim="time")
Note

The result’s data units are the square of the patch’s (for example (m/s)**2 for velocity), as each value is a sum of products of the data; with other they are the product of both patches’ units, and none when either has none. Single-precision data are correlated in single precision.

Correlation runs along lag_dim. That dimension becomes a lag dimension prefixed with lag_; for example, selecting a distance source transforms time into lag_time.