aerosoltools.loaders.ns¶
Module Contents¶
- aerosoltools.loaders.ns.load_ns_file(file, extra_data=True)[source]¶
Load a NanoScan SMPS (NS) CSV export and return it as an
Aerosol2Dnumber-size distribution with metadata.- Parameters:
- Returns:
NanoScan size distributions with a datetime index, total concentration, size-resolved bins, and associated metadata.
- Return type:
- Raises:
FileNotFoundError – If
filedoes not exist or cannot be opened.UnicodeDecodeError – If the CSV file cannot be decoded using the encodings tried by
sniff.ValueError – If the reported data type/unit string cannot be mapped to a known NanoScan format (e.g. dN, dS, dV, dM), or if the datetime column cannot be parsed.
Notes
- Detailed description:
This loader is tailored to NanoScan SMPS CSV exports produced by the TSI AIM instrument software. The file typically contains several header rows, followed by a table with:
a
"Date Time"column,size-bin columns labelled by mid diameters (nm),
additional metadata columns (e.g. particle density).
Internally, the function:
Uses
sniffto infer file encoding and field delimiter.Reads the main data table, starting at the NanoScan data header (
header=5).Drops columns that are not part of the size distribution or time:
"File Index","Sample #", and"Total Conc".Extracts bin mid diameters from the first 13 size-bin column headers and converts them to floats. From these, it computes bin edges in nm using geometric means between adjacent mids, with fixed outer edges at 10 nm and 420 nm.
Renames
"Date Time"to"Datetime"and parses timestamps using the format"%Y/%m/%d %H:%M:%S".Selects the size-distribution columns (those matching the bin-mid labels) as numeric data.
Optionally collects all non-size-bin columns into
extra_datawhenextra_data=True, withDatetimeas the index.Reads a header line to extract the instrument serial number.
Reads the first data row to infer the data-type string (e.g.
"dN/dlogDp") and extracts particle density.Maps the data-type prefix (
"dN","dS","dV","dM") to a physical unit via a small lookup, raising aValueErrorif the type is unknown.Computes
"Total_conc"as the sum over all size bins for each time step and concatenatesDatetime,Total_concand the size-bin columns into a single DataFrame.Creates an
Aerosol2Dobject from this DataFrame and populates metadata:instrumentset to"NS",bin_edgesandbin_mids(rounded to one decimal place),density(float),serial_number,unit(string) anddtype(raw type string from header).
Calls
_convert_to_number_concentration()followed byAerosol2D.unnormalize_logdp()so that the final distribution is expressed as number concentration per bin (dN, cm⁻³) without/dlogDpnormalisation.If
extra_data=True, attaches the non-size-bin columns asextra_dataindexed byDatetime.
- Theory:
NanoScan exports can represent different moments of the particle size distribution (number, surface, volume, mass) and may be normalised by
/dlogDp. The raw type string typically encodes this, for example:dN/dlogDp— number concentration per logarithmic diameter interval,dS/dlogDp— surface-based moment,dV/dlogDp— volume-based moment,dM/dlogDp— mass-based moment.
From the two-letter prefix (
dN,dS,dV,dM), the loader assigns the corresponding unit (cm⁻³, nm²/cm³, nm³/cm³, µg/m³). The internal helper then converts any supported moment to number concentration and removes the/dlogDpnormalisation so that the resulting distribution is directly comparable to other number-size distributions in aerosoltools.- Examples:
Typical usage is to load a NanoScan CSV file and work directly with the resulting number-size distribution:
import aerosoltools as at # Load NanoScan data (keep extra metadata columns) ns = at.load_ns_file("data/NanoScan_export.csv", extra_data=True) # Inspect the first few rows print(ns.data.head()) # Check bin edges and metadata print(ns.bin_edges) print(ns.metadata) # Plot a time-integrated or mean size distribution fig, ax = ns.plot_psd()