I/O Module

The pyadps.io module reads RDI ADCP binary files (PD0 format) and converts them into xarray.Dataset objects ready for analysis and processing.

Architecture

The module is organised in three layers:

Layer

Module

Purpose

1

pd0_parser

Low-level binary parsing — bytes to NumPy arrays

2

binary_reader

High-level reader — NumPy arrays to xarray.Dataset

3

accessors

Domain-specific methods attached to the Dataset

Most users only need the binary_reader layer via pyadps.read(). The pd0_parser layer is for advanced users who need direct binary access.

Reading a File

import pyadps

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

The returned object is a standard xarray.Dataset containing velocity, correlation, echo intensity, percent good, fixed leader, and variable leader data. All xarray operations (indexing, plotting, NetCDF export) work directly.

Loading Specific Components

Use data_types to load only the variables you need — useful for large files:

ds = pyadps.read('deployment.000', data_types=['Velocity', 'Correlation'])

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

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

use_time_as_primary_dim

True

Time is the first dimension

use_depth_as_primary_dim

False

Cell index used instead of physical depth

Available Functions

Function

Description

pyadps.read()

Load complete dataset — primary entry point

pyadps.read_header()

Read file header and structure metadata

pyadps.read_fixed_leader()

Read static instrument configuration

pyadps.read_variable_leader()

Read per-ensemble sensor data

pyadps.read_velocity()

Read velocity array (beam × cell × time) in mm/s

pyadps.read_correlation()

Read correlation array (0–255)

pyadps.read_echo_intensity()

Read echo intensity array (0–255, ×0.45 for dB)

pyadps.read_percent_good()

Read percent good array (0–100)

pyadps.read_status()

Read status diagnostic bit flags

Accessor Methods

Accessor methods are automatically registered when you import pyadps — no additional import is needed. They are available on any Dataset returned by the read functions.

Header (ds.header.*)

Note

Header data is not loaded by default. Pass include_header=True to pyadps.read() before using any ds.header.* method, or they will silently report failure (e.g. check_file() returning File Size Match: False) rather than raising an error.

Method

Description

check_file()

Verify file integrity (size, byte uniformity)

get_available_data_types()

List data types present in the file

get_ensemble_info(ensemble)

Metadata for a specific ensemble

validate()

Full validation report

summary()

Print formatted header summary

Fixed Leader (ds.fixed_leader.*)

Method

Description

system_configuration()

Frequency, beam pattern, orientation

coordinate_transformation()

Coordinate system and transformation settings

sensor_info()

Available and active sensors

is_uniform()

Check if configuration is consistent across ensembles

validate()

Full validation report

summary()

Print formatted configuration summary

Variable Leader (ds.variable_leader.*)

Method

Description

validate_timestamps()

Check time coordinate validity

get_time_interval()

Most common ensemble interval

is_time_regular()

Check if time axis is uniform

get_time_component_frequency()

Frequency distribution of time components

ensemble_continuity_check()

Detect gaps in ensemble numbering

bit_result_summary()

Decode Built-In Test result bits

error_status_word_summary()

Decode all four Error Status Words

summary()

Print formatted variable leader summary

Low-Level Access

For direct binary access without the xarray layer:

from pyadps.io import pd0_parser

# Parse file structure
dt, byte, byteskip, offset, idarray, n_ens, err = pd0_parser.fileheader('deployment.000')

# Read velocity as NumPy array
data, n_ens, cell_array, beam_array, err = pd0_parser.datatype('deployment.000', 'velocity')

See pd0_parser for full details.

Contents

See Also