Paired ARINA microscope metadata

NXem companion files

For acquisition_master.h5, the Python loader also recognizes acquisition_em_metadata.h5. Keep the master, all detector shards and this companion together. Opening the master is sufficient; no separate metadata argument is required.

The NXem reader checks the regular raster against the acquisition frame count and any explicit scan dimensions before applying calibration. It reads scalar metadata only. Scan pixel sizes are converted to Å, angular detector pixel sizes to mrad and accelerating voltage to kV. Each quantity needs explicit, recognized units. Row and column sampling are retained separately.

Zero or missing convergence angles remain unavailable during header inspection. screening.prepare can estimate the missing semiangle from the full mean diffraction disk when angular detector sampling is recorded. It uses the half-plateau disk area and the angular area of one detector pixel, preserving the estimate’s provenance in semiangle_mrad_source. This does not independently validate the detector calibration. An explicit recorded angle is retained. A zero scan-controller rotation does not establish a scan-to-detector rotation. Missing or mismatched metadata must not become a guessed calibration. The paired file participates in the source signature, so changing it invalidates cached metadata.

tests/contracts/io/test_nxem_metadata.py covers loading a nonsquare raster, anisotropic units, saved metadata, companion changes and rejected calibration.

Legacy STEM Metadata companion files

Opening acquisition_master.h5 also reads acquisition.h5, when that exactly paired file contains a STEM Metadata group. The Python loader and native Swift catalog read its small attributes without decoding virtual images. Keep the master, detector shards and microscope file together.

Source attribute	Interpretation
NumPixelsY, NumPixelsX	Scan rows and columns, checked against detector frame count and any explicit raster
Pixel Size	Nominal scan step in nm, converted to Å
IsPixelSizeCalibrated	Only 1 permits promotion to calibrated scan sampling
High Tension	Microscope voltage in V
Camera Length	Nominal camera length in m
Rotation	Retained scan-controller setting; not used as scan-detector rotation

These are the legacy STEM Metadata schema conventions. Other HDF5 layouts require their own unit-bearing reader. The Pixel Size interpretation follows the RosettaSciIO ARINA reader.

What becomes automatic

io.load(...) returns a Dataset4dstemGPU with microscope voltage, camera length, raw companion attributes and the paired filename in metadata. Calibrated scan steps populate sampling[:2] in Å. A nominal step instead appears in metadata["scan_sampling_nominal_A"]; the scan sampling remains unspecified. The native inspector displays the nominal value and its warning.

Detector sensor pitch is not scan sampling. Camera length alone is not enough to derive a calibrated angular or reciprocal detector step. No convergence angle, detector sampling or scan-detector rotation is invented by this reader.

The microscope voltage takes precedence over a conflicting detector photon_energy setting. Both source values and a warning are retained. Unreadable or mismatched companion files cannot supply calibration. Native catalog cache keys and Python source signatures include the paired file, so updating or removing it invalidates earlier metadata evidence.

Saved .qem copies retain the original attributes, nominal step, calibration flag and warning in source_metadata, as well as valid microscope quantities.

Checks

• Python: tests/contracts/io/test_stem_metadata.py covers inspection, loading, saved metadata, nominal calibration and mismatched companions.

• Native: tests/hardware/metal/test_catalog_calibration.py covers the same source interpretation, cache refresh, removal and existing NXem behavior.

• Real-device acceptance separately checks original HDF5 GPU loading and the native inspector. Metadata tests alone do not qualify detector decoding.