# 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

```python
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.