sidescanpy.core.history

Processing history: the record of which correction steps were applied.

ds.attrs["processing_history"] is a JSON-encoded list of step records, appended to by every step that changes a frequency channel dataset:

{
    "step": "tvg",                      # canonical step name
    "params": {...},                    # actual params used, defaults included
    "function": "sidescanpy.processing.radiometric.apply_tvg",
    "version": "0.5.0",                 # sidescanpy version that applied it
    "timestamp_utc": "2026-10-07T12:00:00+00:00",
}

The history is what makes corrections idempotent (a recorded step is not re-applied) and reversible (radiometric steps are undone from their recorded params). The processing level is derived from it (processing_level()), not stored as a separate attribute. The history records what the library did; it does not describe the input data (units, hardware TVG state) – that is the caller’s knowledge.

Geometric and georef steps only add variables, so for them a present, not-all-NaN output variable is what counts as “done” (has_step()).

Legacy files: step names written by older versions (tvg_correction, compute_geometric_ranges, …) are mapped to the canonical names by canonical_step(), and a legacy processing_level attribute is used only as a fallback when the history records no recognised step.

2026 rshomberg@uri.edu

Contents

STEP_CROP_FARRANGE	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_INTERPOLATE_AUX	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_BOTTOM_TRACK	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_LAYBACK	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_TVG	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_GEOMETRIC	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_RANGE_CORRECTION	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
STEP_GEOREF	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
BUILTIN_STEPS	Built-in correction steps, in their canonical (dependency) order.
RADIOMETRIC_STEPS	Steps that change backscatter_intensity values and can be inverted.
STEP_OUTPUT_VARS	Variables added by the geometric/georef steps.
LEGACY_STEP_NAMES	Step names written to processing_history by older versions.
LEVEL_STEPS	Built-in steps that define a processing level.
PROCESSING_LEVELS	Values processing_level() can return, least to most processed.
canonical_step	Map a recorded step name (possibly a legacy one) to its canonical name.
read_history	Parsed processing_history records (raw, names not canonicalised).
applied_steps	Canonical names of every recorded step, oldest first.
has_step	True if step has been applied to ds.
processing_level	The most advanced correction step applied to ds (canonical order), or "raw".
append_history	Return a shallow copy of ds with one step record appended.
remove_history_records	Return a shallow copy of ds without the history records at indices.

sidescanpy.core.history.STEP_CROP_FARRANGE = 'crop_farrange'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_INTERPOLATE_AUX = 'interpolate_aux'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_BOTTOM_TRACK = 'bottom_track'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_LAYBACK = 'layback'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_TVG = 'tvg'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_GEOMETRIC = 'geometric'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_RANGE_CORRECTION = 'range_correction'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.STEP_GEOREF = 'georef'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

sidescanpy.core.history.BUILTIN_STEPS

Built-in correction steps, in their canonical (dependency) order.

sidescanpy.core.history.RADIOMETRIC_STEPS = ('tvg', 'range_correction')

Steps that change backscatter_intensity values and can be inverted.

sidescanpy.core.history.STEP_OUTPUT_VARS

Variables added by the geometric/georef steps. The first one listed is the variable checked by has_step().

sidescanpy.core.history.LEGACY_STEP_NAMES

Step names written to processing_history by older versions.

sidescanpy.core.history.LEVEL_STEPS

Built-in steps that define a processing level. Cropping, aux interpolation, bottom tracking and layback prepare data but do not correct the backscatter, so they are not levels.

sidescanpy.core.history.PROCESSING_LEVELS = ('raw', 'tvg', 'geometric', 'range_correction', 'georef')

Values processing_level() can return, least to most processed.

sidescanpy.core.history.canonical_step(name)

Map a recorded step name (possibly a legacy one) to its canonical name.

sidescanpy.core.history.read_history(ds)

Parsed processing_history records (raw, names not canonicalised).

A missing attribute is an empty history. Malformed JSON logs a WARNING and is treated as empty.

sidescanpy.core.history.applied_steps(ds)

Canonical names of every recorded step, oldest first.

sidescanpy.core.history.has_step(ds, step)

True if step has been applied to ds.

Geometric/georef: their output variable is present and not all NaN (a variable dropped since is “not done”; when the step is also recorded in the history the NaN scan is skipped). Every other step (built-in or custom): a record with that name (legacy names included) is in the history. A legacy processing_level == "radiometric" attribute counts as tvg when no history record says so.

sidescanpy.core.history.processing_level(ds)

The most advanced correction step applied to ds (canonical order), or "raw".

Derived from has_step() for each of LEVEL_STEPS; custom steps, cropping and aux interpolation do not change the level. One of PROCESSING_LEVELS.

sidescanpy.core.history.append_history(ds, step, params, *, function, version)

Return a shallow copy of ds with one step record appended.

Also drops the legacy processing_level attribute: once the library has written history, the level is derived from it.

params must be JSON-serialisable; non-serialisable values are stored via str().

sidescanpy.core.history.remove_history_records(ds, indices)

Return a shallow copy of ds without the history records at indices.

Also drops the legacy processing_level attribute (see append_history()).