Merge pull request #408 from European-XFEL/feat/detectordata

Add DetectorData API

Author: philsmt

docs/calibration.md

@@ -1,7 +1,10 @@
 # Calibration constants
 
 The `extra.calibration` module helps you to find & load detector calibration
-constants stored in the [Calibration Catalog](https://in.xfel.eu/calibration/).
+data stored in the [Calibration Catalog](https://in.xfel.eu/calibration/).
+This is used for most imaging detectors in use at European XFEL to record
+and track datasets called calibration constants derived from characterization
+measurements and used for data corrections.
 
 To find constants by conditions for a particular point in time, create a
 condition object for the relevant detector type and use
@@ -69,6 +72,20 @@ agipd_cd.display_markdown_table()
 
 ::: extra.calibration.ShimadzuHPVX2Conditions
 
+## Detectors and modules
+
+Calibration data is associated with physical detector units (PDUs), with an actual
+detector consisting of one or more of these PDUs then generally called modules. PDUs
+can freely move between detectors of the same type in a process called mapping, and
+take their calibration data alongside with them.
+
+This is automatically taken into account when using the `CalibrationData` APIs described
+here, but you can also obtain the detector metadata and mapping information explicitly:
+
+::: extra.calibration.DetectorData
+
+::: extra.calibration.DetectorModule
+
 ## Bad pixel values
 
 The calibration pipeline produces masks along with corrected data, in keys

docs/changelog.md

@@ -19,6 +19,8 @@
 Added:
 
 - [AGIPDConditions][extra.calibration.AGIPDConditions] now recognizes current source constant types
+- [DetectorData][extra.calibration.DetectorData] to obtain detector metadata and
+  module mapping from the Calibration Cataloge (!408).
 - [SpectrometerCalibration][extra.gui.jupyter.SpectrometerCalibration] to
   provide a Jupyter widget for energy calibration of 2D X-ray spectrum data
   (!363).