AeroViz

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

pip install AeroViz

Pre-built for Linux, macOS, and Windows — no compiler needed. Plotting lives in an extra: pip install "AeroViz[plot]". Details, building from source and troubleshooting: Installation.

Quick Start

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

See the instrument reference 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 has the full parameter list, QC flags, and df.attrs reference.

Data Processing & Visualization

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 for details.

Documentation

• Full Documentation
• Installation · Getting Started · RawDataReader Usage
• Supported Instruments · Gallery
• Changelog

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development setup and release workflow, and GitHub Issues for bug reports and feature requests.

License

MIT License - see LICENSE for details.

Citation

If you use AeroViz in your research, please cite it. The metadata is in CITATION.cff; GitHub's "Cite this repository" button gives APA and BibTeX.

Chan, C.-Y. AeroViz: Aerosol Data Processing and Visualization Toolkit (Version 0.5.0) [Computer software].
https://github.com/Alex870521/AeroViz