aerosoltools 0.2.1

Tools for loading and analyzing aerosol instrument data

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
• Alternative / legacy formats via AerosolAlt

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).

For full documentation and usage examples, see:

👉 View the documentation

---

🧰 Provided Loaders

Instrument	Function	Company
Aethalometer	Load_Aethalometer_file()	Magee Scientific
CPC	Load_CPC_file()	TSI Inc.
DiSCmini	Load_DiSCmini_file()	Testo
DustTrak	Load_DustTrak_file()	TSI Inc.
ELPI	Load_ELPI_file()	Dekati Ltd.
FMPS	Load_FMPS_file()	TSI Inc.
Fourtec	Load_Fourtec()	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
SMPS	Load_SMPS_file()	TSI Inc.

---

✨ 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 /dlogDp normalization)
  • 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

• 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

• 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)
  • Simple correlation/comparison plots

• Batch loading

  • Load_data_from_folder() to apply a loader across a folder of files

---

📦 Installation

Install from PyPI:

pip install aerosoltools

---

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",
    activity="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_list = at.Load_data_from_folder(folder_path, loader=at.Load_CPC_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!