User's Guide

• 1: Channel file format specifications
• 2: Code Contribution Guide

pip install -i https://test.pypi.org/simple/ uwa-replay

channel = load('blue_1.mat');
noise = load('blue_1_noise.mat');
y = replay(input, fs, array_index, channel);
w = noisegen(size(y), fs, array_index, noise);
r = y + 0.05 * w;

from uwa_replay import replay, noisegen
channel = h5py.File("blue_1.mat", "r")
noise = h5py.File("blue_1_noise.mat", "r")
y = replay(input, fs, array_index, channel)
w = noisegen(y.shape, fs, array_index, noise)
r = y + 0.05 * w

1 - Channel file format specifications

UWA-Channels MAT File Format Specification

The uwa-channels-compatible .mat files must be saved with the following flags:

• -v7.3: Supports large variables and the HDF5 file format, ensuring better compatibility with other programming languages such as Python and Julia.
• -nocompression: Accelerates loading speed.

Required Fields

Each .mat file must include the following variables:

h_hat

• Type: Multi-dimensional numeric tensor (single or double precision). Arbitrarily scaled.
• Dimensions: [delay, receiver, time]
• Description: The estimated time-varying channel impulse response (TVIR), complex baseband.

params

A MATLAB structure containing the following scalar fields:

• fs_delay (Hz): Sampling rate of h_hat along the delay axis.
• fs_time (Hz): Sampling rate of h_hat along the time axis.
• fc (Hz): The probing waveform was basebanded with respect to fc prior to the TVIR estimation; fc typically corresponds to the center frequency of the probing waveform.

version

• Type: Numeric scalar
• Description: Dataset format version number.

Optional Fields

theta_hat

• Type: Numeric matrix of size [receiver, time] (single or double precision).
• Sampling Rate: Must match params.fs_delay
• Duration Constraint: The time duration of theta_hat must match the third dimension of h_hat, i.e., size(theta_hat, 2) * params.fs_time == size(h_hat, 3) * params.fs_delay.
• Description: For each hydrophone (receiver), theta_hat represents a time-varying resampling factor $R(t)$ to be applied to the output signal in conjunction with $h(t,\tau)$: $$ R(t) = 1 - \frac{1}{2 \pi f_c} \frac{\text{d} \hat{\theta}(t)}{\text{d} t} $$ where $f_c$ is the center frequency, and the $\hat{\theta}(t)$ is the theta_hat.

f_resamp

• Type: Scalar (single or double precision)
• Units: Unitless resampling factor
• Description: A time-invariant resampling factor applied to the output signal after convolution. This is typically the inverse of a resampling operation used to remove nominal Doppler offsets during channel estimation. It is applied after the time-varying convolution.

meta

The meta structure is optional but encouraged for documenting dataset context. The suggested fields include:

• meta.experiment_name (string): Name of the experiment.
• meta.experiment_info (string or struct): Descriptive details about the experimental setup.
• meta.array_info (string or struct): Information about the hydrophone array (e.g., geometry, number of elements).
• meta.authorship (string or struct): Data contributor names and affiliations.

Users are free to add any number of additional fields to meta to record experiment-specific metadata.

Dataset Configurations

The following configurations are currently supported:

• h_hat only — supported but not used in official datasets.
• h_hat and theta_hat — used in the blue, red, green, purple, yellow, abyssal, and namikaze datasets.
• h_hat and f_resamp — used in Watermark datasets.
• h_hat, theta_hat, and f_resamp — used in the Sky dataset.

2 - Code Contribution Guide

Contributing to UWA-Channels (MATLAB & Python)

First off — thank you for considering a contribution! Bug reports, feature requests, documentation improvements, and code changes are all welcome.

This guide explains how to contribute effectively to the two companion repositories hosted at https://github.com/uwa-channels:

Getting Started

Prerequisites

• Familiarity with Git, GitHub, Markdown, and either MATLAB or Python.
  Helpful references: GitHub Quickstart, Markdown Guide.

