sidescanpy.analysis.nadir#

Nadir analysis: how nadir is represented, and where the bottom starts.

analyze_nadir() classifies the first nadir_n_samples of each ping (gap / bright_spike / noisy / clean) and reports two distinct reference points per (ping, channel):

  • the altitude sample — the vehicle altitude in sample units (where ground_range_m first goes finite). Not a boundary of the data.

  • the first bottom return — where backscatter actually rises to the bottom echo (detect_first_bottom_return()), floored at the altitude sample. Everything before it is the nadir gap: blanking, noise, and the span the tilted beam never illuminates.

Built on sidescanpy.processing.bottom.

Contents

NadirResult

Nadir classification and bottom-boundary statistics.

analyze_nadir

Classify nadir and locate the altitude sample and first bottom return.
class sidescanpy.analysis.nadir.NadirResult(nadir_type=None, nadir_n_samples=None, nadir_mean=None, nadir_std=None, nadir_pct_zero=None, offnadir_mean=None, offnadir_std=None, nadir_offnadir_ratio=None, thresholds=<factory>, altitude_sample_median=None, altitude_sample_p10=None, altitude_sample_p90=None, first_bottom_return_sample_median=None, first_bottom_return_sample_p10=None, first_bottom_return_sample_p90=None, altitude_to_bottom_gap_sample_median=None, signal_step_check_ping=None, signal_step_check_channel=None, signal_step_pre_mean=None, signal_step_post_mean=None, signal_step_ratio=None, notes=<factory>, altitude_sample=None, first_bottom_return_sample=None)#

Bases:

Nadir classification and bottom-boundary statistics.

nadir_type is "gap", "bright_spike", "noisy" or "clean". Sample-index statistics are None when not computed. The per-(ping, channel) arrays altitude_sample and first_bottom_return_sample are left out of to_dict().

sidescanpy.analysis.nadir.analyze_nadir(ds, value_var='backscatter_intensity', range_var='ground_range_m', *, nadir_n_samples=50, bright_spike_ratio=1.5, noisy_std_ratio=1.5, gap_pct_zero_threshold=20.0, water_column_post_window=20, strong_return_smooth_window=10, strong_return_threshold_fraction=0.2, strong_return_min_run=10, strong_return_min_sample_buffer=0.0, strong_return_peak_percentile=100.0, min_first_bottom_return_sample=None, boundary_smoothing_window=15)#

Classify nadir and locate the altitude sample and first bottom return.

Classification (first match wins), comparing samples [0, nadir_n_samples) against the rest of each ping:

  • gap — at least gap_pct_zero_threshold % of nadir values are 0

  • bright_spike — nadir/off-nadir mean ratio >= bright_spike_ratio

  • noisy — nadir/off-nadir std ratio >= noisy_std_ratio

  • clean — otherwise

A corroborating step check compares the mean of water_column_post_window samples on either side of the first bottom return on the middle ping (channel 0) and adds a note if the signal doesn’t step up.

Parameters:
range_varstr, default “ground_range_m”

Used for the altitude sample. If absent, that part is skipped with a note; the first bottom return is still detected (without the altitude floor).

strong_return_smooth_window, strong_return_threshold_fraction,
strong_return_min_run, strong_return_min_sample_buffer,
strong_return_peak_percentile

Passed to detect_first_bottom_return() as smooth_window / threshold_fraction / min_run / min_sample_buffer / peak_percentile.

min_first_bottom_return_samplefloat, optional

Extra scalar floor on the first bottom return, combined with the altitude floor by element-wise max.

boundary_smoothing_windowint, default 15

smooth_boundary_across_pings() window for the first bottom return; <= 1 disables.