sidescanpy.analysis.characterize#

Value distribution summary and units inference.

characterize_values() — dtype, shape and distribution statistics of one variable, no interpretation (ValueSummary).
infer_units() — likely units (dB, raw counts, normalized, …) from a ValueSummary, optionally cross-checked against a range-decay fit (UnitsResult).

Contents

`ValueSummary`	Distribution statistics of one variable (finite values only).
`characterize_values`	Data type, shape and distribution of `ds[value_var]`.
`UnitsResult`	Likely units of a variable.
`infer_units`	Classify likely units from a value-range signature.

class sidescanpy.analysis.characterize.ValueSummary(dtype=None, shape=<factory>, n_values=0, n_finite=0, pct_nan=nan, minimum=nan, maximum=nan, mean=nan, median=nan, std=nan, pct_zero=nan, pct_negative=nan, notes=<factory>)#

Bases:

Distribution statistics of one variable (finite values only).

sidescanpy.analysis.characterize.characterize_values(ds, value_var='backscatter_intensity')#: Data type, shape and distribution of ds[value_var].

class sidescanpy.analysis.characterize.UnitsResult(units='unknown', value_range=<factory>, pct_negative=None, pct_zero=None, notes=<factory>)#

Bases:

Likely units of a variable.

units is one of "dB", "normalized", "raw_counts" or "unknown".

sidescanpy.analysis.characterize.infer_units(summary, decay=None)#

Classify likely units from a value-range signature.

mostly negative, within (-200, 5] → "dB"
non-negative, max in (0, 1] → "normalized"
non-negative, max > 1 → "raw_counts" (raw ADC counts or uncalibrated linear amplitude; volts can’t be told apart by value alone)
anything else → "unknown"

When decay (a fit_tvg_models() result, or a deprecated fit_range_decay() one) has a TVG status and a best-model RMS under 3 dB, a supporting note is added.