Metadata-Version: 2.1
Name: AeroViz
Version: 0.3.4
Summary: Aerosol data processing and visualization toolkit. Read, QC, and analyze data from SMPS, APS, AE33, TEOM, Nephelometer, XRF, and 15+ atmospheric instruments.
Keywords: aerosol,atmospheric-science,air-quality,data-processing,visualization,PM2.5,PM10,black-carbon,particle-size-distribution,optical-properties,SMPS,APS,aethalometer,nephelometer,TEOM,XRF,OC-EC,environmental-monitoring,research,quality-control
Author-Email: Alex Chan <alex870521@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Project-URL: Homepage, https://github.com/Alex870521/AeroViz
Project-URL: Documentation, https://alex870521.github.io/AeroViz/
Project-URL: Repository, https://github.com/Alex870521/AeroViz
Project-URL: Issues, https://github.com/Alex870521/AeroViz/issues
Project-URL: Changelog, https://github.com/Alex870521/AeroViz/blob/main/docs/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: pandas>=2.2.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: matplotlib>=3.8.4
Requires-Dist: scipy>=1.15.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: scikit-learn>=1.5.1
Requires-Dist: windrose>=1.9.2
Requires-Dist: cartopy>=0.24.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: rich~=13.9.4
Requires-Dist: numba>=0.63.0
Requires-Dist: plotly>=5.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: commitizen>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=8.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.18.0; extra == "docs"
Description-Content-Type: text/markdown

<div align="center">

# AeroViz

**Aerosol Data Processing and Visualization Toolkit for Atmospheric Research**

[![Python](https://img.shields.io/pypi/pyversions/aeroviz?logo=python)](https://pypi.org/project/aeroviz/)
[![PyPI](https://img.shields.io/pypi/v/aeroviz?logo=pypi)](https://pypi.org/project/aeroviz/)
[![Pytest](https://img.shields.io/github/actions/workflow/status/Alex870521/aeroviz/pytest.yml?logo=pytest&label=pytest)](https://github.com/Alex870521/AeroViz/actions)
[![Documentation](https://img.shields.io/badge/docs-MkDocs-blue?logo=materialformkdocs)](https://alex870521.github.io/AeroViz/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

</div>

AeroViz is a Python toolkit for reading, processing, and visualizing aerosol measurement data. It supports 18+ atmospheric instruments with built-in quality control, data processing, and publication-ready visualizations.

## Installation

```bash
pip install AeroViz
```

Pre-built for Linux, macOS, and Windows — no compiler needed.

## Quick Start

```python
from AeroViz import RawDataReader

df = RawDataReader(
    instrument='AE33',
    path='/path/to/data',
    start='2024-01-01',  # optional — omit to read the files' full coverage
    end='2024-12-31',    # optional
    mean_freq='1h',      # optional — '1h' resamples to hourly; omit for native resolution
    qc=True,             # apply quality control
)
print(df[['eBC', 'AAE']].describe())

# Or read everything the files contain, at native resolution:
df_all = RawDataReader('AE33', '/path/to/data')
print(df_all.attrs['coverage_start'], '→', df_all.attrs['coverage_end'])
```

> [!IMPORTANT]
> **Behaviour change:** `mean_freq` no longer defaults to `'1h'` — the default is
> now **no resampling** (native resolution). Pass `mean_freq='1h'` (or `'30min'`,
> `'1D'`) for averaging. `start` / `end` are also optional now.

## Supported Instruments

| Category | Instruments |
|----------|-------------|
| Black carbon / absorption | AE33, AE43, BC1054, MA350 |
| Particle sizers | SMPS, APS, GRIMM |
| Mass concentration | TEOM, BAM1020 |
| Optical | NEPH, Aurora |
| Chemical composition | Xact, OCEC, IGAC, Q-ACSM |

See the [instrument reference](https://alex870521.github.io/AeroViz/api/instruments/)
for output columns and per-instrument notes.

## Usage

`RawDataReader` returns a pandas `DataFrame`. Key options:

- `start` / `end` — optional date range (omit for the files' full coverage)
- `mean_freq` — resample frequency, e.g. `'1h'` (omit for native resolution)
- `qc` — quality control (on by default; flags rows via `QC_Flag` and reports rates)
- `fill_missing` — pad to the requested range (default) or clamp to coverage
- `size_range` — diameter filter for SMPS / APS

Result metadata — coverage, QC rates, native frequency and more — is attached to
`df.attrs`. The [RawDataReader guide](https://alex870521.github.io/AeroViz/guide/rawdatareader/)
has the full parameter list, QC flags, and `df.attrs` reference.

## Data Processing & Visualization

```python
from AeroViz import reconstruct_mass, improve, mie, merge_psd, voc_potentials, plot
from AeroViz.plot import timeseries_interactive
```

- **Top-level processing functions** — each takes a DataFrame (or a few) and
  returns a DataFrame/dict: `reconstruct_mass` & `volume_ri`/`kappa` (chemistry),
  `improve`/`mie`/`retrieve_ri` (optical), `merge_psd`/`psd_stats` (size
  distribution), `voc_potentials` (OFP, SOAP). They are grouped under the
  `chemistry`, `optical`, `size`, `voc` namespaces too.
- **`plot`** — publication-ready matplotlib figures (`timeseries`,
  `diurnal_pattern`, `scatter`, `meteorology.wind_rose`, …).
- **`timeseries_interactive(df)`** — quick interactive Plotly viewer; click the
  legend to toggle columns, or `save='out.html'` for a standalone file.

> **`DataProcess(...)` is deprecated** (it still works but emits a
> `DeprecationWarning`); use the top-level functions above.

See the [user guide](https://alex870521.github.io/AeroViz/) for details.

## Documentation

- [Full Documentation](https://alex870521.github.io/AeroViz/)
- [RawDataReader API](https://alex870521.github.io/AeroViz/api/RawDataReader/)
- [Changelog](docs/CHANGELOG.md)

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the
development setup and release workflow, and
[GitHub Issues](https://github.com/Alex870521/AeroViz/issues) for bug reports
and feature requests.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Citation

If you use AeroViz in your research, please cite:

```
AeroViz: Aerosol Data Processing and Visualization Toolkit
https://github.com/Alex870521/AeroViz
```

<div align="center">

## Contributors

<a href="https://github.com/Alex870521"><img src="https://github.com/Alex870521.png" width="40" height="40" alt="Alex870521" style="border-radius: 50%;"></a>
<a href="https://github.com/yrr-Su"><img src="https://github.com/yrr-Su.png" width="40" height="40" alt="yrr-Su" style="border-radius: 50%;"></a>
<a href="https://github.com/Masbear"><img src="https://github.com/Masbear.png" width="40" height="40" alt="Masbear" style="border-radius: 50%;"></a>

</div>
