sidescanpy.processing.inversion

Undo recorded corrections, driven by processing_history.

No uncorrected copy of the backscatter is stored: radiometric steps are inverted exactly from the parameters recorded in their history records, and geometric/georef steps are undone by dropping the variables they added, and layback by restoring the positions it kept.

• uncorrected_backscatter() – the pre-radiometric signal as a DataArray (nothing else touched). Works lazily on dask-backed data.

• invert() – a dataset with the chosen steps undone and their history records removed.

Not invertible: crop_farrange (samples are gone), interpolate_aux (the converter’s embedded per-ping values were overwritten) and caller-supplied steps (unknown effect).

Legacy files: TVG records written by older versions (tvg_correction) carry the same parameters and invert the same way. A legacy file whose only TVG evidence is the processing_level == "radiometric" attribute falls back to its stored LEGACY_RAW_VAR (backscatter_raw) variable.

2026 rshomberg@uri.edu

Contents

INVERTIBLE_STEPS	Built-in immutable sequence.
UNCORRECTED_VAR	Name of the in-memory variable holding the uncorrected signal (never stored on disk).
LEGACY_RAW_VAR	Variable older files stored as a raw copy; read for legacy files, dropped on rewrite.
uncorrected_backscatter	backscatter_intensity with every recorded radiometric step undone.
with_uncorrected_var	Add the uncorrected variable unless ds already has it.
invert	Undo recorded correction steps.

sidescanpy.processing.inversion.INVERTIBLE_STEPS

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

sidescanpy.processing.inversion.UNCORRECTED_VAR = 'uncorrected'

Name of the in-memory variable holding the uncorrected signal (never stored on disk).

sidescanpy.processing.inversion.LEGACY_RAW_VAR = 'backscatter_raw'

Variable older files stored as a raw copy; read for legacy files, dropped on rewrite.

sidescanpy.processing.inversion.uncorrected_backscatter(ds)

backscatter_intensity with every recorded radiometric step undone.

Equals backscatter_intensity when no radiometric step was applied. Exact-zero input amplitude (clipped to -120 dB by TVG) comes back as 0. Lazy for dask-backed input. Does not modify ds.

sidescanpy.processing.inversion.with_uncorrected_var(ds)

Add the uncorrected variable unless ds already has it.

uncorrected is uncorrected_backscatter() (backscatter_intensity with every recorded radiometric step undone); lazy on dask-backed data. Returns a new dataset; ds is not modified.

sidescanpy.processing.inversion.invert(ds, steps=None)

Undo recorded correction steps.

Parameters:

dsxr.Dataset

Frequency channel dataset.

stepsiterable of str, optional

Steps to undo, any of INVERTIBLE_STEPS. Default: every one that has been applied. Radiometric steps are undone newest first and must include every radiometric step recorded after the oldest one requested (tvg cannot be undone underneath a later range_correction). Undoing geometric also undoes georef (it is derived from the geometric variables) and requires range_correction to be undone too if it was applied (it needs ground_range_m). Undoing layback restores the recorded positions and also undoes georef (computed from the moved positions). Steps that were never applied are ignored.

Returns:

xr.Dataset

New dataset: backscatter_intensity restored, geometric/georef output variables dropped, layback positions restored, and the undone steps’ history records removed. Records of non-invertible steps (crop_farrange, interpolate_aux, custom steps) are kept.

Raises:

ValueError

For a non-invertible or unknown step name, or a request that would leave a dependent step behind (see above).