Metadata-Version: 2.4
Name: py-ona
Version: 0.1.0b2
Requires-Dist: numpy
License-File: LICENSE
Summary: Optimized Noise-reduction Averaging (ONA) smoothing for black carbon aethalometer data.
Keywords: aethalometer,black-carbon,smoothing,ona,air-quality
Home-Page: https://github.com/jbandoro/py-ona
Author: Justin Bandoro
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/jbandoro/py-ona
Project-URL: Repository, https://github.com/jbandoro/py-ona

# py-ona

Optimized noise-reduction averaging (ONA) smoothing for black carbon aethalometer data.

ONA smoothing reduces noise in black carbon time series using a variable, per-sample centered rolling mean.
Periods that have little change get a wider window (more smoothing), while volatile periods get a narrower window (to preserve real signal). See the EPA's [Optimized Noise-reduction Algorithm (ONA) program](https://www.epa.gov/air-research/optimized-noise-reduction-algorithm-ona-program-improves-black-carbon-particle).

The numeric algorithm is implemented in Rust (the [`ona`](Cargo.toml) crate) along with PyO3 bindings so it can be
used in Python.

![ONA smoothing of black carbon aethalometer data](assets/ona_smoothing.png)

## Installation

```bash
pip install py-ona
```

Requires Python 3.12 or later.

## Usage

`smooth` takes `float64` numpy arrays of black carbon values (µg/m³) and their timestamps (unix seconds), and returns the smoothed series:

```python
import numpy as np
import ona

values = np.array([0.253, -1.17, 0.971, 0.775, 4.017, -0.733, 0.366])
timestamps = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0])

smoothed = ona.smooth(values, timestamps)
```

### Parameter configuration

There are five ONA parameters are exposed as kwargs with default values:

```python
smoothed = ona.smooth(
    values,
    timestamps,
    min_window_size=1.0,
    max_window_sec=60.0,
    window_smooth_width_size=30,
    low_percentile=10.0,
    high_percentile=90.0,
)
```

where

- `min_window_size` : smallest smoothing window, in samples.
- `max_window_sec`: cap on the derived max window, in seconds.
- `window_smooth_width_size`: rolling-median width used to smooth the
  per-sample window sizes.
- `low_percentile` : lower percentile of the delta distribution.
- `high_percentile`: upper percentile of the delta distribution.

## Development

This project uses [uv](https://docs.astral.sh/uv/) and [maturin](https://www.maturin.rs/):

```bash
uv sync
uv run pytest -v
cargo test 
```

