correlate

correlate(
    patch: Patch ,
    samples: bool = False,
    **kwargs ,
)-> ‘PatchType’

Correlate source row/columns in a 2D 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 2D input becomes 3D, with one new source dimension; Patch.squeeze removes it for a single source.

Parameters

Parameter	Description
patch	Two-dimensional patch in the original or frequency domain.
samples	Interpret source selectors as sample indices rather than coordinate values.
**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))
)

# 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")

Note

Correlation runs along the dimension not named in kwargs. That dimension becomes a lag dimension prefixed with lag_; for example, selecting a distance source transforms time into lag_time.