multifile

Provides tools for combining multiple ADCP binary files from a single deployment into one file before processing. Files are appended in the order they are found (alphabetical by default).

Functions

Function	Description
`combine_adcp_files(folder_path, output_file, ...)`	Combine all ADCP files found in a folder
`combine_file_list(files, output_file, ...)`	Combine a specific ordered list of files
`validate_adcp_file(filepath)`	Check a single file for structural validity

Usage

from pyadps.processing.multifile import combine_adcp_files, combine_file_list

# Combine all *.000 files in a folder (alphabetical order)
result = combine_adcp_files('raw_data/', 'combined.000')

if result.success:
    print(f"Combined {result.files_processed} files, {result.total_ensembles} ensembles")
else:
    print(result.error_message)

# Combine a specific ordered list
result = combine_file_list(
    ['data/deploy_001.000', 'data/deploy_002.000', 'data/deploy_003.000'],
    'combined.000'
)

Validate before combining

from pyadps.processing.multifile import validate_adcp_file
from pathlib import Path

for f in sorted(Path('raw_data/').glob('*.000')):
    v = validate_adcp_file(f)
    status = 'OK' if v.is_valid else v.error_message
    truncated = ' (truncated)' if v.is_truncated else ''
    print(f"{f.name}: {status}{truncated}")

Command line

python -m pyadps.processing.multifile raw_data/ -o combined.000
python -m pyadps.processing.multifile raw_data/ -o combined.000 --strict  # stop on first error
python -m pyadps.processing.multifile raw_data/ -o combined.000 -p "*.pd0"  # custom extension

Return Objects

CombineResult (returned by combine_adcp_files and combine_file_list):

Field	Description
`success`	Whether the combination completed
`files_processed`	Number of files successfully included
`total_ensembles`	Total ensembles in output
`output_path`	Path to the output file
`skipped_files`	List of filenames that were skipped
`error_message`	Populated if `success` is `False`

FileValidationResult (returned by validate_adcp_file):

Field	Description
`is_valid`	Whether the file has a valid ADCP structure
`valid_ensembles`	Number of complete ensembles found
`ensemble_size`	Bytes per ensemble
`is_truncated`	Last ensemble is incomplete
`error_message`	Populated if `is_valid` is `False`

Non-Obvious Behaviors

Ensemble size must match across all files. All files in a deployment should have the same ensemble size (bytes per ensemble). A mismatch means different instrument configurations or a corrupt file — combining them would produce unreadable output. The check is enabled by default; pass require_matching_ensemble_size=False only if you are certain the mismatch is benign.

Truncated files are skipped by default (skip_invalid=True). A truncated file at the end of a deployment is common when the instrument was recovered mid-ensemble. The partial last ensemble is dropped and the rest of the file is included.

File order matters. Use combine_file_list() with an explicitly ordered list if alphabetical sorting does not match chronological order.