Normalize

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

source

Normalize(
    *args ,
    dim: str ,
    norm: str = l2,
    window: Any | None[Any, None] = None,
    samples: bool = False,
)-> None

Normalize a patch along a specified dimension.

By default each slice along dim is divided by a single norm of that whole slice. Giving a window divides each sample by the norm of a window centered on it instead, which is automatic gain control: late, weak arrivals come up to the amplitude of early, strong ones.

NaN values are ignored when computing the norm. They remain NaN in the output but do not affect any other sample. Slices, or windows, with a norm of zero – meaning they contain nothing but zeros and NaN – are returned unscaled.

Parameters

Parameter	Description
dim	The dimension along which the normalization takes place.
norm	Divisor: axis L1 norm ("l1"), L2 norm ("l2"), maximum absolute value ("max"), or sample magnitude ("bit").
window	Moving-window length, in units of dim unless samples is True. The window is centered on the sample it scales and is reflected where it runs off either end of dim, so every sample is scaled. If None, the whole slice is one window. Not supported for norm="bit", which is already a sample-by-sample operation.
samples	If True, the values in kwargs and step represent samples along a dimension. Must be integers. Otherwise, values are assumed to have same units as the specified dimension, or have units attached.

Note

Even window lengths in coordinate units are raised to the next odd number; with samples=True, an even sample count raises ParameterError. Reflection gives every input sample an output without introducing new nulls, unlike rolling, which leaves incomplete windows null.

Windowed L2 and L1 norms use RMS and mean absolute value, respectively, so scale does not depend on window length. Whole-slice L2 and L1 retain their established sum-based definitions.

Examples

import dascore as dc
patch = dc.get_example_patch()
l2_norm = patch.normalize(dim="time", norm="l2")
max_norm = patch.normalize(dim="distance", norm="max")
bit_norm = patch.normalize(dim="time", norm="bit")

# Automatic gain control: divide by the RMS of a 1 second window.
agc = patch.normalize(dim="time", norm="l2", window=1)
agc = patch.normalize(dim="time", norm="l2", window=251, samples=True)

Methods

Name	Description
check	Refuse a patch which does not carry what the operation needs.
derive	Return the result’s metadata, as a patch without data.
kernel	Return the data with each slice, or window, divided by its norm.
new	Create new instance with some attributed updated.
normalize	Normalize a patch along a specified dimension.
plan	Return the axis, and the window in samples when one is given.
reconcile	Return the result’s metadata once the data are known; default as is.
run	Run the operation: check, derive, plan, kernel, reconcile, record.