align_to_coord

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

Align patches based on values in a non-dimension coordinate.

Parameters

Parameter	Description
mode : str	Determines the output shape of the patch. Options are: “full” - Regardless of shift, all original data are preserved. This can result in patches with many fill values along the aligned dimension. “same” - The patch will retain its shape, however, only one trace (and traces that weren’t shifted) will remain complete. Parts of shifted traces will be discarded. “valid” - The output patch will likely be smaller than the input patch, as only completely overlapped valid data are kept. This means no fill_values will occur in the patch.
relative	If True, the values in the alignment coordinate specify offsets from the original start position (in the dimension’s units). If False and samples is False (absolute mode), the values specify the exact absolute positions where each trace should start.
samples	If True, the values in the alignment coordinate specify offsets in sample counts from the original start position. If False and relative is False (absolute mode), the values specify exact absolute positions in the dimension’s units.
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 a smaller subset for examples
patch = patch.select(distance=(0, 50))

# Example 1: Absolute mode - align traces to specific times
# Each trace will start at the specified absolute time value
time = patch.get_coord("time")
distance = patch.get_array("distance")
# Specify exact start times for each trace (as datetime64)
dt = np.timedelta64(1, 'ms')  # 1 millisecond
start_times = time.min() + np.arange(len(distance)) * dt
patch_abs = patch.update_coords(abs_times=("distance", start_times))
# Traces will now start at specified absolute times
aligned_abs = patch_abs.align_to_coord(time="abs_times", mode="full")

# Example 2: Round-trip alignment with reverse parameter
shifts = np.arange(len(distance))  # shifts in samples
patch_shift = patch.update_coords(my_shifts=("distance", shifts))
# Forward alignment
aligned = patch_shift.align_to_coord(
    time="my_shifts", samples=True, mode="full"
)
# Reverse to get back original (after dropping NaN padding)
reversed_patch = aligned.align_to_coord(
    time="my_shifts", samples=True, mode="full", reverse=True
)
original = reversed_patch.dropna("time")
assert original.equals(patch_shift)

# Example 3: Use 'valid' mode to extract only overlapping region
valid_aligned = patch_shift.align_to_coord(
    time="my_shifts", samples=True, mode="valid"
)
# Result contains no NaN values, only the overlapping data
assert not np.isnan(valid_aligned.data).any()

Note

**Alignment Meaning

The relative and samples parameters control how shift values are interpreted:

Absolute mode (relative=False, samples=False): Shift coordinate values specify the exact absolute position where each trace should start. For example, if the shift coordinate contains [2.0, 2.5, 3.0], traces will start at times 2.0, 2.5, and 3.0 respectively.
Relative mode (relative=True): Shift coordinate values specify offsets from the original start position in the dimension’s units. For example, if the original start is 0.0 and shifts are [0.0, 0.5, 1.0], traces will start at 0.0, 0.5, and 1.0.
Samples mode (samples=True): Shift coordinate values specify offsets in sample counts. For example, shifts of [0, 1, 2] with step=0.1 will offset traces by 0, 0.1, and 0.2 in the dimension’s units.

Mode Parameter:

To understand the mode argument, consider a 2D patch with two traces, an alignment dimension length of 10, and a relative shift of 5 samples. For mode==“full” the output looks like this: —–aaaaaaaaaa bbbbbbbbbb—– For mode==“same” the patch will look like this: aaaaaaaaaa bbbbb—– For mode==“valid”: aaaaa bbbbb where a and b represent values in first and second trace, respectively, and the - represents the fill values.