sidescanpy.io.xtf.split

Split XTF pings into runs of constant sample interval.

Some recorders keep a fixed number of samples per ping and change the range setting mid-file, so the sample interval (TimeDuration / NumSamples) changes from one ping to the next. The survey model has one sample_rate_hz per frequency, so a file like that cannot become one survey without giving some pings the wrong range. split_by_sample_rate() cuts the pings of one file into consecutive runs (in file order) within which every channel keeps its sample rate, each run an XtfPingData that sidescanpy.io.xtf.convert() turns into its own survey.

Cut rule

For each port/starboard channel the per-ping sample rate is NumSamples / TimeDuration (NumSamples / SlantRange, proportional at constant sound speed, when a channel never records TimeDuration). A run’s reference rate for a channel is the first rate it records in the run; a ping whose rate differs from that reference by more than rtol (relative) starts a new run. Comparing with the run’s reference rather than the previous ping stops a slow drift from accumulating inside a run. Pings where a channel is absent (present False) or carries no usable rate do not take part for that channel, so they never cause a cut. A cut in any channel cuts every channel.

Runs shorter than min_pings are dropped (a range change usually leaves a few pings at an intermediate setting). A file without a cut is returned whole whatever its length.

Each run is a view of the file’s arrays (no copy, no re-read). A channel absent from every ping of a run is left out of that run, so a run may hold fewer frequencies than the file. stats and block_stats are the whole file’s. segment (XtfSegmentInfo) records where the run sits in the file; the converter turns it into xtf_ provenance attributes.

2026 rshomberg@uri.edu

Contents

SPLIT_RTOL	Default relative change in sample rate that starts a new run.
SPLIT_MIN_PINGS	Default minimum run length (pings) kept by split_by_sample_rate().
sample_rate_runs	Consecutive runs of constant sample rate, as (start, stop) ping ranges.
split_by_sample_rate	Split one file's pings at sample-rate (range-setting) changes.

sidescanpy.io.xtf.split.SPLIT_RTOL = 0.01

Default relative change in sample rate that starts a new run.

sidescanpy.io.xtf.split.SPLIT_MIN_PINGS = 50

Default minimum run length (pings) kept by split_by_sample_rate().

sidescanpy.io.xtf.split.sample_rate_runs(data, *, rtol=0.01)

Consecutive runs of constant sample rate, as (start, stop) ping ranges.

The runs cover every ping of data in order. See the module docstring for the cut rule.

Parameters:

dataXtfPingData

Pings of one file (read_xtf()).

rtolfloat, default 0.01

Relative change in a channel’s sample rate that starts a new run.

Returns:

list[tuple[int, int]]

Half-open ping ranges; empty when data has no pings.

sidescanpy.io.xtf.split.split_by_sample_rate(data, *, min_pings=50, rtol=0.01)

Split one file’s pings at sample-rate (range-setting) changes.

Parameters:

dataXtfPingData

Pings of one file (read_xtf()).

min_pingsint, default 50

Runs with fewer pings are dropped. Ignored when the file has a single run.

rtolfloat, default 0.01

Relative change in a channel’s sample rate that starts a new run.

Returns:

list[XtfPingData]

The kept runs in file order, each a view of data with segment set. One element (covering the whole file) when the sample rate never changes; empty when every run is shorter than min_pings (logged at WARNING).