AlignToCoord

class of dascore.proc.align
inherits from: PatchProcessor, DascoreBaseModel, pydantic.main.BaseModel

AlignToCoord(
    *args ,
    mode: Any = same,
    samples: Any = False,
    reverse: Any = False,
    fill_value: Any = nan,
    **kwargs ,
)-> None

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.

Methods

Name	Description
check	Refuse a patch which does not carry what the operation needs.
get_metadata	Return the aligned coordinates, and where each trace moves from and to.
model_copy	Copy the model, dropping cached values the update invalidates.
new	Create new instance with some attributed updated.
numpy_kernel	Return the traces shifted into a new array of the fill value.
align_to_coord	Align (shift) patch dim(s) based on values in a non-dimension coordinate.
reconcile	Return metadata or a patch holding the final data; default as is.
run	Run the operation: check, get_metadata, kernel, reconcile, record.