sidescanpy.processing.outliers

Median/MAD outlier rejection.

reject_range_outliers() drops samples far from their own range bin’s median. Meant for calibration-style fits that assume a flat, homogeneous bottom population (noise-floor and range-decay estimates), not for display or export: it deliberately discards genuine bright returns such as hard targets.

mask_bright_ping_rows() drops whole pings whose overall level is an outlier – the full-width bright streak a per-ping automatic gain jump leaves.

Contents

reject_range_outliers	Return a copy of values with per-range-bin outliers set to NaN.
mask_bright_ping_rows	NaN out whole ping rows whose typical level is an extreme outlier.

sidescanpy.processing.outliers.reject_range_outliers(values, ranges, *, bin_width_m=5.0, mad_k=3.5, min_bin_count=5)

Return a copy of values with per-range-bin outliers set to NaN.

Samples are grouped into bin_width_m range bins; within each bin a sample is rejected when its modified z-score 0.6745 * |value - median| / MAD exceeds mad_k. Median/MAD rather than mean/std, so the right-skewed backscatter distribution doesn’t hide the outliers it contains.

Parameters:

values, rangesnp.ndarray

Same shape, any dims (flattened internally, reshaped on return).

bin_width_mfloat, default 5.0

Range-bin width for the local median/MAD.

mad_kfloat, default 3.5

Modified z-score threshold (Iglewicz & Hoaglin’s “outlier” cutoff). Lower rejects more.

min_bin_countint, default 5

Bins with fewer finite samples are left unfiltered.

Returns:

np.ndarray

float64 copy of values, same shape, rejected samples NaN.

sidescanpy.processing.outliers.mask_bright_ping_rows(array_2d, mad_k=3.5)

NaN out whole ping rows whose typical level is an extreme outlier.

Hardware with per-ping automatic gain control occasionally raises one ping’s gain well above its neighbors, leaving a uniformly bright, full-width streak. The gain multiplies the whole ping, so clipping values only dims the streak; masking the row removes it. Each row’s level is its median; a row is masked when its modified z-score 0.6745 * |level - median| / MAD across rows exceeds mad_k.

Parameters:

array_2dnp.ndarray

(n_pings, n_samples).

mad_kfloat, default 3.5

Modified z-score threshold (Iglewicz & Hoaglin’s “outlier” cutoff).

Returns:

np.ndarray

array_2d itself when nothing is masked (or fewer than 5 rows have a finite level, or the MAD is 0), otherwise a copy with the outlier rows NaN.