.. index:: TEM immunity, immunity data structure, TEMCell

TEM immunity data
=================

This page documents the persisted paths of the TEM/GTEM workflow. See
:doc:`immunity-results` for the domain meaning and assessment of EUT events.

A dataset is addressed by name::

   raw = history.rawData_Immunity[description]
   result = history.processedData_Immunity[description]

Raw data and run contract
-------------------------

Measurements use two parallel paths::

   raw["power"][frequency][position][0][attempt]
   raw["eutstatus"][frequency][position][0][attempt]

``frequency`` is a numeric frequency value in Hz, ``position`` is the EUT
orientation, and ``attempt`` indexes an initial or repeated attempt. The ``0``
level is the currently sole port index and readers must nevertheless include
it.

A ``power`` entry contains ``value``, ``pfwd``, ``pbwd``, ``testfield``,
``am_enabled``, and ``am_modulation``. For historical reasons, ``value`` is
again the mapping of measured quantities. ``pfwd`` and ``pbwd`` are power
quantities and ``testfield`` is a field-strength quantity. ``leveling_*`` keys
are added according to the leveling strategy.

An ``eutstatus`` entry contains at least ``value``, ``pfwd``, and ``pbwd``.
The current workflow adds ``testfield``, ``am_enabled``, ``am_modulation``,
and ``eut_event``, plus optional ``leveling_*`` keys. ``value`` is the
legacy-compatible EUT status; ``eut_event`` is the structured event.

``exposure_status[frequency][position]`` has ``status``, ``reason``,
``detail``, and ``testfield``. Relevant status values are ``completed``,
``retry_pending``, ``not_evaluated``, ``observation_pending``, and
``not_executed``. The last value is stored, for example, when amplifier
protection is triggered. ``monitor_diagnostics`` is a list of EUT-monitoring
error and status records.

.. list-table:: Important workflow and provenance fields
   :header-rows: 1
   :widths: 34 66

   * - Key
     - Meaning
   * - ``requested_frequencies``, ``requested_positions``
     - Planned scope used for completeness checking.
   * - ``reference_selection``, ``reference_summary``
     - Selected TEM verification and summary of its suitability.
   * - ``immunity_target_efield``
     - Required field strength as a quantity.
   * - ``immunity_reference_power_selection``
     - Selected or interpolated reference power for each frequency.
   * - ``am_headroom_policy``, ``am_modulation``
     - Protection/evidence policy and AM parameters actually configured.
   * - ``position_coverage``
     - Validation of required EUT orientations.
   * - ``performance_criterion``, ``eut_event_policy``
     - Assessment criterion and actions for monitor events.
   * - ``post_exposure_timeout``
     - Observation duration after the disturbance is switched off.
   * - ``measurement_graph_mode``
     - Logical graph context used, normally ``"GTEM"``.
   * - ``immunity_run_contract``
     - Stable snapshot of settings that must remain unchanged when resuming
       from autosave.
   * - ``mg``
     - Persisted measurement-graph description, not an open device connection.

``immunity_run_contract`` is an independently versioned subdocument. Its
current ``schema_version`` is ``2``. It stores quantities as mappings with
``__quantity__``, ``value``, ``uncertainty``, and ``unit`` so settings can be
compared stably. This field does not replace SCUQ quantities in measurement
data.

Processed data
--------------

The primary result path is::

   result["result"][frequency][position][attempt]

Each attempt contains ``eutstatus``, ``eut_event``, ``passed``, ``effective``,
``testfield``, ``pfwd``, ``pbwd``, ``am_enabled``, and ``am_modulation``.
``leveling`` is optional. Only the last attempt for a position has
``effective == True``; older attempts remain for traceability. Under criterion
A, an earlier impairment can still affect the overall assessment after a
later passing attempt.

.. list-table:: Top-level keys of ``processedData_Immunity[description]``
   :header-rows: 1
   :widths: 34 66

   * - Key
     - Meaning
   * - ``result``
     - Evaluated attempts by frequency and position.
   * - ``performance_criterion``, ``performance_assessment``
     - Criterion A/B/C and structured assessment for each measurement point.
   * - ``overall_passed``, ``overall_status``, ``complete``
     - Overall decision and completeness. ``overall_status`` is ``passed``,
       ``failed``, or ``incomplete``.
   * - ``incomplete_exposures``
     - Missing or unevaluable requested exposures.
   * - ``leveling_summary``
     - Leveling metadata by frequency and position.
   * - ``monitor_diagnostics``
     - Copy of diagnostics from raw data.
   * - ``reference_selection``, ``reference_summary``
     - Reference used and its suitability summary.
   * - ``immunity_target_efield``, ``immunity_reference_power_selection``
     - Target field and power reference used.
   * - ``am_headroom_policy``, ``am_modulation``
     - AM evidence and modulation.
   * - ``eut_event_policy``, ``position_coverage``, ``post_exposure_timeout``
     - Assessment and workflow context.

An ``incomplete_exposures`` entry has ``frequency``, ``position``, ``status``,
``reason``, ``detail``, and ``testfield``. ``complete`` is ``True`` only when
every requested frequency-and-position combination has a valid EUT status.
Consequently, do not interpret ``overall_passed == False`` without
``overall_status``: it can mean a technical failure or an incomplete run.