eval-ac 0.3.1__tar.gz

eval_ac-0.3.1/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.3.1] - 2026-10-06
+
+### Added
+- Documentation with Sphinx in `docs/` (theme furo, Markdown via
+  MyST): installation, user guide, Python interface with API reference
+  generated from the docstrings, description of the ABSCAL.HIS file format
+  (RPG manual, appendix A20, with byte offsets) and of the dataset, and the
+  changelog. The README sections are included, not copied, so that there
+  is only one source.
+- `.readthedocs.yaml` for hosting on Read the Docs (warnings are errors).
+- Extra `docs` in `pyproject.toml`; the extra `dev` contains the
+  documentation tools as well.
+- CI job that builds the documentation with warnings as errors.
+- Workflow `publish.yml`: a published GitHub release uploads the package
+  to PyPI, "Run workflow" uploads it to TestPyPI, both with trusted
+  publishing (no stored tokens). The workflow checks that the release tag
+  matches the package version.
+- `MANIFEST.in`: the source distribution contains the tests, their
+  example data and the changelog, so that the tests can be run from it.
+- Documentation page "Releasing" with the one-time setup of PyPI and the
+  release steps.
+- README: badge of the documentation build.
+
+### Changed
+- README: images as Markdown instead of HTML (needed for the
+  documentation; on GitHub they are now shown in full width), markers for
+  the sections included in the documentation, link to the documentation.
+- README: images and the changelog link use absolute GitHub URLs, so that
+  they are also shown in the project description on PyPI.
+
+### Fixed
+- Docstring of `calibration_drift()`: the return value was rendered as
+  return type in the API reference.
+
+## [0.3.0] - 2026-10-05
+
+### Added
+- Selection of the calibration type: by default only calibrations with
+  liquid nitrogen (`cal_type` = 1) are plotted and analysed. Entries in
+  which no receiver was calibrated with liquid nitrogen are removed; if
+  only one receiver was, the values of the other receiver are set to NaN.
+  CLI option `--all-cal-types` disables the selection. Python:
+  `eval_ac.analysis.select_cal_type()`.
+- Quality flags: channels with `calibration_flag` = 0 (not calibrated) are
+  marked with a red cross in the history plot, excluded from the drift
+  analysis and listed in the report if they belong to the latest
+  calibration. Python: `eval_ac.analysis.latest_not_calibrated()`.
+- Drift analysis: the latest calibration of each receiver is compared with
+  the median of the `N` calibrations before it (deviation in percent).
+  Python: `eval_ac.analysis.calibration_drift()` and
+  `eval_ac.analysis.drift_exceedances()`. Default thresholds: gain 10 %,
+  noise diode temperature 2.5 %, system noise temperature 2.5 %,
+  non-linearity factor 0.5 % (about the 99th percentile of the example
+  data, adapt them to the instrument).
+- Drift plot in the style of the history plot (`results_ln2_drift.png`),
+  Python: `eval_ac.plotting.plot_drift()`.
+- CLI options `-d/--drift-plot`, `--n-reference`, `-t/--threshold
+  VARIABLE=PERCENT` (repeatable), `--max-age DAYS` and
+  `--fail-on-warning` (exit code 2 if the report contains a warning).
+- CLI prints a quality report of the latest calibration of each receiver:
+  date and age, channels with flag 0, alpha out of range and drift.
+- Age check: warning if the latest calibration of a receiver is older than
+  183 days (RPG recommends an absolute calibration every 5 to 6 months,
+  manual section 3.1.3). The age is computed from `time_of_rec_1/2` of the
+  respective receiver. Python: `eval_ac.analysis.calibration_age()`.
+- Range check of the non-linearity factor: warning if alpha of the latest
+  calibration is outside 0.9 <= alpha < 1 (manual section 3.1.3.1).
+  Python: `eval_ac.analysis.alpha_out_of_range()`.
+- README section "Interpreting the results" based on the RPG manual
+  (RPG-MWR-STD-SW): meaning and operational use of G, Tsys, Tn and alpha,
+  typical patterns in the drift plot, what to do with a suspicious
+  calibration, how to adapt the thresholds and limitations.
+- Tests with modified copies of the example file (other calibration
+  types, flag 0, time stamps, alpha); 47 tests in total. The tests do not
+  depend on the current date.
+
+### Changed
+- History plot: latest and previous calibration are determined per
+  receiver, so a receiver that was not calibrated with liquid nitrogen in
+  the latest entry shows its own latest calibration.
+- History plot: one legend per receiver below the panels instead of one in
+  every panel, so that the legend never hides data.
+- `--no-plot` now suppresses both plots.
+- The NetCDF file (`--netcdf`) still contains all calibration types.
+
+### Fixed
+- `calibration_flag` comment: the flag is 0 = not calibrated,
+  1 = calibrated per channel (RPG manual, appendix A20), not an 8 bit
+  array.
+- `alpha`: comment with the detector model and the valid range added.
+
+## [0.2.0] - 2026-10-05
+
+### Added
+- Command line interface `eval-ac` (also `python -m eval_ac`):
+  `eval-ac ABSCAL.HIS --netcdf abscal.nc --plot results_ln2_cal.png`.
+  Options `--no-plot`, `--show` and `--version`. Errors (missing file,
+  invalid file) are reported as one line on stderr with exit code 1.
+- Functional API: `read_abscal_his()`, `write_netcdf()`, `read_raw()`,
+  `records_to_dataset()` in `eval_ac.convert_abscal_his` and
+  `plot_calibration_history()` in the new module `eval_ac.plotting`.
+- Coordinate `time` (datetime of each calibration, decoded from
+  `time_of_rec_1`, seconds since 2001-01-01).
+- Coordinate `receiver` (1 or 2) along `freq`, derived from the channel
+  numbers stored in the file.
+- Validation of the input file: file code (39583209), length of every
+  record, truncated files, and identical channels in all entries.
+- Tests (pytest) for reader, NetCDF output, plotting and CLI, including a
+  regression test against the output of version 0.1.0
+  (`example_data/abscal.nc`).
+- `pyproject.toml` with the entry point `eval-ac` and the extras `test`
+  and `dev`.
+- `CHANGELOG.md`.
+
+### Changed
+- `HatproBinAbscalHis(filename, filename_out=None)`: the NetCDF file is
+  only written if `filename_out` is given. Before, the output file was
+  mandatory.
+- `HatproBinAbscalHis.header` now holds plain integers
+  (`{'file_code': 39583209, 'n_samples': 16}`) instead of numpy arrays, and
+  the key `_n_samples` is renamed to `n_samples`. `HatproBinAbscalHis.data`
+  is now a list with one dictionary per calibration entry.
+- The reader reads the file once into memory and parses it with explicit
+  little-endian types instead of calling `np.fromfile` for every value.
+  The values are identical to version 0.1.0 (checked by a test).
+- Plot: the split into the two receivers is taken from the file instead of
+  fixed channel indices 0-6 / 7-13. The plot works for any number of
+  calibration entries (before, at least four were needed). The legend shows
+  the dates of the latest and previous calibration, the axes are labelled
+  with name and unit.
+- `evaluate_absolute_calibration.py` no longer contains hard coded paths
+  and no longer runs on import. It now calls the CLI, i.e.
+  `python eval_ac/evaluate_absolute_calibration.py ABSCAL.HIS`.
+- Global NetCDF attributes follow CF/ACDD names: `Conventions` (was
+  `conventions`), `date_created` in ISO 8601 (was `date of creation`), new
+  `title`. `history` contains time stamp, source file and eval_ac version.
+  The empty attribute `comments` was removed.
+- CI: tests and a CLI run are executed on every push/PR, Python 3.9-3.12,
+  `actions/checkout@v4` and `actions/setup-python@v5`. Pylint checks
+  `eval_ac` and `tests`.
+- Minimum Python version is 3.9 (was 3.8; Python 3.8 is end of life).
+- The example plot moved to `docs/images/results_ln2_cal.png`.
+
+### Fixed
+- The test called the class with one argument although two were required
+  and depended on the working directory; it was not run in CI.
+- `long_name` of `cold_load_temp_1/2` said "hot load".
+- Invalid CF `standard_name` "reveiver gain" of `gain` removed.
+- Unit of the non-linearity factor `alpha` changed from `K` to `1`
+  (dimensionless).
+- Typo "micorwave" in the `source` attribute.
+- `datetime.utcnow()` (deprecated since Python 3.12) replaced.
+- `datetime` removed from the dependencies (it is part of the standard
+  library); `netCDF4` added (needed to write NetCDF files).
+- Version numbers were inconsistent (`setup.py`: 1.0, `__init__.py`:
+  0.1.0); the version is now only defined in `eval_ac/__init__.py`.
+- README: download badge pointed to a foreign repository.
+
+### Removed
+- `setup.py` (replaced by `pyproject.toml`). Install with `pip install .`
+  instead of `python setup.py install`.
+- Duplicate `results_ln2_cal.png` in the repository root and in the
+  package directory.
+
+### Migration from 0.1.0
+| 0.1.0 | 0.2.0 |
+| --- | --- |
+| edit paths in `evaluate_absolute_calibration.py`, run it | `eval-ac ABSCAL.HIS --netcdf abscal.nc` |
+| `python setup.py install` | `pip install .` |
+| `HatproBinAbscalHis(f_in, f_out).xrdata` | `read_abscal_his(f_in)` (+ `write_netcdf(ds, f_out)`) |
+| `obj.header['_n_samples'][0]` | `obj.header['n_samples']` |
+| `ds.attrs['conventions']` | `ds.attrs['Conventions']` |
+
+The distribution name changed from `evaluation-of-absolute-calibration-results`
+to `eval-ac`; the import name `eval_ac` is unchanged.
+
+## [0.1.0]
+
+- First version: reading of ABSCAL.HIS, conversion to NetCDF and plot of
+  the calibration history.

