aerosoltools
Tools for loading and analyzing aerosol instrument data
Overview
aerosoltools is a Python library developed at NFA for loading, processing, analyzing, and plotting data from a variety of aerosol instruments. It provides consistent data structures for:
- 1D time-series (e.g. total number or mass) via
Aerosol1D - 2D size-resolved time-series via
Aerosol2D - Dual-distribution data (APS aerodynamic + optical) via
Aerosol3d - Instrument-specific classes with their own physics and accessors —
DiSCmini,DustTrak,ELPI - Non-particle instruments —
Gas1D,Aethalometer,Environmental1D,Partector,ACSM_simple(these expose domain accessors instead oftotal_concentration)
The package includes loaders for common instrument exports, tools for activity segmentation, and convenience methods for task-based statistics and exposure assessment (e.g. 8 h TWA, short-term limits, peaks).
Prefer a point-and-click workflow? An interactive desktop GUI is included — see the Desktop GUI section below.
For full documentation and usage examples, see:
👉 View the documentation — including worked examples for each topic and a guide to the desktop GUI.
🧰 Provided Loaders
| Instrument | Function | Company |
|---|---|---|
| ACSM | load_simple_acsm_file() |
Aerodyne Research |
| Aethalometer | load_aethalometer_file() |
AethLabs |
| APS | load_aps_file() |
TSI Inc. |
| CPC | load_cpc_file() |
TSI Inc. |
| DiSCmini | load_discmini_file() |
Testo |
| DiSCmini (raw export) | load_discmini_raw_file() |
Testo |
| DustTrak | load_dusttrak_file() |
TSI Inc. |
| ELPI | load_elpi_file() |
Dekati Ltd. |
| FMPS | load_fmps_file() |
TSI Inc. |
| Fourtec | load_fourtec_file() |
Fourtec Technologies |
| Grimm | load_grimm_file() |
GRIMM Aerosol Technik |
| NS (NanoScan) | load_ns_file() |
TSI Inc. |
| OPC-N3 | load_opcn3_file() |
Alphasense Ltd. |
| OPS | load_ops_file() |
TSI Inc. |
| Partector | load_partector_file() |
naneos GmbH |
| Ranger | load_ranger_file() |
Aeroqual |
| SMPS | load_smps_file() |
TSI Inc. |
| Tiger (VOC) | load_tiger_file() |
Ion Science |
| Weather station | load_devlabs_file() |
DevLabs |
Don't know which loader you need? load_file() auto-detects the instrument
from the file itself, and detect_instrument() reports what it found.
✨ Features
-
Unified interface for loaded aerosol data:
- Datetime parsing and indexing
- Particle data formatting and bin edges/midpoints
- Dtype tracking (
dN,dM,dS,dV, and/dlogDpnormalization) - Metadata extraction (instrument, units, serial number, etc.)
-
Activity handling
- Mark tasks/segments via
mark_activities() - Built-in
"All data"activity - Helper methods to extract activity-specific data
- Mark tasks/segments via
-
Summaries & exposure metrics
summarize_activities()– task-based descriptive statistics (duration, PNC, PMx, size metrics, etc.)summarize_exposure()– detailed exposure assessment:- 1D (
Aerosol1D): PNC time series - 2D (
Aerosol2D): PNC, MASS, and Pₓ metrics (e.g. PM₂.₅, PM₄.₂, PN₁₀) - 8 h (or custom) TWA with background level (value or activity)
- Short-term limit exceedances (e.g. 15 min window)
- Peak counts, high percentiles (C95/C99), IQR, durations above limits
- 1D (
-
Pₓ / fraction utilities (2D)
- Cumulative and band-limited Pₓ (PM, PN, PS, PV)
- Reuses previously computed series via internal caching
-
Time operations
- Time shifting, cropping, rebinning, and smoothing
- Handles irregular sampling safely for integration and TWA
-
Plotting
- Timeseries plots (with activity shading)
- Particle size distributions (PSD)
- Time–size heatmaps and stacked PM bands
- Simple correlation/comparison plots
-
Curve fitting
fit_psd()– lognormal mode fitting of size distributions (lognormal_modes,PSDFitResult)fit_decay()– single-zone emission + decay fitting, giving source strength, air exchange and wall-loss rates (decay_curve,DecayResult)
-
Comparing instruments (
aerosoltools.intercomparison)plot_correlation()andbland_altman_analysis()for agreement, with exact / nearest / rebin time alignmentfit_calibration(),apply_calibration(),calibrate_against_reference()to bring one instrument onto another's scale (CalibrationModel)combine_measurements()to join consecutive recordings, andcombine_size_ranges()to stitch two instruments into one distribution
-
Batch loading
load_data_from_folder()to apply a loader across a folder of files
📦 Installation
Install from PyPI:
pip install aerosoltools
To also get the interactive desktop GUI (adds the PyQt5 dependency), install
the gui extra:
pip install aerosoltools[gui]
Quickstart
Load a single instrument file
import aerosoltools as at
elpi = at.load_elpi_file("data/elpi_sample.txt")
elpi.plot_timeseries()
Access metadata
elpi.metadata
Mark activities and summarize
activity_periods = {
"Background": [("2023-09-07 09:06:50", "2023-09-07 09:07:50")],
"Emission": [("2023-09-07 09:07:55", "2023-09-07 09:08:30")],
}
elpi.mark_activities(activity_periods)
# Task-based summary across all activities
summary = elpi.summarize_activities()
# Detailed exposure summary for respirable dust (PM4.2) during "Emission"
exp = elpi.summarize_exposure(
metric="PM4.2",
activities=["Emission"],
background="Background", # or a float, or None
short_limit=1.0,
long_limit=1.0,
)
Batch-load a folder of files
folder_path = "data/cpc_campaign/"
data = at.load_data_from_folder(folder_path, at.load_cpc_file)
🖥️ Desktop GUI
aerosoltools ships with an interactive desktop app for loading multiple
datasets, marking shared tasks, and exploring time series, size distributions,
summaries, overlays and instrument correlations — no coding required.
📖 Full GUI documentation — a guided tour of the window plus a page for every tab.
First install the GUI extra (adds PyQt5):
pip install aerosoltools[gui]
Create a desktop shortcut (Windows — recommended)
After installing, run this once in a terminal:
aerosoltools-gui-shortcut
This places an AerosolTools shortcut (with the app icon) on your Desktop and in the Start Menu. From then on, just double-click the desktop icon — or press the Windows key and type AerosolTools — to launch the app; no terminal or Python knowledge is needed afterwards. Re-running the command simply refreshes the shortcuts.
Launch from the command line or Python
These work on any platform with the gui extra installed:
aerosoltools-gui # open the empty viewer
aerosoltools-gui data/sample_ELPI.txt # open a file on startup
python -m aerosoltools.gui # equivalent, via the module
from aerosoltools.gui import launch
launch() # empty viewer
launch("data/sample.txt") # or pre-load a file
📄 License
This project is licensed under the MIT License — see the LICENSE file for details.
🙌 Acknowledgments
Developed by the NRCWE / NFA community to standardize and accelerate aerosol data workflows.
Contributions, issues, and feature requests are very welcome!
Metadata
Release files for aerosoltools 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aerosoltools-1.0.0.tar.gz | 12.7 MB | Without provenance | Details for aerosoltools-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aerosoltools-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for aerosoltools-1.0.0-py3-none-any.whl |
Total release size: 13.3 MB
Release files / aerosoltools-1.0.0.tar.gz
| Download URL | aerosoltools-1.0.0.tar.gz |
|---|---|
| Size | 12.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36e078bd077bbb8ae2868700416b5da9713d9e9de95b356a1f2fbbcedecf727a
|
|
BLAKE2b-256 checksum How to use checksums |
05dc11a5b8df1baa8b865b1eead68144d460c9341c600f686758062c436ca307
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / aerosoltools-1.0.0-py3-none-any.whl
| Download URL | aerosoltools-1.0.0-py3-none-any.whl |
|---|---|
| Size | 550.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1c89ac977caaf4c214b7cc4dd29a1c8b97a1368e02d54f72c8335f49d87e754c
|
|
BLAKE2b-256 checksum How to use checksums |
e596672120d86012364cd30b294449fbdeea26c58b78875eb34fa15ca2be804c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for aerosoltools 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.