aerosoltools.loaders.opcn3¶
Module Contents¶
- aerosoltools.loaders.opcn3.load_opcn3_file(file, extra_data=True, PM_focus=False)[source]¶
Load an OPC-N3 export and return either a size-resolved distribution (
Aerosol2D) or PM-focused time series (Aerosol1D) with metadata.- Parameters:
file (str) – Path to the OPC-N3 data file.
extra_data (bool, optional) – If
True, auxiliary channels (e.g. temperature, RH, flow, PM channels) are stored inextra_datawhen supported by the underlying loader. Defaults toTrue— everything in the file is kept.PM_focus (bool, optional) – If
True, return a compact PM-focusedAerosol1Dwith total number concentration and PM1/PM2.5/PM10 mass as reported by the instrument. IfFalse(default), return a fully size-resolvedAerosol2Dwith binned number concentrations.
- Returns:
Parsed OPC-N3 dataset as either a size-resolved number-size distribution or a PM-only time series, depending on
PM_focusand the detected file format.- Return type:
- Raises:
FileNotFoundError – If
filedoes not exist or cannot be opened.UnicodeDecodeError – If the file cannot be decoded using the encodings tried by
sniff.ValueError – If the delimiter detection or CSV parsing fails in a way that prevents reading the header or main data table.
FileFormatError – If the file format cannot be recognised from the first line and thus cannot be dispatched to a supported OPC-N3 loader.
Notes
- Detailed description:
This loader is designed for loading data from an alphasense OPC-N3 low-cost particle counter. It reads CSV formats produced by different firmware/software revisions. The formats differ mainly in how timestamps, bin labels, and PM channels are laid out.
Internally, the function:
Uses
sniffto infer file encoding and field delimiter.Reads the first line to classify the file:
Legacy/old format (few columns, typically no trailing
"OPC"marker):Detected when
len(first_line) <= 34.If
PM_focus=False(default), the file is passed to_load_opcn3_file_old(), which:parses ISO datetime strings into a
Datetimecolumn,interprets legacy bin labels (
Bin1,Bin2, …),converts raw counts to number concentration in
cm⁻³using the reported sampling period and flow,infers bin edges/mids and returns an
Aerosol2DwithDatetime,Total_conc, and one column per size bin.
If
PM_focus=True, the file is passed to_load_opcn3_file_pm_old(), which:computes
Total_concfrom the size bins,extracts PM1, PM2.5 and PM10 mass concentrations,
returns an
Aerosol1DwithDatetime,Total_conc,PM1,PM2.5andPM10.
Newer format (AIM-like structure, trailing
"OPC"in the first line):Detected when
first_line[-1] == "OPC".If
PM_focus=False, the file is passed to_load_opcn3_file_new(), which:parses ISO datetime strings from a
Datecolumn,uses a fixed set of bin edges from the OPC-N3 specification,
converts raw counts to number concentration in
cm⁻³using sampling period and flow,returns an
Aerosol2DwithDatetime,Total_concand size-bin columns.
If
PM_focus=True, the file is passed to_load_opcn3_file_pm_new(), which:computes
Total_concfrom the size bins,returns an
Aerosol1DwithDatetime,Total_conc,PM1,PM2.5andPM10.
If neither legacy nor newer patterns match, an
Exceptionis raised indicating that the OPC-N3 format is not supported.
Across all loaders:
extra_data=Truecauses selected auxiliary variables (temperature, RH, period, flow, PM channels) to be stored inextra_dataand_raw_extra_dataindexed byDatetime.Size-resolved loaders return number concentration per bin in
cm⁻³with metadata for bin edges, bin mids, density, instrument name, and dtype.PM-focused loaders return compact time series of total number concentration and PM metrics with corresponding units and dtypes.
Examples
Typical usage is to load OPC-N3 data either as a full size distribution or as a compact PM time series:
import aerosoltools as at # 1) Load full size-resolved distribution (Aerosol2D) opcn_dist = at.load_opcn3_file("data/OPCN3_legacy.csv") print(opcn_dist.data.head()) print(opcn_dist.bin_edges) print(opcn_dist.metadata) # 2) Load only total and PM metrics (multi-channel Aerosol1D) opcn_pm = at.load_opcn3_file( "data/OPCN3_legacy.csv", extra_data=True, PM_focus=True, ) print(opcn_pm.data.head()) print(opcn_pm.metadata) # 3) Plot the time-integrated size distribution fig, ax = opcn_dist.plot_psd()