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 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 Profile reference for every configuration value and Develop custom report modules 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 mpylab.env.Measure.load_pickle_compat() but does not connect to instruments.

Report modules consume evaluated data:

Automatically discovered sections¶
Identifier	Pickle mapping	Main content
`verification:<description>`	`processedData_Verification`	Uniformity, TEM mode, reference field and power, analytical e0y, and AM headroom
`e0y:<description>`	`processedData_e0y`	Measured field factor, source, position, and analytical comparison
`emission:<description>`	`processedData_Emission` and `preflightData_Emission`	Correlated field and power, limits, detectors, prescan, and e0y sources
`immunity:<description>`	`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:

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¶

# 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¶

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:

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:

# Global laboratory profile
[report]
title = "TEM/GTEM Measurement Report"
language = "en"

[laboratory]
name = "EMC Laboratory"

[appearance]
primary_color = "#174A7E"
accent_color = "#2E7D32"

# 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.

Profile reference¶

Only the following tables and keys are accepted. Unknown or misspelled keys are errors rather than silently ignored metadata.

TOML report profile¶
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.

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 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 mpylab.env.tem.history_report.write_history_report(); the command-line program does not discover external modules automatically.

The report API 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 report API documents discovery, selection, profile loading, and the modular extension interface.