sidescanpy.io.hdf5.reader

Read a SideScanSurvey from an HDF5 (.ss.h5) file.

Pass chunks= for lazy/dask-backed loading of frequency channel data. Aux records are always loaded eagerly (they’re small).

2026 rshomberg@uri.edu

Contents

check_format_version	Check a .ss.h5 file's format_version root attribute.
read_survey	Read a .ss.h5 file back into a SideScanSurvey.

sidescanpy.io.hdf5.reader.check_format_version(root_attrs, path='')

Check a .ss.h5 file’s format_version root attribute.

Parameters:

root_attrsdict

The file’s root attributes.

pathPath or str, optional

Used in log messages only.

Returns:

str or None

The file’s format version, or None for a file written before the attribute existed (sidescanpy 0.8 and earlier), which is logged at DEBUG and read as is.

Notes

A file whose version is newer than this sidescanpy knows (SS_FORMAT_VERSION) is read anyway and logs a WARNING, because a newer layout may hold variables this reader does not understand.

sidescanpy.io.hdf5.reader.read_survey(path, *, chunks=None)

Read a .ss.h5 file back into a SideScanSurvey.

Parameters:

pathPath or str

Source file path.

chunksdict, optional

Pass to xr.open_dataset for lazy loading of frequency channel data via dask. e.g. chunks={"ping": 256}. None (default) loads eagerly. Aux records are always loaded eagerly regardless of this parameter.

Returns:

SideScanSurvey

Validated survey, fully populated from on-disk groups.

Raises:

FileNotFoundError

If path does not exist.

ValueError

If any loaded dataset fails its accessor’s schema validation.