sidescanpy.viz.analysis#

Plots for the analysis results in sidescanpy.analysis.

Each function renders one result (or a dataset, where the plot is of the data itself), draws into caller-supplied axes when given, returns (fig, ax) or (fig, axes) and never saves a file. Figure-level decorations (suptitle, tight_layout) are only applied when the function created the figure. TVG / range-decay plots live in sidescanpy.viz.tvg.

2026 rshomberg@uri.edu

Contents

`plot_value_histograms`	Dual-panel histogram: linear scale (left) and `log10(\|x\|)` scale (right).
`plot_units_distribution`	The `plot_value_histograms()` view titled for a units call (`infer_units` reads the value-range signature this shows).
`plot_sample_ping`	One representative ping (default: the middle one), port and starboard side by side.
`plot_outlier_comparison`	Overlaid before/after histograms (linear + log scale) of what `reject_range_outliers` discarded from `value_var`.
`plot_cross_track_profile`	One ping across the full swath (port mirrored to negative sample index).
`plot_nadir_zoom`	Cross-track profile zoomed around nadir.
`plot_nadir_waterfall`	Cross-track-vs-ping waterfall of `value_var` (via `plot_waterfall()`), with `nadir`'s altitude (dotted) and first bottom return (solid) traced on both sides when given.
`plot_beam_geometry`	Side-view beam-geometry diagram above the same ping's backscatter profile, sharing one x-axis.
`plot_usable_range`	Median and std-dev vs. range, with the usable-range boundary marked.
`plot_segments_overview`	Altitude and pitch vs. ping index with each segment boundary marked and excluded spans shaded, for reviewing `find_segments()` output.
`plot_navigation_summary`	Heading, pitch/roll, altitude/depth/heave vs. ping number, plus the lon/lat track colored by ping number.
`plot_shadow_proposals`	Draw proposal boxes onto an image already shown in `ax`.

sidescanpy.viz.analysis.plot_value_histograms(ds, value_var='backscatter_intensity', *, bins=100, axes=None, title=None)#: Dual-panel histogram: linear scale (left) and log10(|x|) scale (right).

sidescanpy.viz.analysis.plot_units_distribution(ds, value_var='backscatter_intensity', *, bins=100, axes=None)#: The plot_value_histograms() view titled for a units call (infer_units reads the value-range signature this shows).

sidescanpy.viz.analysis.plot_sample_ping(ds, value_var='backscatter_intensity', *, ping_idx=None, axes=None)#: One representative ping (default: the middle one), port and starboard side by side.

sidescanpy.viz.analysis.plot_outlier_comparison(ds, result, value_var='backscatter_intensity', *, bins=100, linear_xlim_percentile=99.5, axes=None)#

Overlaid before/after histograms (linear + log scale) of what reject_range_outliers discarded from value_var.

Each panel uses one shared set of bin edges for both populations. The linear panel is capped at the “before” population’s linear_xlim_percentile so a few extreme values cannot squash the bulk; the count beyond the cap is annotated.

sidescanpy.viz.analysis.plot_cross_track_profile(ds, value_var='backscatter_intensity', *, ping_idx=None, ax=None)#: One ping across the full swath (port mirrored to negative sample index).

sidescanpy.viz.analysis.plot_nadir_zoom(ds, value_var='backscatter_intensity', *, nadir=None, nadir_n_samples=50, ping_idx=None, zoom_factor=2, ax=None)#

Cross-track profile zoomed around nadir.

Without nadir (an analyze_nadir() result) the window is nadir_n_samples * zoom_factor. With it, the window widens to the detected boundaries, which are marked: altitude (dotted, the vehicle altitude in sample units) and first bottom return (dashed). Everything from nadir out to the first bottom return is shaded as “water column returns”.

sidescanpy.viz.analysis.plot_nadir_waterfall(ds, value_var='backscatter_intensity', *, nadir=None, ax=None, ping_offset=0, **waterfall_kwargs)#

Cross-track-vs-ping waterfall of value_var (via plot_waterfall()), with nadir’s altitude (dotted) and first bottom return (solid) traced on both sides when given.

ping_offset shifts both the image and the traced boundaries, so a slice of a larger survey can show absolute ping numbers.

sidescanpy.viz.analysis.plot_beam_geometry(ds, result, value_var='backscatter_intensity', range_var='across_track_m', *, axes=None)#

Side-view beam-geometry diagram above the same ping’s backscatter profile, sharing one x-axis.

Top: towfish, seafloor at the ping’s altitude, the near edge (solid, from the first bottom return) and far edge (dashed, from the usable range), with the illuminated wedge shaded. Bottom: value_var vs. range_var with the same edges marked.

sidescanpy.viz.analysis.plot_usable_range(result, *, axes=None)#: Median and std-dev vs. range, with the usable-range boundary marked.

sidescanpy.viz.analysis.plot_segments_overview(ds, segments, *, axes=None)#: Altitude and pitch vs. ping index with each segment boundary marked and excluded spans shaded, for reviewing find_segments() output.

sidescanpy.viz.analysis.plot_navigation_summary(ds, *, ping_offset=0, result=None, axes=None)#

Heading, pitch/roll, altitude/depth/heave vs. ping number, plus the lon/lat track colored by ping number.

The heading panel shades the [0,360) and [-180,180) conventions and, given result (summarize_navigation()), marks points outside both. ping_offset makes the x-axis read absolute ping numbers. axes is (heading, attitude, vertical, track).

sidescanpy.viz.analysis.plot_shadow_proposals(proposals, *, ax, window=None, channel=None, min_score=0.0, cmap='autumn', linewidth=0.8)#

Draw proposal boxes onto an image already shown in ax.

With window (the NativeWindow of a chip or tile shown with imshow), boxes are mapped to image pixels. Without it, ax is taken to show one channel in native coordinates (x = sample position, y = ping position) and only that channel’s proposals (default 0) are drawn. Box colour follows the score through cmap; proposals below min_score are skipped.