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")correlate
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 dimensionsmust 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 bothmust share with the same step but may differ in length. Other dimensions broadcast and align as in patch * other, so atemplate with only lag_dim is matched against every trace.lag_dim is required unless the patch is 1D. Lags, inlag_dim’s units, cover -(len(other) - 1) tolen(patch) - 1 steps, plus a few zeros from padding to a fastlength; 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 combinedwith sources, or with a patch transformed along lag_dim.
|
| **kwargs | Source dimension mapped to one or more source values or indices. |
Examples
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.