correlate

correlate(
    patch: Patch ,
    lag: int | float | pint.registry.Quantity | None[int, float, Quantity, None] = None,
    samples = False,
    **kwargs ,
)-> ‘PatchType’

Correlate a single row/column in a 2D patch with every other row/column.

Parameters

Parameter	Description
patch : PatchType	The input data patch to be cross-correlated. Must be 2-dimensional.
lag :	An optional argument to save only certain lag times instead of full output.
samples : bool, optional (default = False)	If True, the argument specified in kwargs refers to the sample not value along that axis. See examples for details.
**kwargs	Additional arguments to specify cross correlation dimension and the master source, to which we cross-correlate all other channels/time samples.

Examples

import dascore as dc
from dascore.units import m, s
patch = dc.get_example_patch()
# Example 1
# Calculate cc for all channels as receivers and
# the 10 m channel as the master channel. The new patch has dimensions
# (lag_time, distance)
cc_patch = patch.correlate(distance = 10 * m)
# Example 2
# Calculate cc within (-2,2) sec of lag for all channels as receivers and
# the 10 m channel as the master channel.
cc_patch = patch.correlate(distance = 10 * m, lag = 2 * s)
# Example 3
# Use 2nd channel (python is 0 indexed) along distance as master channel
cc_patch = patch.correlate(distance=1, samples=True)
# Example 4
# Correlate along time dimension
cc_patch = patch.correlate(time=100, samples=True)

Note

The cross-correlation is performed in the frequency domain for efficiency reasons.

The output dimension is opposite of the one specified in kwargs, has the units of float, and the string “lag_” prepended. For example, “lag_time”.