NeXusCreator

NeXusCreator is a Python command-line tool that converts raw experimental data into NeXus-compliant HDF5 (.nxs) files. It addresses a key challenge in scientific data management: experimental instruments generate data in many different formats, while long-term storage, sharing, and analysis require a standardized structure.

NeXus is that standard — a community-defined data format built on HDF5 that specifies how scientific data and metadata should be organized, especially for photon, neutron, and muon experiments.

---

Key Features

• Convert raw data files into structured NeXus (.nxs) files
• Generate NeXus definition templates (.nxd) from input data
• Support multiple data formats such as SPEC, DTA/DAT, HDF5, TIFF, and YAML
• Process individual files or entire directories
• Support batch workflows and beamline-specific parsing
• Provide an extensible plugin system for custom formats
• Optional schema-guided structuring via SchemaPlacer
• Support validation and CSV export workflows

---

Core Concept

NeXusCreator separates structure from data.

1. .nxd Definition File

A .nxd file defines the NeXus structure:

• groups (NXentry, NXdata, NXinstrument)
• datasets and types
• attributes (@units, @signal, @axes)

Placeholders are used for values:

energy:NX_FLOAT64[] = scan1_energy

---

2. Input Data Parsing

Raw files are parsed into a dictionary (library):

scan1_energy -> [array]
temperature  -> 298.15

---

3. Value Injection

Placeholders are replaced with real values, producing a valid .nxs file with proper structure and metadata.

---

SchemaPlacer (Schema-Guided Structuring)

SchemaPlacer enhances NeXusCreator by aligning generated structures with official NXDL definitions.

It uses NeXus schema files to:

• Place datasets in the correct NX_class groups
• Suggest or enforce compliant hierarchy layouts
• Align output with application definitions (e.g. NXxas)
• Reduce ambiguity in auto-generated .nxd files

When to use it

• When generating .nxd automatically (-g)
• When targeting a specific NeXus application definition
• When standardizing across instruments or beamlines
• When validation compliance matters

---

Example: schema-guided .nxd generation

nexuscreator -g out.nxd -i data.spec \
  --nxdl-root /path/to/nxdl \
  --app-def NXxas

---

Example: schema-guided conversion

nexuscreator -n def.nxd -i data.spec -o out.nxs \
  --nxdl-root /path/to/nxdl \
  --app-def NXxas

---

What changes with SchemaPlacer

Without SchemaPlacer:

• Structure is inferred from input + heuristics

With SchemaPlacer:

• Structure is guided by NXDL schema
• Fields are placed in expected locations
• Output is closer to formal NeXus compliance

---

Typical Workflow

# Generate definition
nexuscreator -g output.nxd -i data.spec

# Convert to NeXus
nexuscreator -n output.nxd -i data.spec -o output.nxs

---

Common CLI Options

Flag	Description
-i	Input file or directory
-o	Output file or directory
-g	Generate a .nxd definition
-n	Convert to .nxs
-b	Beamline profile
-t	Template generation
--nxdl-root	Path to NXDL definitions
--app-def	Target application definition
--auto-generate-nxd	Auto-generate .nxd

---

Advanced Concepts

Templates

• scan_{num} → per-scan expansion
• {file_name} → per-file expansion

Links

• Internal (@link)
• External (@extlink)

---

Design Goals

• Explicit and readable NeXus structures
• Accessible to non-programmers
• Extensible for multiple instruments
• Transparent data-to-structure mapping
• Reproducible workflows

---

Summary

NeXusCreator bridges raw experimental data and standardized NeXus datasets. With SchemaPlacer, it can move from flexible data mapping to schema-aligned, application-definition-aware outputs, improving interoperability and validation readiness.