.. index:: measurement data model, data structure, history pickle

Measurement data models
=======================

This reference organizes mpylab's persisted data containers. It describes the
supported read interface of a measurement history, not every internal
attribute that Python happens to store when pickling a measurement class.

Basic structure
---------------

Measurement classes store several named datasets in one shared history
object. The usual access path is::

   history.<data_container>[description]

``description`` is a freely chosen name that is unique within its container.
Below it, workflows typically use numeric frequency keys in hertz and further
keys for ports, tuner positions, points, detectors, or generator levels. The
respective domain reference documents the exact order.

A description can collect several measurement acquisitions, including runs
made after the setup changed. The compact ``acquisition`` reference on each
bundled raw sample associates it with a timestamped configuration snapshot;
:doc:`history-files` defines this shared provenance structure.

Raw-data containers normally start with ``rawData``. They hold instrument
values, workflow metadata, and the provenance needed for repeated evaluation.
``processedData`` contains quantities derived from those raw values. An
evaluation does not replace or delete the raw data.

Persisted containers
--------------------

.. list-table:: Measurement-class data containers
   :header-rows: 1
   :widths: 18 34 30 18

   * - Measurement class
     - Containers
     - Content
     - Detailed reference
   * - ``TEMCell``
     - ``rawData_Verification``, ``processedData_Verification``
     - TEM-mode verification and power references
     - :doc:`tem-verification-data`
   * - ``TEMCell``
     - ``rawData_e0y``, ``processedData_e0y``
     - measured GTEM field factor
     - :doc:`tem-e0y-data`
   * - ``TEMCell``
     - ``rawData_Immunity``, ``processedData_Immunity``
     - exposure, reference selection, and EUT assessment
     - :doc:`tem-immunity-data`
   * - ``TEMCell``
     - ``rawData_Emission``, ``processedData_Emission``
     - emission scan, detectors, and field correlation
     - :doc:`tem-emission-data`
   * - ``AmplifierTest``
     - ``rawData``, ``processedData``
     - amplifier power, gain, and compression
     - :doc:`amplifier-test-data`
   * - ``MSC``
     - ``rawData_MainCal``, ``processedData_MainCal``
     - empty-chamber and loading calibration
     - :doc:`msc-calibration-data`
   * - ``MSC``
     - ``rawData_EUTCal``, ``processedData_EUTCal``
     - EUT-specific chamber calibration
     - :doc:`msc-calibration-data`
   * - ``MSC``
     - ``rawData_AutoCorr``, ``processedData_AutoCorr``
     - tuner autocorrelation and independent positions
     - :doc:`msc-calibration-data`
   * - ``MSC``
     - ``rawData_Immunity``, ``processedData_Immunity``
     - exposure, thresholds, and EUT assessment
     - :doc:`msc-immunity-emission-data`
   * - ``MSC``
     - ``rawData_Emission``, ``processedData_Emission``
     - received power and derived emission
     - :doc:`msc-immunity-emission-data`

``TEMCell`` additionally stores ``geometry``, ``uniform_areas``,
``verification_datasets``, and ``reference_datasets``. These attributes bind
geometry and provenance to the measurement history and are relevant when
interpreting verification and reference data.

Supported contract and internal state
-------------------------------------

The paths, types, units, and meanings described on these pages are supported.
Later mpylab versions may add keys. Fields marked as optional can be absent
from older pickles or another measurement mode; applications should read them
with ``mapping.get(...)``.

Runtime objects such as open files, loggers, UI adapters, and instrument
instances are not a data-reading interface. An attribute currently visible in
``__dict__`` is not a stable contract unless this reference includes it.

Established keys are not silently renamed or assigned a new technical
meaning. An unavoidable incompatible change requires a migration strategy and
an explicit versioning decision. This documentation does not introduce a
global schema version for the pickle history; individual interchange formats
or nested documents can have their own ``schema_version`` fields.

Changing the data model
-----------------------

A change to a persisted attribute, key, index, type, unit, or meaning must
update the German and English documentation in the same commit. Its virtual
runtime contract test must be updated as well. New containers must appear in
the table above.

See :doc:`../help/documentation-maintenance` for maintenance rules and check
commands. :doc:`history-files` documents pickle, autosave, and resume;
:doc:`pexplorer` explains interactive inspection of a trusted history.

Path-correction quantities keep their existing units and dictionary keys.
Newly computed corrections retain SCUQ expressions, including shared-input
and real/complex transfer dependencies, rather than independent evaluated
inputs. Their pickle representation may include the internal transfer
expression classes in ``mpylab.tools.ratio_conversion``; readers need a
version providing those classes. Existing saved numerical results are not
rewritten. See :doc:`../framework/path-corrections` for the corrected coherent
power semantics and the limits of first-order uncertainty at cancellation.