{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# 10b — Calibration\n", "\n", "**Theme:** turning a measured disagreement into a correction, and applying it.\n", "\n", "[10a](10a-correlation-and-agreement.ipynb) established that two NanoScans\n", "disagree by roughly 20%. This notebook fits that relationship as a calibration\n", "model and applies it, so one instrument is expressed on the other's scale.\n", "\n", "A calibration is only as good as the reference. Calibrating against another\n", "field instrument makes the two *consistent*; it does not make either *correct*." ], "id": "cell-00" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import aerosoltools as at\n", "from aerosoltools.intercomparison import (\n", " CalibrationModel,\n", " apply_calibration,\n", " fit_calibration,\n", ")\n", "\n", "target = at.load_ns_file(\"../../tests/data/Combine_example_NS.csv\")\n", "reference = at.load_ns_file(\"../../tests/data/Correlation_example_NS2.csv\")" ], "id": "cell-01" }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Fitting a model\n", "\n", "`fit_calibration` compares the target against the reference and returns a\n", "`CalibrationModel`. The time-alignment arguments are the same as in 10a." ], "id": "cell-02" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "model = fit_calibration(\n", " target, reference,\n", " basis=\"total\",\n", " match=\"nearest\",\n", " tolerance=\"45s\",\n", ")\n", "model" ], "id": "cell-03" }, { "cell_type": "markdown", "metadata": {}, "source": [ "The model records what was fitted and how well." ], "id": "cell-04" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(\"basis :\", model.basis)\n", "print(\"gain :\", round(model.gains[0], 4))\n", "print(\"offset :\", model.offsets[0])\n", "print(\"R squared :\", round(model.r_squared[0], 4))\n", "print(\"observations :\", model.n_obs[0])\n", "print(\"target unit :\", model.target_unit)\n", "print(\"reference unit :\", model.reference_unit)" ], "id": "cell-05" }, { "cell_type": "markdown", "metadata": {}, "source": [ "A gain of about 1.2 means the target reads roughly 20% low relative to the\n", "reference, so correcting it multiplies by 1.2.\n", "\n", "## Gain only, or gain and offset\n", "\n", "By default the fit is proportional — gain only, no offset — because a particle\n", "counter reading zero in clean air should stay at zero. `include_offset=True`\n", "allows a constant shift when there is reason to expect one." ], "id": "cell-06" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "with_offset = fit_calibration(\n", " target, reference, basis=\"total\",\n", " include_offset=True, match=\"nearest\", tolerance=\"45s\",\n", ")\n", "\n", "print(f\"gain only : gain {model.gains[0]:.4f}, \"\n", " f\"offset {model.offsets[0]:.1f}, R2 {model.r_squared[0]:.4f}\")\n", "print(f\"with offset : gain {with_offset.gains[0]:.4f}, \"\n", " f\"offset {with_offset.offsets[0]:.1f}, R2 {with_offset.r_squared[0]:.4f}\")" ], "id": "cell-07" }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Refusing a bad fit\n", "\n", "`minimum_r_squared` guards against applying a calibration built on a\n", "relationship that is not there. Below the threshold the model is not marked as\n", "applied, and `applied` records that." ], "id": "cell-08" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "strict = fit_calibration(\n", " target, reference, basis=\"total\",\n", " minimum_r_squared=0.95,\n", " match=\"nearest\", tolerance=\"45s\",\n", ")\n", "\n", "print(f\"R squared {strict.r_squared[0]:.4f} vs threshold 0.95\")\n", "print(\"applied:\", strict.applied)" ], "id": "cell-09" }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Applying a model\n", "\n", "`apply_calibration` is a method on the dataset. It returns a corrected copy by\n", "default; `inplace=True` modifies the object." ], "id": "cell-10" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "calibrated = target.apply_calibration(model)\n", "\n", "print(f\"before: mean {target.total_concentration.mean():10.1f} {target.unit}\")\n", "print(f\"after : mean {calibrated.total_concentration.mean():10.1f} {calibrated.unit}\")\n", "print(f\"ratio : {calibrated.total_concentration.mean() / target.total_concentration.mean():.4f}\")" ], "id": "cell-11" }, { "cell_type": "markdown", "metadata": {}, "source": [ "The corrected instrument should now sit on the 1:1 line against the reference." ], "id": "cell-12" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "\n", "fig, axs = plt.subplots(ncols=2, figsize=(12, 5))\n", "\n", "at.plot_correlation(target, reference, ax_in=axs[0],\n", " match=\"nearest\", tolerance=\"45s\")\n", "axs[0].set_title(\"Before calibration\")\n", "\n", "at.plot_correlation(calibrated, reference, ax_in=axs[1],\n", " match=\"nearest\", tolerance=\"45s\")\n", "axs[1].set_title(\"After calibration\")\n", "\n", "plt.tight_layout()" ], "id": "cell-13" }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Fit and apply in one step\n", "\n", "When you do not need the intermediate model, `calibrate_against_reference` does\n", "both and returns the corrected dataset together with the model it used." ], "id": "cell-14" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "corrected, used_model = at.calibrate_against_reference(\n", " target, reference,\n", " basis=\"total\",\n", " match=\"nearest\",\n", " tolerance=\"45s\",\n", ")\n", "\n", "print(f\"gain applied: {used_model.gains[0]:.4f}\")\n", "print(f\"mean {target.total_concentration.mean():.1f} -> \"\n", " f\"{corrected.total_concentration.mean():.1f} {corrected.unit}\")" ], "id": "cell-15" }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Calibrating per size bin\n", "\n", "`basis=\"total\"` fits one gain for the whole instrument. Size-resolved\n", "instruments can instead be calibrated bin by bin, with `basis=\"bins\"`, which\n", "corrects a distribution whose *shape* is wrong rather than just its magnitude.\n", "Each bin then carries its own gain, and `bin_mids` records which diameter each\n", "belongs to.\n", "\n", "## Reusing a calibration\n", "\n", "A `CalibrationModel` is a plain record of the fit, so it can be kept and\n", "applied to later measurements from the same instrument — the usual workflow\n", "when one side-by-side run calibrates a whole campaign." ], "id": "cell-16" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(\"This model can be applied to any dataset from the same instrument:\")\n", "print(f\" instrument : {model.target_instrument}\")\n", "print(f\" gain : {model.gains[0]:.4f}\")\n", "print(f\" fitted on : {model.n_obs[0]} paired observations\")\n", "print(f\" alignment : {model.align}\")" ], "id": "cell-17" }, { "cell_type": "markdown", "metadata": {}, "source": [ "---\n", "\n", "**Next:** the instrument-specific notebooks, starting with\n", "[11 — Simple instruments](11-simple-instruments.ipynb)." ], "id": "cell-18" } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.11" } }, "nbformat": 4, "nbformat_minor": 5 }