SchemaPlacer

SchemaPlacer is a lightweight NXDL indexer that proposes canonical NeXus paths for variables produced by generators and parsers.

Capabilities

  • Indexes NXDL — loads application definitions and base classes to collect fields and paths.

  • Matches names — normalises variable names and applies common aliases (for example hv → energy).

  • Scores candidates — considers name overlap, group context, and unit hints (eV, K, deg).

  • Honours preferences — favours your chosen application definition when possible.

  • Builds objects — produces NeXus-shaped dictionaries with inferred @dtype and optional @units.

Quick Example

from nexuscreator.libraries.SchemaPlacer import SchemaPlacer

nxdl_root = "./nexus_definitions"  # path to an NXDL checkout
placer = SchemaPlacer(nxdl_root, app_def="NXxas", search_app_definitions=True)

# Suggest placements for a variable library (name -> sample value)
library = {"photon_energy": 400.0, "ring_current": 250.0}
placements = placer.place(library)

# Convert placements + values into a NeXus-like object
obj = SchemaPlacer.build_object_from_placements(placements, library)

Tips

  • Pass --nxdl-root and --app-def to the CLI to enable schema-guided placement during generation. If --nxdl-root is omitted, NeXusCreator uses external_references/nexus/nexus_definitions when present.

  • Supply a metadata CSV (variable,description,units) to improve scoring and populate @units.

  • Metadata keys are matched case-insensitively and across aliases (hv, photon_energy, energy).

  • Base classes are always indexed; pass --app-def NAME if you also want to search a specific application definition.

  • Energy aliases (energy, hv, photon_energy, mono_energy, e_ke) are always forced to /entry/instrument/monochromator/energy so the NXmonochromator path stays canonical even if other NXDL hits score higher.

Inspecting candidates

Use SchemaPlacer.ranked_candidates(name, units_text, limit) to inspect the ordered list of matches and their _score. This is handy when tuning metadata or debugging why a variable was mapped to a specific path.