aerosoltools.intercomparison.calibration

Calibrate one dataset (the target) so it agrees with a reference.

This is the calibration half of the intercomparison flow align → assess → fit → apply. Two identical instruments run side by side rarely read exactly the same; picking one as the reference and fitting a gain (optionally an offset) that maps the other onto it is a standard field correction.

The scientific work is split cleanly:

  • fitting (cross-dataset) lives here — fit_calibration() validates the pair, time-aligns them via the shared _alignment machinery, fits the relationship and returns a CalibrationModel;

  • application (single-dataset) lives on the data object as data.apply_calibration(model) — this module’s apply_calibration() is a thin pass-through so the two never diverge.

calibrate_against_reference() is the one obvious high-level entry point (re-exported as aerosoltools.calibrate_against_reference); it runs the whole workflow and returns (calibrated, model).

Two bases are supported:

  • "total" — one gain (and optional offset) from the total-concentration correlation. For a size-resolved target it corrects only the total series and leaves the individual bins untouched, so a total-only calibration never distorts the distribution.

  • "per_bin" — a separate gain (optional offset) per size bin, applied bin-by-bin. Only bins whose fit clears minimum_r_squared are corrected; weaker bins are left unchanged. Requires both datasets to be size-resolved with compatible bins.

Module Contents

aerosoltools.intercomparison.calibration.BASIS_TOTAL = 'total'
aerosoltools.intercomparison.calibration.BASIS_PER_BIN = 'per_bin'
aerosoltools.intercomparison.calibration.DEFAULT_MIN_R2 = 0.5
exception aerosoltools.intercomparison.calibration.CalibrationError[source]

Bases: ValueError

Raised when two datasets cannot be calibrated against each other.

Carries an actionable, domain-specific message (incompatible instrument class, bases, units, size bins, or insufficient overlapping data).

Initialize self. See help(type(self)) for accurate signature.

class aerosoltools.intercomparison.calibration.CalibrationModel[source]

A fitted calibration transformation plus its diagnostics.

A model maps a target dataset onto a reference by a per-quantity linear relation y = gain·x (+ offset). For basis="total" the lists hold a single element (the total-concentration fit); for basis="per_bin" they hold one element per size bin, in bin order.

Variables:
  • basis – "total" or "per_bin".

  • gains – Fitted gain(s) m.

  • offsets – Fitted offset(s) b (zero unless include_offset).

  • r_squared – Coefficient(s) of determination of the fit(s).

  • n_obs – Number of aligned observations used per fit.

  • applied – Per-entry flag — whether that gain/offset is actually applied. Always [True] for a total fit; for per-bin it is True only where the fit cleared minimum_r_squared.

  • include_offset – Whether an intercept was fitted.

  • minimum_r_squared – The per-bin acceptance gate used (basis="per_bin").

  • clip_negative – Clip calibrated concentrations at zero on application.

  • reference_instrument (target_instrument /) – Instrument names, for record.

  • reference_name (target_name /) – Human labels (e.g. GUI dataset labels).

  • reference_unit (target_unit /) – Measurement units, for record.

  • bin_mids – Size-bin midpoints (nm) the per-bin fit was computed on.

  • align – Time-alignment settings used (match/tolerance/rebin/activity).

basis: str
gains: list[float]
offsets: list[float]
r_squared: list[float]
n_obs: list[int]
applied: list[bool]
include_offset: bool = False
minimum_r_squared: float = 0.5
clip_negative: bool = True
target_instrument: str = ''
reference_instrument: str = ''
target_name: str = ''
reference_name: str = ''
target_unit: str = ''
reference_unit: str = ''
bin_mids: list[float] = []
align: dict
property n_applied: int

Number of entries (bins, or the single total) actually corrected.

Return type:

int

to_dict()[source]

Return a JSON-safe dict (round-trips through from_dict()).

Return type:

dict

classmethod from_dict(d)[source]

Reconstruct a model from to_dict() output.

Parameters:

d (dict)

Return type:

CalibrationModel

aerosoltools.intercomparison.calibration.fit_calibration(target, reference, *, basis=BASIS_TOTAL, include_offset=False, minimum_r_squared=DEFAULT_MIN_R2, match='exact', tolerance='30s', rebin_freq=None, rebin_method='mean', activity=None)[source]

Fit a CalibrationModel mapping target onto reference.

Validates the pair, time-aligns the two datasets with the shared alignment machinery, fits the relationship on the chosen basis, and returns the model without modifying either dataset. Use apply_calibration() (or target.apply_calibration(model)) to apply it, or the one-shot calibrate_against_reference() to do both.

Parameters:
  • target – Dataset to be corrected.

  • reference – Dataset kept unchanged, whose readings target is mapped to.

  • basis (str) – "total" (default) or "per_bin".

  • include_offset (bool) – Fit an intercept b as well as a gain m. Off by default — identical instruments should agree through the origin.

  • minimum_r_squared (float) – Per-bin acceptance gate (basis="per_bin" only).

  • match (str) – Time-alignment strategy ("exact"/"nearest"/"rebin").

  • tolerance – Max timestamp separation for match="nearest".

  • rebin_freq (Optional[str]) – Target cadence for match="rebin".

  • rebin_method – Aggregation for match="rebin".

  • activity (Optional[str]) – Restrict the fit to one activity’s marked periods.

Returns:

The fitted model with per-entry diagnostics.

Return type:

CalibrationModel

Raises:

CalibrationError – If the datasets are incompatible (class, units, bins) or have too little overlapping data to fit.

aerosoltools.intercomparison.calibration.apply_calibration(data, model, *, inplace=False)[source]

Apply a fitted CalibrationModel to a single dataset.

Thin pass-through to data.apply_calibration(model) so the intercomparison workflow and direct scripting share one application implementation.

Parameters:
  • data – The dataset to correct (typically the calibration target).

  • model (CalibrationModel) – A model from fit_calibration().

  • inplace (bool) – Modify data (True) or a deep copy (False, default).

Returns:

The calibrated dataset (data when inplace).

aerosoltools.intercomparison.calibration.calibrate_against_reference(target, reference, *, basis=BASIS_TOTAL, include_offset=False, minimum_r_squared=DEFAULT_MIN_R2, inplace=False, match='exact', tolerance='30s', rebin_freq=None, rebin_method='mean', activity=None)[source]

Fit and apply a calibration of target against reference in one call.

The obvious high-level entry point (re-exported as aerosoltools.calibrate_against_reference). Equivalent to:

model = fit_calibration(target, reference, ...)
calibrated = apply_calibration(target, model, inplace=inplace)
return calibrated, model
Parameters:
  • target – Dataset to be corrected.

  • reference – Dataset kept unchanged.

  • basis (str) – "total" (default) or "per_bin".

  • include_offset (bool) – Fit an intercept as well as a gain.

  • minimum_r_squared (float) – Per-bin acceptance gate (basis="per_bin").

  • inplace (bool) – Correct target in place (True) or return a new, calibrated copy and leave target untouched (False, default).

  • match (str) – Time-alignment settings (see fit_calibration()).

  • tolerance – Time-alignment settings (see fit_calibration()).

  • rebin_freq (Optional[str]) – Time-alignment settings (see fit_calibration()).

  • rebin_method – Time-alignment settings (see fit_calibration()).

  • activity (Optional[str]) – Time-alignment settings (see fit_calibration()).

Returns:

The calibrated dataset and the model

used. The dataset keeps target’s own class.

Return type:

tuple[Aerosol1D, CalibrationModel]

Raises:

CalibrationError – If the datasets are incompatible or lack overlap.