aerosoltools.loaders.aethalometer¶
Module Contents¶
- aerosoltools.loaders.aethalometer.load_aethalometer_file(file, extra_data=True)[source]¶
Load time-resolved black carbon data from an Aethalometer export file into an
aerosoltools.Aethalometerobject.- Parameters:
file (str) – Path to the Aethalometer export file (typically
.csvor.txt) containing time-resolved concentration data.extra_data (bool, optional) – If
True, non-core variables (e.g. diagnostics, sensor status or quality flags) are stored inAethalometer.extra_datawith aDatetimeindex (ambient sample temp/RH/dewpoint and flows get canonical units). IfFalse, only the main measurement channels are kept in.data. Defaults toTrue— everything in the file is kept.
- Returns:
An
Aethalometerinstance with:.datacontaining the primary BC concentration channels (at least IR/UV/blue/green/red) indexed byDatetime..metadata(.meta) populated with, e.g.:"serial_number"— Aethalometer serial number."optical_config"— optical configuration string."instrument"— set to"Aethalometer"."unit"— per-channel dict:"ng/m³"for the BC channels and""(dimensionless) for"AAE"."dtype"— per-channel dict:"dM"(mass concentration) for the BC channels and"AAE"for the Ångström exponent.
If
extra_data=True, additional columns that are not part of the core BC channels are stored in.extra_data.- Return type:
- Raises:
FileNotFoundError – If the specified
filepath does not exist.UnicodeDecodeError – If the file encoding cannot be correctly decoded using the detected encoding. Check that the file is not corrupted and matches the expected export format.
KeyError – If expected columns (e.g.
"Date / time local","Serial number","Optical config", or the BC channels) are missing or renamed in an unexpected way. Verify that the file is an unmodified Aethalometer export.ValueError – If the datetime strings in the
"Date / time local"column cannot be parsed using the expected format"%Y-%m-%dT%H:%M:%S". Check that the locale and export format match the loader assumptions.EmptyFileError – If the file is read successfully but, after dropping empty rows, no data remain (i.e. the dataset is effectively empty). This typically indicates an export problem or a file containing only headers.
Notes
- Detailed description:
This loader is tailored to Aethalometer (e.g. MicroAeth) ASCII or CSV exports produced by the vendor software. Internally, it:
Auto-detects file delimiter and encoding.
Reads the file and drops the
"Readable status"column if present, and removes fully empty rows.Extracts metadata from the first row (serial number, optical configuration) and stores it in the internal
.metadictionary.Detects the file structure: for wide exports (many columns, typically
>= 70), it standardizes verbose column names such as"Biomass BCc (ng/m^3)"and"Fossil fuel BCc (ng/m^3)"to shorter labels ("Biomass BCc","Fossil fuel BCc") and includes them along with"AAE"as core channels. For narrower exports, only the main spectral BC channels are treated as core.Builds a new
Aethalometerobject from these core columns, withDatetimeas the time index.Optionally collects all remaining non-core columns into
.extra_dataifextra_data=True.
- Theory:
The loader does not perform any transformations on the physical values themselves beyond basic type conversion; it assumes the Aethalometer has already converted raw optical attenuation to BC mass concentration (BCc) in units of
ng/m³using the manufacturer’s algorithms and calibration constants.The different color channels (IR, UV, blue, green, red) provide wavelength-resolved BC mass concentrations. Optional channels such as
"Biomass BCc"and"Fossil fuel BCc"are derived quantities based on multi-wavelength absorption (e.g. via Ångström exponent or source apportioning models) as implemented in the vendor software.
Examples
Load a single Aethalometer file
import aerosoltools as at # Load Aethalometer data with core BC channels only aeth = at.load_aethalometer_file("data/aeth_export.csv")