.. index:: report generation, TEM report, PDF report, HTML report Modular TEM reports =================== ``mpylab-tem-report`` reads the complete history from a ``TEMCell`` pickle and discovers supported datasets automatically. The generator currently covers TEM-mode verification, measured e0y field factors, emission, and immunity including EUT assessment. Event fields, performance criteria, and the optional interchange format are documented under :doc:`Immunity results and EUT assessment `. Content, presentation, and extension are deliberately separate: * ``--section`` selects existing evaluated measurement datasets; * TOML profiles configure metadata, laboratory identity, and colors; * custom Python report modules add new technical report sections. Profiles never change measurement results or run an evaluation. See :ref:`report-profile-reference-en` for every configuration value and :ref:`custom-report-modules-en` for the extension interface. Input and prerequisites ----------------------- The input is a trusted final or after-measure ``TEMCell`` pickle. Pickles can execute Python code while loading; do not generate reports from an untrusted file. The generator uses :func:`mpylab.env.Measure.load_pickle_compat` but does not connect to instruments. Report modules consume evaluated data: .. list-table:: Automatically discovered sections :header-rows: 1 :widths: 20 34 46 * - Identifier - Pickle mapping - Main content * - ``verification:`` - ``processedData_Verification`` - Uniformity, TEM mode, reference field and power, analytical e0y, and AM headroom * - ``e0y:`` - ``processedData_e0y`` - Measured field factor, source, position, and analytical comparison * - ``emission:`` - ``processedData_Emission`` and ``preflightData_Emission`` - Correlated field and power, limits, detectors, prescan, and e0y sources * - ``immunity:`` - ``processedData_Immunity`` and ``preflightData_Immunity`` - Exposures, disturbance, leveling, EUT events, and assessments Raw-only histories generally have no reportable section. Run the relevant evaluation first and write a new history pickle. The report generator never reconstructs missing evaluations silently. Inspect available sections -------------------------- Before generating a report, list the report sections found in a pickle: .. code-block:: console mpylab-tem-report measurement-history.p --list-sections ``--section MODULE:DATASET`` limits output to one or more of these sections. The option may be repeated. Recommended workflow -------------------- .. code-block:: console # Inspect the evaluated data sets first. mpylab-tem-report measurement-history.p --list-sections # Generate into a measurement-specific directory. mpylab-tem-report measurement-history.p \ --output reports/EMC-2026-001 \ --formats pdf html svg \ --profile laboratory.toml \ --profile EMC-2026-001.toml Use repeated ``--section`` options when a history contains several runs but only a controlled subset belongs in the deliverable report. Generate a report ----------------- .. code-block:: console mpylab-tem-report measurement-history.p \ --output tem-report \ --formats pdf html svg \ --profile script/conf/tem-report-profile.toml \ --profile script/conf/tem-report-measurement.toml Supported formats are ``pdf``, ``html``, ``svg``, and ``png``. HTML and PDF form the complete report. SVG and PNG create separate figures from the report modules. When HTML is requested without an image format, the generator also creates SVG files. PDF is generated directly through Matplotlib. HTML is a static local package without a server requirement. SVG is recommended for scalable plots and versioned archives; PNG is useful where office software cannot import SVG reliably. The generator currently does not create LaTeX source. Output directory ---------------- The result has a stable structure: .. code-block:: text tem-report/ |-- index.html |-- tem-history-report.pdf |-- traceability.tsv |-- report-metadata.tsv |-- assets/ `-- sections/ |-- verification-cal/ | |-- index.html | |-- figures/ | `-- tables/ `-- emission-eut/ |-- index.html |-- figures/ `-- tables/ Module tables retain the values behind the plots and are preferred for scripted review. A plot is omitted when its required data are absent; this does not remove available tables or traceability warnings. Layer profiles -------------- ``--profile`` may be repeated. Files are merged in command-line order; later values override only earlier values with the same key. A global laboratory configuration and measurement-specific details can therefore be versioned separately: .. code-block:: toml # Global laboratory profile [report] title = "TEM/GTEM Measurement Report" language = "en" [laboratory] name = "EMC Laboratory" [appearance] primary_color = "#174A7E" accent_color = "#2E7D32" .. code-block:: toml # Measurement-specific additions [report] report_number = "EMC-2026-001" [measurement] operator = "Example Operator" location = "Large GTEM" date = "2026-07-16" [environment] temperature_c = 23.1 relative_humidity_percent = 44.0 Commented templates are provided as ``script/conf/tem-report-profile.toml`` and ``script/conf/tem-report-measurement.toml``. .. _report-profile-reference-en: Profile reference ----------------- Only the following tables and keys are accepted. Unknown or misspelled keys are errors rather than silently ignored metadata. .. list-table:: TOML report profile :header-rows: 1 :widths: 20 36 44 * - Table - Keys - Validation and purpose * - ``[report]`` - ``title``, ``report_number``, ``language``, ``confidentiality`` - ``language`` is ``de`` or ``en``; title has a stable default * - ``[laboratory]`` - ``name``, ``department``, ``address``, ``logo`` - Logo is an existing PNG or JPEG; relative paths use the defining profile file as their base * - ``[measurement]`` - ``operator``, ``customer``, ``location``, ``date``, ``free_text`` - Date uses ISO ``YYYY-MM-DD`` and is not inferred from report creation * - ``[environment]`` - ``temperature_c``, ``relative_humidity_percent``, ``air_pressure_hpa`` - Humidity is 0 to 100; pressure is positive * - ``[appearance]`` - ``primary_color``, ``accent_color`` - Colors use ``#RRGGBB`` Later profiles override the same key only. Relative resources remain relative to the file that supplied the effective value. Traceability ------------ The generator does not evaluate the measurement again. It presents the results already stored in the pickle as independent modules. HTML and PDF contain a cross-section traceability overview. ``traceability.tsv`` provides the same information in machine-readable form, including frequency coverage, referenced source datasets, completeness, and warnings. ``report-metadata.tsv`` records effective profile values and their origins. This keeps values from the global profile, measurement profile, defaults, and generation distinguishable. For a report limited to verification, ``script/tem-verification-report.py`` remains available. .. _custom-report-modules-en: Develop custom report modules ----------------------------- Create a report module when an additional evaluated dataset needs its own report section. Use a TOML profile instead when only titles, laboratory details, free text, or colors need to change. A report module implements :class:`mpylab.env.tem.history_report.ReportModule` and participates in five steps: #. ``discover`` finds reportable datasets in the history. #. ``collect`` converts one dataset into renderer-neutral data. #. ``write`` creates the section HTML, tables, and separate figures. #. ``pdf_figures`` supplies pages for the combined PDF. #. ``summary`` provides compact index and traceability fields. Technical evaluation remains in the measurement class. ``collect`` may select and arrange existing results but must not reassess the measurement. Applications pass custom modules through the ``modules`` argument of :func:`mpylab.env.tem.history_report.write_history_report`; the command-line program does not discover external modules automatically. The :doc:`report API <../../api/reports>` provides a complete minimal skeleton and documents return structures. A new module should have at least logic tests for discovery and collection plus an end-to-end test for its generated files. Repeating and diagnosing generation ----------------------------------- Files with the same generated names are overwritten, but the output directory is not cleaned. Use a new or previously emptied directory when its exact file inventory is part of the archive. Typical failures have deliberate meanings: * ``no reportable sections``: the pickle has no supported evaluated mapping; * ``section ... is unavailable``: compare the identifier with ``--list-sections``; * profile errors: correct unknown keys, types, date, colors, environment ranges, or logo path; * a missing plot after successful generation: inspect the section's TSV tables and traceability warnings for absent source values. The :doc:`report API <../../api/reports>` documents discovery, selection, profile loading, and the modular extension interface.