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_alignmentmachinery, fits the relationship and returns aCalibrationModel;application (single-dataset) lives on the data object as
data.apply_calibration(model)— this module’sapply_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 clearsminimum_r_squaredare 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:
ValueErrorRaised 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). Forbasis="total"the lists hold a single element (the total-concentration fit); forbasis="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 unlessinclude_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 isTrueonly where the fit clearedminimum_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).
- property n_applied: int¶
Number of entries (bins, or the single total) actually corrected.
- Return type:
- to_dict()[source]¶
Return a JSON-safe dict (round-trips through
from_dict()).- Return type:
- 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
CalibrationModelmappingtargetontoreference.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. Useapply_calibration()(ortarget.apply_calibration(model)) to apply it, or the one-shotcalibrate_against_reference()to do both.- Parameters:
target – Dataset to be corrected.
reference – Dataset kept unchanged, whose readings
targetis mapped to.basis (str) –
"total"(default) or"per_bin".include_offset (bool) – Fit an intercept
bas well as a gainm. 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:
- 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
CalibrationModelto 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 (
datawheninplace).
- 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
targetagainstreferencein 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
targetin place (True) or return a new, calibrated copy and leavetargetuntouched (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:
- Raises:
CalibrationError – If the datasets are incompatible or lack overlap.