eval_ac-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Andreas Foth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eval_ac-0.3.1/MANIFEST.in

@@ -0,0 +1,5 @@
+# files of the source distribution (sdist) in addition to the package,
+# so that the tests can be run from the sdist
+include CHANGELOG.md
+recursive-include tests *.py
+include example_data/ABSCAL.HIS example_data/abscal.nc

eval_ac-0.3.1/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: eval-ac
+Version: 0.3.1
+Summary: Read the ABSCAL.HIS file of RPG microwave radiometers (e.g. HATPRO) and visualize the history of the absolute calibration with liquid nitrogen.
+Author-email: Andreas Foth <andreas.foth@uni-leipzig.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/WillyWallace/eval_ac
+Project-URL: Documentation, https://eval-ac.readthedocs.io
+Project-URL: Issues, https://github.com/WillyWallace/eval_ac/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: matplotlib
+Requires-Dist: netCDF4
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: sphinx>=7; extra == "dev"
+Requires-Dist: myst-parser>=2; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Dynamic: license-file
+
+[![Python package](https://github.com/WillyWallace/eval_ac/actions/workflows/python-package.yml/badge.svg)](https://github.com/WillyWallace/eval_ac/actions/workflows/python-package.yml)
+[![Pylint](https://github.com/WillyWallace/eval_ac/actions/workflows/pylint.yml/badge.svg)](https://github.com/WillyWallace/eval_ac/actions/workflows/pylint.yml)
+[![Documentation Status](https://readthedocs.org/projects/eval-ac/badge/?version=latest)](https://eval-ac.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Github all releases](https://img.shields.io/github/downloads/WillyWallace/eval_ac/total.svg)](https://github.com/WillyWallace/eval_ac/releases/)
+[![Open Source? Yes!](https://badgen.net/badge/Open%20Source%20%3F/Yes%21/blue?icon=github)](https://github.com/Naereen/badges/)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/WillyWallace/eval_ac/graphs/commit-activity)
+![Mastodon Follow](https://img.shields.io/mastodon/follow/109461236453474330?domain=https%3A%2F%2Fmeteo.social&logoColor=%230066cc&style=social)
+
+<!-- [![Release][release-shield]][release-url] -->
+<!-- [![PyPi version](https://badgen.net/pypi/v/pip/)](https://pypi.com/project/pip) -->
+
+<!-- [![Twitter](https://img.shields.io/twitter/follow/RSAtmos_LIM?style=for-the-badge)](https://twitter.com/RSAtmos_LIM) -->
+
+# Read the ABSCAL.HIS file and visualize the results of the absolute calibration with liquid nitrogen of an RPG microwave radiometer
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#Introduction">Introduction</a></li>
+    <li><a href="#getting-started">Getting Started</a></li>
+    <li><a href="#Usage">Usage</a></li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <!-- <li><a href="#contributing">Contributing</a></li> -->
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+    <li><a href="#acknowledgments">Acknowledgments</a></li>
+  </ol>
+</details>
+
+<!-- Introduction -->
+## Introduction
+
+📖 **Documentation:** https://eval-ac.readthedocs.io (user guide, Python API, ABSCAL.HIS file format)
+
+This repository was created to display the results of the absolute calibration with liquid nitrogen of the microwave radiometer HATPRO manufactured by Radiometer Physics GmbH. For this purpose, the binary file ABSCAL.HIS is read in and converted into an xarray. Then the receiver gain, the temperature of the noise diode, the temperature of the system noise and the non-linearity factor are displayed in comparison to the previous and other prior calibrations.
+
+<!-- GETTING STARTED -->
+## Getting Started
+
+### Installation
+
+<!-- docs-installation-start -->
+eval_ac requires Python 3.9 or newer. The dependencies (numpy, xarray, matplotlib, netCDF4) are installed automatically.
+
+1. Clone the repo
+   ```sh
+   git clone https://github.com/WillyWallace/eval_ac.git
+   cd eval_ac
+   ```
+
+2. Install the package
+   ```sh
+   pip install .
+   ```
+   For development (editable install with test and lint tools):
+   ```sh
+   pip install -e ".[dev]"
+   ```
+<!-- docs-installation-end -->
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- USAGE EXAMPLES -->
+## Usage
+
+<!-- docs-usage-start -->
+### Command line
+
+```sh
+eval-ac path/to/ABSCAL.HIS --netcdf abscal.nc
+```
+
+This writes the NetCDF file, the history plot `results_ln2_cal.png`, the drift plot `results_ln2_drift.png` and prints a short quality report of the latest calibration:
+
+```text
+read 16 calibration entries from path/to/ABSCAL.HIS
+16 of them are calibrations with liquid nitrogen
+receiver 1: latest calibration 2026-04-29 (159 days ago)
+receiver 2: latest calibration 2026-04-29 (159 days ago)
+drift: all channels of the latest calibration are within the thresholds
+```
+
+Lines starting with `warning:` point to something that should be checked, see [Quality checks](#quality-checks).
+
+| Option | Description |
+| --- | --- |
+| `input` | path of the ABSCAL.HIS file (required) |
+| `-n`, `--netcdf FILE` | write the converted data (all calibration types) to a NetCDF file |
+| `-p`, `--plot FILE` | file name of the history plot (default: `results_ln2_cal.png`) |
+| `-d`, `--drift-plot FILE` | file name of the drift plot (default: `results_ln2_drift.png`) |
+| `--no-plot` | do not create any plot |
+| `--show` | additionally show the plots in a window |
+| `--all-cal-types` | use all calibrations instead of only those with liquid nitrogen |
+| `--n-reference N` | number of calibrations before the latest one forming the drift reference (default: 5) |
+| `-t`, `--threshold VAR=PERCENT` | drift threshold, e.g. `-t gain=8 -t temp_sys=2`; variables: `gain`, `temp_noise`, `temp_sys`, `alpha` |
+| `--max-age DAYS` | warn if the latest calibration of a receiver is older (default: 183 days) |
+| `--fail-on-warning` | exit with code 2 if the report contains a warning (e.g. for cron jobs) |
+| `--version` | print the version |
+
+`python -m eval_ac ...` works as well. Try it with the example file:
+
+```sh
+eval-ac example_data/ABSCAL.HIS
+```
+
+#### History plot
+
+The plot shows the receiver gain, the noise diode temperature, the system noise temperature and the non-linearity factor of both receivers. The latest and the previous calibration of each receiver are highlighted with their dates, all older calibrations are drawn in grey. Channels that were not calibrated (`calibration_flag` = 0) are marked with a red cross. By default, only calibrations with liquid nitrogen are used (`cal_type` = 1); if only one receiver of an entry was calibrated with liquid nitrogen, only this receiver is used.
+
+![History plot of the example data](https://raw.githubusercontent.com/WillyWallace/eval_ac/main/docs/images/results_ln2_cal.png)
+
+#### Drift plot
+
+For each receiver, the latest calibration is compared with the median of the 5 calibrations before it (deviation in percent). Channels that were not calibrated are excluded. The dashed red lines are the thresholds, channels of the latest calibration exceeding them are circled and listed in the report. The grey lines show how far the older calibrations deviate from the same reference.
+
+The y-axis is scaled to the thresholds and to the latest and previous calibration. Large outliers of older calibrations are therefore cut off at the edge of the panel; they are still visible in the history plot.
+
+![Drift plot of the example data](https://raw.githubusercontent.com/WillyWallace/eval_ac/main/docs/images/results_ln2_drift.png)
+
+#### Quality checks
+
+The report checks the latest calibration of each receiver (only calibrations with liquid nitrogen, unless `--all-cal-types` is given):
+
+| Check | Warning if | Background |
+| --- | --- | --- |
+| Age | the latest calibration is older than `--max-age` days (default 183) | RPG recommends an absolute calibration every 5 to 6 months and after transport (manual, section 3.1.3). The age is computed from the calibration time of each receiver. |
+| Flag | a channel has `calibration_flag` = 0 | The channel was not calibrated (manual, appendix A20). |
+| Non-linearity factor | α is outside 0.9 ≤ α < 1 | Valid range of the detector model (manual, section 3.1.3.1, equation 1). Channels with flag 0 are not checked. |
+| Drift | the deviation from the reference exceeds the threshold | See [Drift plot](#drift-plot) and [Interpreting the results](#interpreting-the-results). |
+
+With `--fail-on-warning`, eval-ac exits with code 2 if any check gives a warning, e.g. to send an e-mail from a cron job:
+
+```sh
+eval-ac /data/ABSCAL.HIS --no-plot --fail-on-warning || echo "check calibration" | mail -s "HATPRO" me@example.org
+```
+
+### Interpreting the results
+
+The report and the drift plot point to calibrations that deserve a closer look; they do not decide whether a calibration is good or bad. That decision needs the knowledge of the instrument and of the calibration conditions. The background below is taken from the RPG manual *Principle of Operation & Software (standard radiometers)*, RPG-MWR-STD-SW (cited as "manual, section …").
+
+#### What the absolute calibration determines
+
+During the absolute calibration the radiometer looks at the internal ambient target and at the external liquid nitrogen cooled target, each with and without additional noise from the noise diode. From these four measurements it determines four parameters per channel (manual, section 3.1.3.1):
+
+| Variable | Meaning | Use between two absolute calibrations |
+| --- | --- | --- |
+| `gain` (G) | receiver gain [V/K] | Very sensitive to small changes of the physical temperature of the receiver; it is recalibrated regularly with the ambient target (gain calibration, manual, section 3.3). |
+| `temp_sys` (T<sub>sys</sub>) | system noise temperature [K] | Recalibrated together with G using the noise diode and the ambient target (manual, section 3.1.3.1). Changes of the temperature of the receiver optics (e.g. the feedhorn) change T<sub>sys</sub> (manual, section 3.1.3.2). |
+| `temp_noise` (T<sub>n</sub>) | equivalent temperature of the noise diode [K] | Used as **secondary standard** for all automatic calibrations until the next absolute calibration; it is assumed to be stable (manual, section 3.1.3.1). In transparent channels it can also be recalibrated by sky tipping (manual, section 4.9.1). |
+| `alpha` (α) | non-linearity factor of the detector, U = G·P<sup>α</sup> with 0.9 ≤ α < 1 | Assumed to be constant until the next absolute calibration (manual, section 3.1.3.1). |
+
+**Consequences for the evaluation**
+
+- Changes of **T<sub>n</sub>** and **α** are the most relevant: until the next absolute calibration, every automatic calibration builds on them. A real change of T<sub>n</sub> that is not captured by a new absolute calibration enters the measured brightness temperatures.
+- Differences of the **gain** between absolute calibrations are expected, because the gain follows the receiver temperature and is recalibrated during operation anyway. Its default threshold is therefore larger. In the example data the gain varies much more than the other variables (standard deviation 1–3 % in the K-band and 5–18 % in the V-band, compared with below 2 % for T<sub>n</sub> and T<sub>sys</sub>).
+- ABSCAL.HIS also contains successful sky tipping calibrations (manual, section 4.6). They use a different method and are only possible in transparent channels, so eval_ac compares only calibrations with liquid nitrogen by default.
+
+#### Why the median of the previous calibrations?
+
+A single failed calibration in the reference would shift a mean, but hardly the median. The previous calibration is part of the reference, so its deviation is usually small.
+
+#### Typical patterns
+
+These are rules of thumb, not statements of the manual:
+
+| Pattern in the drift plot | Possible meaning |
+| --- | --- |
+| Latest within the thresholds, similar to the grey lines | Calibration consistent with the history. |
+| Single channels of the latest calibration out of the thresholds, previous calibration normal | Possibly a problem during this calibration, e.g. with the cold target (filling, condensation; the manual asks to let the target dry before the V-band part, section 4.8). Check the calibration conditions and consider repeating the calibration. |
+| All channels of a receiver shifted in the same direction | Rather a change of the receiver or of its noise diode than a single failed calibration, e.g. after maintenance or transport. |
+| Latest and previous calibration deviate in the same way | The change is confirmed by two calibrations and is probably real; the reference (the 5 calibrations before) still describes the old state. |
+| Channels marked as "not calibrated" (flag 0) | These channels were not calibrated in this entry (manual, appendix A20); they are not evaluated. |
+
+#### What to do with a suspicious calibration
+
+- Check that the absolute calibration was done after a warm-up of at least 30 minutes; it is recommended every 5 to 6 months and after transport (manual, section 3.1.3).
+- Repeat the calibration if the conditions were doubtful.
+- A bad calibration can be removed in the RPG host software: in the *Absolute Calibration History* menu, *Delete Last Entries* removes all entries after the marked one, and *Generate a new calibration file* creates an ABSCAL.CLB from selected calibrations of receiver 1 and 2 (manual, section 4.6).
+
+#### Adapting the thresholds
+
+The default thresholds are derived from a single HATPRO (2018–2026, 16 calibrations). Instruments, channels and sites differ, so:
+
+1. run `eval-ac` on the full history of your instrument,
+2. look at the spread of the grey lines in the drift plot,
+3. set thresholds slightly above the usual spread, e.g. `-t gain=6 -t temp_noise=1.5`.
+
+#### Limitations
+
+- With fewer than 5 earlier calibrations, the reference consists of fewer values (see `n_reference_used` in the result of `calibration_drift()`); with none, no drift can be computed.
+- The drift is relative to the previous calibrations. A slow drift over many calibrations shifts the reference as well and is better seen in the history plot.
+
+<!-- docs-usage-end -->
+### Python
+
+<!-- docs-python-start -->
+```python
+from eval_ac.convert_abscal_his import read_abscal_his, write_netcdf
+from eval_ac.analysis import select_cal_type, calibration_drift, drift_exceedances
+from eval_ac.plotting import plot_calibration_history, plot_drift
+
+ds = read_abscal_his("ABSCAL.HIS")   # xarray.Dataset, all calibration types
+write_netcdf(ds, "abscal.nc")
+
+ln2 = select_cal_type(ds)            # only calibrations with liquid nitrogen
+fig = plot_calibration_history(ln2, variables=["gain", "temp_sys"])
+fig.savefig("gain_tsys.png")
+
+drift = calibration_drift(ln2, n_reference=5)
+for row in drift_exceedances(drift, thresholds={"gain": 8}):
+    print(row)
+plot_drift(drift, thresholds={"gain": 8}).savefig("drift.png")
+```
+
+The dataset has the dimensions `n_samples` (calibration entries, oldest first) and `freq` (channels). The coordinate `time` holds the date of each calibration, the coordinate `receiver` (1 or 2) assigns each channel to its receiver.
+
+<!-- docs-python-end -->
+### Running the tests
+
+<!-- docs-tests-start -->
+```sh
+pip install -e ".[test]"
+pytest
+```
+<!-- docs-tests-end -->
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- ROADMAP -->
+## Roadmap
+
+- [x] add meaningful docstrings
+- [x] make documentation with Sphinx (`docs/`)
+- [x] host the documentation on readthedocs
+- [x] enable pip install ...
+- [ ] publish on PyPI
+- [ ] Released version 1
+- [x] Add Tests
+
+See the [open issues](https://github.com/WillyWallace/eval_ac/issues) for a full list of proposed features (and known issues) and [CHANGELOG.md](https://github.com/WillyWallace/eval_ac/blob/main/CHANGELOG.md) for the changes of each version.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- LICENSE -->
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- CONTACT -->
+## Contact
+
+[Andreas Foth](https://www.uni-leipzig.de/personenprofil/mitarbeiter/dr-andreas-foth)
+
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- ACKNOWLEDGMENTS -->
+## Acknowledgments
+
+Special thanks for templates and help during implementation.
+
+* [Readme Template](https://github.com/othneildrew/Best-README-Template)
+* [cloudnetpy GitHub](https://github.com/actris-cloudnet/cloudnetpy.git)
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+