Patch

class of dascore.core.patch
inherits from: NamespaceOwner, PatchMeta, NodeRepr, RichRepr

Patch(
    data: ndarray = None,
    coords: CoordManager = None,
    dims: tuple[str, …] = None,
    attrs: PatchAttrs = None,
    dtype: Any = None,
    source = None,
)

A Class for managing data and metadata.

See the patch tutorial for examples.

Parameters

Parameter	Description
data	The array data representing fiber optic measurements. A Patch or xarray DataArray supplies its own coords and attrs.
coords	The coordinates, or dimensional labels for the data. A few types of input are permitted. If a mapping (eg dict) the value should conform to one of the following three forms: {coord_name: coord} {coord_name: ((dimensions,), coord)} {coord_name: (dimensions, coord)} Where coord can be a numpy array or a `BaseCoord` object. A `CoordManager` is also acceptable.
dims	A sequence of dimension strings. The first entry corresponds to the first axis of data, the second to the second dimension, and so on.
attrs	Optional attributes (non-coordinate metadata) passed as a dict or PatchAttrs
dtype	Optional. When given, the data are refused unless that is what they hold; a patch’s dtype is always its data’s.

source	Internal source metadata supplied by the I/O framework.

Note

Coordinates are owned by the patch/coord manager, not by attrs. Use Patch.summary when you need a combined view of attrs plus coordinate summary metadata.

Coords and a dtype describe data without holding any, which is a PatchMeta; see drop_data.

NumPy ufuncs and most NumPy functions take patches and return patches, with coordinates following the data:

Reductions such as np.mean(patch, axis=1) keep the reduced dimension at length one, with or without keepdims.
np.transpose, np.swapaxes, np.squeeze and the np.flip family call the matching patch methods.
np.diff labels each difference with the midpoint of its two samples, drops coordinates that depend on that dimension, and refuses prepend and append.
np.gradient returns one patch per axis.
np.sort, np.argsort, np.partition and numpy.fft functions raise a ParameterError; apply them to patch.data, or use dft.

Methods

