align_to_coord

function of dascore.proc.align source

align_to_coord(
    patch: Patch ,
    mode: Literal[‘full’, ‘valid’, ‘same’] = same,
    samples: bool = False,
    reverse: bool = False,
    fill_value: float = nan,
    **kwargs ,
)-> ‘PatchType’

Align (shift) patch dim(s) based on values in a non-dimension coordinate.

In the DAS context, this can be useful to time shift data from all channels varying amounts. The specified coordinate must indicate a shift relative to the current positions.

Parameters

Parameter Description
patch The patch to align.
mode : str Output extent: "full" preserves all data with fill as needed,
"same" preserves the input shape and trims shifted edges, and
"valid" keeps only the region shared by every shifted trace.
samples If True, the values in the alignment coordinate specify integer sample
offsets from the original start position. If False, the values specify
value offsets (such as timedelta64) relative to the start of the aligned
dimension.
reverse If True, multiply the alignment coordinate values by -1 to reverse
a previous alignment operation.
fill_value The value to insert in areas lacking data.
**kwargs Used to specify the dimension which should shift and the coordinate
to shift it to. The shift coordinate should not depend on the
specified dimension.

Returns

A patch with aligned coordinates.

Examples

import dascore as dc
import numpy as np
patch = dc.get_example_patch().select(distance=(0, 50))
distance = patch.get_array("distance")
start_times = np.arange(len(distance)) * np.timedelta64(1, "ms")
patch_shift = patch.update_coords(shift_times=("distance", start_times))
aligned_offsets = patch_shift.align_to_coord(time="shift_times", mode="full")

# Align by samples and reverse the operation.
shifts = np.arange(len(distance))
patch_shift = patch.update_coords(my_shifts=("distance", shifts))
aligned = patch_shift.align_to_coord(
    time="my_shifts", samples=True, mode="full"
)
reversed_patch = aligned.align_to_coord(
    time="my_shifts", samples=True, mode="full", reverse=True
)
assert reversed_patch.dropna("time").equals(patch_shift)

valid_aligned = patch_shift.align_to_coord(
    time="my_shifts", samples=True, mode="valid"
)
assert not np.isnan(valid_aligned.data).any()
Note

For two length-10 traces separated by five samples, the modes produce:

full                 same          valid
-----aaaaaaaaaa      aaaaaaaaaa    aaaaa
bbbbbbbbbb-----      bbbbb-----    bbbbb

Letters represent data and dashes represent fill values.