ultrasound_metrics.metrics.clip

Measure signal-clipping in ultrasound pulse-echo data (RF or I/Q).

Uses time-domain amplitude thresholding.

Attributes

Scalar

Classes

ClipDetectMethod

Enum for different clipping metrics.

Functions

clip_ratio(→ float)	Measure the ratio of clipped samples in the data.
is_clipped_max_amplitude(...)	Detect clipped samples in the data by checking for contiguous segments outside the normal range.
is_clipped_threshold(→ jaxtyping.Bool[jaxtyping.Array, ...)	Detect clipped samples in the data by comparing to a threshold.

Module Contents

class ultrasound_metrics.metrics.clip.ClipDetectMethod

Bases: str, enum.Enum

Enum for different clipping metrics.

Initialize self. See help(type(self)) for accurate signature.

MAX_AMPLITUDE = 'max_amplitude'

THRESHOLD = 'threshold'

ultrasound_metrics.metrics.clip.clip_ratio(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], method: Union[ClipDetectMethod, str] = ClipDetectMethod.THRESHOLD, **kwargs: Any) → float

Measure the ratio of clipped samples in the data.

Supports multiple methods for clipping detection.

Parameters:

• data – Data array of shape (…, n_samples).

• method – Method to use for clipping detection.

• **kwargs – Additional keyword arguments for the clipping detection method.

Returns:

Ratio of clipped samples in the data.

Return type:

float

ultrasound_metrics.metrics.clip.is_clipped_max_amplitude(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], *, range_factor: Union[Scalar, tuple[Optional[Scalar], Optional[Scalar]]] = 0.01, min_contiguous: int = 1) → jaxtyping.Bool[jaxtyping.Array,  *batch sample]

Detect clipped samples in the data by checking for contiguous segments outside the normal range.

Implementation note: allows for a different threshold for each time-series in the batch.

Parameters:

• data – Data array of shape (…, n_samples).

• range_factor –

  How far inside the data’s min/max range to consider as clipping. Can be either:

  • float: symmetric factor for real data (e.g., 0.01 means within ±1% of the data range). For complex data, this is the factor for the magnitude range.

  • tuple: (lower, upper) factors for asymmetric thresholds

  • None for either value in the tuple to disable clipping detection on that side

  Use range_factor when clipping is soft, or when there is some preprocessing (such as filtering or lossy compression) that softens hard-clipping.

• min_contiguous – Minimum number of contiguous samples outside the range to consider that the signal was clipped. This is for guessing whether the signal was clipped, rather than just that the actual signal amplitude has some range.

Returns:

Boolean mask with shape=data.shape indicating which samples were clipped.

Return type:

ndarray

ultrasound_metrics.metrics.clip.is_clipped_threshold(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], *, max_threshold: float, min_threshold: Optional[float] = None) → jaxtyping.Bool[jaxtyping.Array,  *batch sample]

Detect clipped samples in the data by comparing to a threshold.

Parameters:

• data – Data array of shape (…, n_samples).

• max_threshold – Maximum allowed amplitude.

• min_threshold – Minimum allowed amplitude. If None, symmetric threshold is assumed.

Returns:

Boolean mask with shape=data.shape indicating which samples were clipped.

Return type:

ndarray

ultrasound_metrics.metrics.clip.Scalar