Name	Description
abs	Take the absolute value of the patch data.
adaptive_spectral_filter	Suppress energy which is not coherent within a window: the AFK filter.
add_distance_to	Calculate the distance to “origin” and create new coordinate.
aggregate	Aggregate values along a specified dimension.
align_to_coord	Align (shift) patch dim(s) based on values in a non-dimension coordinate.
all	Perform boolean all operation along one or more dimensions.
angle	Return a new patch with the phase angles from the data array.
any	Perform boolean any operation along one or more dimensions.
append_dims	Insert dimensions at the end of the patch.
apply_ufunc	Apply a ufunc with the patch as its first operand.
check_patch_attrs	Check for expected attributes.
check_patch_coords	Check that a patch has the required coordinates, else raise.
conj	Apply the complex conjugate of the patch data.
convert_units	Convert the patch data or coordinate units.
coords_from_df	Update non-dimensional coordinate of a patch using a dataframe.
correlate	Correlate source row/columns in a 2D patch with all other row/columns.
correlate_shift	Apply a shift to the patch data to undo correlation in frequency domain.
decimate	Decimate a patch along a dimension.
demean	Remove the mean along a given dimension of a DASCore patch.
demedian	Remove the median along a given dimension of a DASCore patch.
detrend	Remove a constant or linear trend from the data along one dimension.
dft	Perform the discrete Fourier transform (dft) on specified dimension(s).
differentiate	Calculate first derivative along dimension(s) using central differences.
dispersion_phase_shift	Compute dispersion images using the phase-shift method.
drop_coords	Drop one or more non-dimensional coordinates.
drop_data	Return this patch’s metadata, without its data.
drop_private_coords	Drop all private coords in the patch.
dropna	Return a patch with nullish values dropped along dimension.
enrich	Copy inventory metadata onto a patch.
envelope	Calculate the envelope of a signal using the Hilbert transform.
equals	Determine if the current patch equals another.
fbe	Compute the rolling Frequency Band Energy in a window.
fill_gaps	Fill the holes along a dimension with a constant value.
fillna	Return a patch with nullish values replaced by a value.
first	Get the first value along one or more dimensions.
flat_dump	Return a flat summary dict for dataframe-oriented helpers.
flip	Flip patch data and (optionally coords) along specified dimensions.
full	Return an identical patch with the data replaced by fill_value.
gaussian_filter	Applies a Gaussian filter along specified dimensions.
get_array	Get an array associated with patch data or a coordinate.
get_axis	Get the axis corresponding to a Patch dimension. Raise error if not found.
get_coord	Get a managed coordinate from the patch.
get_patch_name	Return the name of the patch.
get_patch_names	Generates the default name of patch data.
hampel_filter	A Hampel filter implementation useful for removing spikes in data.
hilbert	Perform a Hilbert transform on a patch.
idft	Perform the inverse discrete Fourier transform (idft) on specified dimension(s).
idxmax	Return the coordinate value where the data are largest along a dimension.
idxmin	Return the coordinate value where the data are smallest along a dimension.
imag	Return a new patch with the imaginary part of the data array.
integrate	Integrate along a specified dimension using composite trapezoidal rule.
interpolate	Set coordinates of patch along a dimension using interpolation.
isel	Select sample positions with xarray-compatible dimension indexing.
istft	Invert a short-time fourier transform.
kurtosis	Compute kurtosis along a patch dimension.
last	Get the last value along one or more dimensions.
line_mute	Mute (zero out) data in a region specified by one or more lines.
load	Return the patch with its data read into memory, keeping its id.
make_broadcastable_to	Stretch a patch until it broadcasts against a shape.
max	Calculate the maximum along one or more dimensions.
mean	Calculate the mean along one or more dimensions.
median	Calculate the median along one or more dimensions.
median_filter	Apply 2-D median filter.
median_frequency	Compute the median frequency of a Fourier-domain patch.
min	Calculate the minimum along one or more dimensions.
update	Return a copy of the Patch with replaced data, coords, dims, or attrs.
normalize	Normalize a patch along a specified dimension.
notch_filter	Apply a second-order IIR notch digital filter on patch’s data.
order	Re-order the patch contents based on coordinate values or indices.
pad	Pad the patch data along specified dimensions.
pass_filter	Apply a Butterworth pass filter (bandpass, highpass, or lowpass).
phase_weighted_stack	Apply phase weighted stacking to enhance coherent signals.
pin_id	Return the patch with a `data_id` hashed from the data it holds.
pipe	Pipe the patch to a function.
pow_coord	Scale the data by coordinate values raised to a power.
radians_to_strain	Convert data in radians to strain (rate).
real	Return a new patch with the real part of the data array.
reassemble	Blend a stack of tiles back into the patch they were cut from.
rename_coords	Rename coordinate of Patch.
resample	Resample along a single dimension using Fourier Method and interpolation.
roll	Roll patch array elements along a given dimension.
rolling	Apply a rolling function along a specified dimension.
savgol_filter	Applies Savgol filter along specified dimensions.
sel	Select coordinate labels with xarray-compatible dimension indexing.
select	Return a subset of the patch.
set_dims	Set dimension to non-dimensional coordinate.
set_units	Set the units of a patch’s data or coordinates.
simplify_units	Simplify the units contained by the patch to base metric units.
slope_filter	Filter the patch over certain slopes in the 2D Fourier domain.
slope_mute	Apply a mute between specified slopes (eg velocities).
snap_coords	Snap coordinates to evenly spaced samples.
sobel_filter	Estimate the gradient along one dimension with a Sobel operator.
sort_coords	Sort one or more coordinates.
spectral_centroid	Compute the spectral centroid of a Fourier-domain patch.
spectral_entropy	Compute spectral entropy from a Fourier-domain patch.
spectral_flatness	Compute spectral flatness from a Fourier-domain patch.
spectral_kurtosis	Compute spectral kurtosis from a Fourier-domain patch.
spectral_peak_amplitude	Compute the peak spectral amplitude of a Fourier-domain patch.
spectral_peak_frequency	Compute the peak frequency of a Fourier-domain patch.
split_gaps	Split the patch into contiguous patches.
squeeze	Return a new object with len one dimensions flattened.
stalta	Compute the short-term / long-term average (STA/LTA) ratio along a patch dimension.
standardize	Standardize data by removing the mean and scaling to unit variance.
std	Calculate the standard deviation along one or more dimensions.
stft	Perform a short-time fourier transform.
sum	Sum the values along one or more dimensions.
taper	Taper the ends of the signal.
taper_range	Taper a range inside the patch.
tau_p	Compute linear tau-p transform.
tile_apply	Apply a function to overlapping windows of the patch.
to_patch	Return this patch holding `data` instead of its own.
transpose	Transpose the data array to any dimension order desired.
unselect	Return the patch outside a selection.
update_attrs	Update patch attrs and return a new Patch.
update_coords	Update the coordinates of a patch.
velocity_to_strain_rate	Convert velocity DAS data to strain rate using central differences.
velocity_to_strain_rate_edgeless	Estimate strain-rate using central differences.
where	Return elements from patch where condition is True, else fill with other.
whiten	Spectral whitening of a signal.
wiener_filter	Apply a Wiener filter to reduce noise in the patch data.