binary_reader

High-level reader for RDI ADCP binary files. Returns xarray.Dataset objects ready for analysis.

This is the primary entry point for loading ADCP data. It wraps pd0_parser and automatically handles metadata extraction, coordinate assignment, and accessor registration.

Functions

Function	Description
`pyadps.read()`	Load complete dataset — primary entry point
`pyadps.read_header()`	File structure and data type mapping
`pyadps.read_fixed_leader()`	Static instrument configuration (36 raw + 25 decoded fields)
`pyadps.read_variable_leader()`	Per-ensemble sensor data (48 raw + 46 decoded + 2 composite fields)
`pyadps.read_velocity()`	Velocity array — shape `(beam, cell, time)`, units mm/s
`pyadps.read_correlation()`	Correlation array — shape `(beam, cell, time)`, range 0–255
`pyadps.read_echo_intensity()`	Echo intensity array — range 0–255 (multiply by 0.45 for dB)
`pyadps.read_percent_good()`	Percent good array — range 0–100
`pyadps.read_status()`	Status diagnostic bit flags

Usage

import pyadps

# Load the complete dataset
ds = pyadps.read('deployment.000')

# Load specific components only — useful for large files
ds = pyadps.read('deployment.000', data_types=['Velocity', 'Correlation'])

data_types options: 'FixedLeader', 'VariableLeader', 'Velocity', 'Correlation', 'Echo', 'PercentGood', 'Status'.

VariableLeader is always included because it provides the time coordinate.

Key Defaults

Parameter	Default	Effect
`missing_as_nan`	`True`	RDI missing value (−32768) replaced with `NaN`
`include_mask`	`True`	A 3D QC mask variable is created from missing values
`include_decoded`	`True`	Decoded fields (frequency, heading in degrees, etc.) are included
`use_time_as_primary_dim`	`True`	Time is the first dimension
`use_depth_as_primary_dim`	`False`	Cell index used; set `True` for physical depth in metres

Time Utilities

Two time axis utilities are available for correcting irregular timestamps. These are most conveniently accessed through ProcessedDataset.apply_time_axis() in the processing module, but can also be called directly:

from pyadps.processing.time_axis import snap_time_axis, fill_time_gaps

# Snap drifted timestamps to the nearest hour
ds_snapped, success, msg = snap_time_axis(ds, freq='h', tolerance='5min')

# Fill missing ensembles so the time axis is uniform
ds_filled = fill_time_gaps(ds_snapped, method='auto')

See Also

pd0_parser — Low-level binary parsing
accessors — Domain-specific accessor methods
Processing Module — Quality control pipeline