sidescanpy.io.hdf5.survey_dir#

Helpers for reading and rewriting directories of .ss.h5 files.

read_survey_dir() – one frequency channel of a directory of files, lazily concatenated along ping.
concat_survey_frequency(), available_frequencies(), load_channel_dataset() – lower-level pieces of the same multi-file convention (a file or a directory both work for the latter two).
read_survey_pings() – every frequency channel of a file or directory, cut to one ping range and loaded.
check_disk_space(), atomic_write_survey() – safe in-place rewrite support.

2026 rshomberg@uri.edu

Contents

`concat_survey_frequency`	Lazily concatenate `freq_key`'s channel across every file in `files` (sorted, so typically time order) into one dask-backed dataset spanning the whole survey -- no per-file restart.
`read_survey_dir`	Read a directory of `.ss.h5` files as one lazily concatenated dataset of `freq_key`.
`available_frequencies`	Every frequency key present at `input_path` -- a single `.ss.h5` file (its own `.frequencies`) or a directory of them (the union across every file -- not every file need carry every key, same as `concat_survey_frequency()`'s own per-file tolerance).
`load_channel_dataset`	One frequency channel's dataset from `input_path`.
`read_survey_pings`	Every frequency channel at `input_path` cut to pings `[start, stop)`, loaded.
`check_disk_space`	True if there's plausibly enough free space to safely rewrite `path` in place (conservative flat multiplier of its current size).
`atomic_write_survey`	Write `survey` to a temp file next to `path`, then replace `path` only on full success (a failed write leaves `path` intact).

sidescanpy.io.hdf5.survey_dir.concat_survey_frequency(files, freq_key, chunks)#

Lazily concatenate freq_key’s channel across every file in files (sorted, so typically time order) into one dask-backed dataset spanning the whole survey – no per-file restart.

Most callers want read_survey_dir() or load_channel_dataset() instead, which wrap this.

Returns (concatenated_ds, file_start_ping) where file_start_ping[path] is that file’s own first ping’s position in the concatenated dataset’s global ping axis (0 for the first file). concatenated_ds is None if no file has this frequency at all.

sidescanpy.io.hdf5.survey_dir.read_survey_dir(path, *, freq_key, chunks=None)#

Read a directory of .ss.h5 files as one lazily concatenated dataset of freq_key.

Files are taken in sorted filename order. Thin wrapper over concat_survey_frequency() that drops the per-file start-ping map.

Raises FileNotFoundError if path has no .ss.h5 files and ValueError if none of them carries freq_key.

sidescanpy.io.hdf5.survey_dir.available_frequencies(input_path, chunks=None)#

Every frequency key present at input_path – a single .ss.h5 file (its own .frequencies) or a directory of them (the union across every file – not every file need carry every key, same as concat_survey_frequency()’s own per-file tolerance).

Raises FileNotFoundError if input_path is a directory with no .ss.h5 files in it.

sidescanpy.io.hdf5.survey_dir.load_channel_dataset(input_path, freq_key, chunks=None)#

One frequency channel’s dataset from input_path.

input_path may be a single .ss.h5 file (original behavior, byte-identical – calls read_survey exactly as every caller already did directly) or a directory of them, lazily dask-concatenated in filename/acquisition order via concat_survey_frequency() – the same multi-file convention sidescan-export’s own --ss-h5-dir already uses. This lets a survey that was never concatenated into one file at conversion time (e.g. for memory safety) still be analyzed as one logical survey.

Raises FileNotFoundError/ValueError if freq_key isn’t present anywhere at input_path – never returns None, unlike concat_survey_frequency() itself, so every caller here can treat this as a normal “the dataset I asked for” return.

sidescanpy.io.hdf5.survey_dir.read_survey_pings(input_path, start=0, stop=None, *, chunks=None)#

Every frequency channel at input_path cut to pings [start, stop), loaded.

input_path is a .ss.h5 file or a directory of them (see load_channel_dataset()). Every channel is cut to the same ping range, so channels must share one ping axis. Only the channel datasets are carried; aux records are not. For a directory, the survey is named after the directory, source_format is "ss_h5" and source_files lists the .ss.h5 files.

sidescanpy.io.hdf5.survey_dir.check_disk_space(path, multiplier)#: True if there’s plausibly enough free space to safely rewrite path in place (conservative flat multiplier of its current size).

sidescanpy.io.hdf5.survey_dir.atomic_write_survey(survey, path)#: Write survey to a temp file next to path, then replace path only on full success (a failed write leaves path intact).