• Development environment:

  MATLAB repository

  git clone https://github.com/uwa-channels/matlab.git
  

  To run example scripts:

  cd examples
  example_replay
  

  To run tests:

  cd tests
  addpath('../src')
  runtests('testReplay')
  

  Python repository — create a virtual environment and install dependencies:

  git clone https://github.com/uwa-channels/python.git
  cd python
  pip install numpy scipy matplotlib h5py pytest pytest-benchmark pre-commit
  

  To run example scripts:

  PYTHONPATH=src python examples/example_replay.py
  

  To run tests:

  PYTHONPATH=src pytest
  

  To initialize pre-commit:

  pre-commit install
  pre-commit run --all-files
  

Code of Conduct

We expect all contributors to be professional, respectful, and constructive. By participating, you agree to uphold these standards.

Bug Reports, Feature Requests, & Discussions

Bug Reports

• Search existing issues and pull requests—your bug may already be reported or fixed.
• Provide a minimal, reproducible example (MATLAB .m file or live script, or a Python snippet), along with:
  • Package versions (uwa_channels.__version__ or MATLAB ver)
  • OS and MATLAB/Python version, if relevant

Feature Requests

Describe both the motivation and the proposed change. Sketch a possible API or workflow if applicable.

Discussions

General Q&A, design ideas, and roadmap conversations belong in GitHub Discussions, not in Issues.

Issue Labels

Workflow for Code & Documentation Changes

1. Fork the repository and clone your fork.
2. Create a branch from main, named like topic-short-description (lowercase, hyphen-separated).
3. Develop locally:
   • MATLAB — run runtests('tests') and address Code Analyzer (MLint) warnings.
   • Python — run PYTHONPATH=src pytest frequently.
4. Write tests for new features or bug fixes.
5. Document your changes:
   • Use NumPy-style docstrings in Python functions and classes.
   • Use MATLAB help text headers; add usage examples for public APIs.
6. Commit with clear messages, then push to your fork.
7. Open a pull request (PR) against main. Mark it as “Draft” if it’s not yet ready for review. Reference any related issues.
8. Address reviewer feedback. Once all checks pass and approvals are received, a maintainer will merge.

Commit Message Style

We follow a simplified version of Conventional Commits:

<type>(<scope>): <summary>

<body>

• type ∈ {feat, fix, docs, test, perf, refactor, style, chore, revert}
• scope identifies the module or subsystem (e.g., io, replay, noisegen)
• Use imperative mood for the summary (e.g., “add support…” not “added”)
• Limit the summary to ≤ 50 characters; wrap the body at 72 characters
• If the change is breaking, begin the body with BREAKING CHANGE:

Examples:

feat(replay): add resampling support for replay channels
fix(io): handle empty .mat files (issue #42)

Coding Standards

MATLAB, follow the MATLAB Style Guide:

• 4-space indentation; camelCase for functions, PascalCase for classes
• Each function/class in its own .m file
• Use arguments blocks for input validation where possible
• Add unit tests under tests/testPkgName/ using MATLAB Unit Test
• Vectorize where possible; comment non-obvious logic

Python

• Formatting is enforced via Black and isort
• Static analysis via Flake8 and Ruff
• Use NumPy-style doc strings with LaTeX equations where helpful
• Keep functions short, prefer clarity to cleverness, and avoid premature optimization

Testing & Continuous Integration

All CI checks must pass before a pull request is merged.

Release Process (Python only)

Maintainers tag releases using git tag -s vX.Y.Z following Semantic Versioning (SemVer).

Merged PRs are reflected in CHANGELOG.md, with entries auto-generated from commit messages.

Acknowledgments

This guide was inspired by the excellent UnderwaterAcoustics.jl contributing guide, as well as the contribution guidelines from NumPy, SciPy, and MATLAB Style Guide.

Happy hacking – may your channels be peaceful and your SNR high!