pysp2.io.read_sp2xr_pbp#

pysp2.io.read_sp2xr_pbp(file_name, keep_firmware_calibration=False)[source]#

Read a SP2-XR Particle-by-Particle (PbP) CSV or ZIP file into an xarray Dataset.

The SP2-XR firmware performs peak fitting on-board, so the PbP file already contains per-particle peak heights, positions, FWHMs, transit times, and pre-calibrated optical diameter / BC mass. This reader maps the peak-fit outputs to PySP2-style names (PkHt_ch0, PkHt_ch1, …) so that the dataset can be fed into PySP2 calibration utilities (e.g. pysp2.util.calc_diams_masses) with appropriate SP2-XR coefficients.

By default, the pre-calibrated ‘Scatter Size (nm)’ and ‘Incand Mass (fg)’ columns are dropped to encourage recalibration with consistent curves. Pass keep_firmware_calibration=True to retain them as ‘firmware_ScatterSize_nm’ and ‘firmware_IncandMass_fg’; in that case the scattering / incandescence calibration CSVs (’_Scatt_.csv’ and ‘_Incan_.csv’) are auto-located alongside the PbP file and attached as dataset attributes for provenance.

Absolute particle datetimes are derived from the matching SP2-XR HK file, which is auto-located in the same directory. Each acquisition session writes one HK file (always _x0001) and one or more PbP files; the HK provides the wall-clock reference that converts the PbP instrument seconds to UTC. If no matching HK file is found, a warning is emitted and the dataset is returned without an absolute ‘time’ coordinate.

Parameters:

  • file_name (str) – Path to the PbP CSV or ZIP file.

  • keep_firmware_calibration (bool) – If True, retain the SP2-XR firmware’s ‘Scatter Size (nm)’ and ‘Incand Mass (fg)’ as ‘firmware_ScatterSize_nm’ and ‘firmware_IncandMass_fg’. Default False.

Returns:

pbp_ds (xarray.Dataset) – Per-particle data indexed by ‘event_index’. Variable names follow PySP2 conventions for peak fit outputs (PkHt_ch0, PkHt_ch1, PkFWHM_ch0, …), with SP2-XR-specific columns kept under descriptive names (ScatTransitTime, IncTransitTime, IncanDelay, ParticleFlags).