API for command line tools

pynxtools provides a unified pynx entry point with subcommands for all CLI operations. This page documents the current API.

The legacy entry points (dataconverter, validate_nexus, read_nexus, generate_eln) are still installed as deprecated aliases — they continue to work but emit a deprecation warning.

Data conversion — pynx convert

Converts experimental data to NeXus/HDF5 files. Internally uses the reader pipeline described in Learn > pynxtools > Data conversion in pynxtools.

pynx convert

Convert input files to a NeXus HDF5 file.

Usage:

pynx convert [OPTIONS] [FILES]...

Options:

Name	Type	Description	Default
--input-file	text	Deprecated: Please use the positional file arguments instead. The path to the input data file to read. Repeat for more than one file. default=[] This option is required if no '--params-file' is supplied.	[]
--reader	choice (example | json_map | json_yml | multi)	The reader to use. Examples are json_map or readers from a pynxtools plugin. default='json_map' This option is required if no '--params-file' is supplied.	json_map
--nxdl	text	The name of the NeXus application definition file to use without the extension nxdl.xml. This option is required if no '--params-file' is supplied.	None
--output	text	The path to the output NeXus file to be generated. default='output.nxs'	output.nxs
--params-file	filename	Allows to pass a .yaml file with all the parameters the converter supports.	None
--append	boolean	Appends instance data to the given file if the file already exists.Will prevent an overwriting of existent data and adding of new NXentry instances.If True, will skip the validation whatever irrespective if --skip-verify is passed.	False
--ignore-undocumented	boolean	Ignore all undocumented concepts during validation.	False
--fail	boolean	Fail conversion and don't create an output file if the validation fails.	False
--skip-verify	boolean	Skips the verification routine during conversion. When --append is used the verification is always skipped irrespective if --skip-verify is used or not.	False
--mapping	text	Takes a .mapping.json file and converts data from given input files. Deprecated. Will be removed in a future release. The --config flag can be used instead.	Sentinel.UNSET
-c, --config	file	A json config file for the reader	None
--help	boolean	Show this message and exit.	False

Sub-commands

pynx convert

Convert data to NeXus.

Usage:

pynx convert [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

Subcommands

• generate-template: Print a conversion template for a NeXus application definition.
• get-readers: List all installed readers.
• reader-info: Show supported NXDLs and file extensions for a reader.
• run: Convert input files to a NeXus HDF5 file.

pynx convert generate-template

Print a conversion template for a NeXus application definition.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx convert generate-template [OPTIONS] NXDL

Options:

Name	Type	Description	Default
--required	boolean	Include only required fields.	False
--pythonic	boolean	Print a Python dict instead of JSON.	False
--output	path	Write output to this file instead of stdout.	Sentinel.UNSET
--help	boolean	Show this message and exit.	False

pynx convert get-readers

List all installed readers.

Usage:

pynx convert get-readers [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

pynx convert reader-info

Show supported NXDLs and file extensions for a reader.

READER: name of the reader to inspect, e.g. json_map

Usage:

pynx convert reader-info [OPTIONS] {example|json_map|json_yml|multi}

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

pynx convert run

Convert input files to a NeXus HDF5 file.

Usage:

pynx convert run [OPTIONS] [FILES]...

Options:

Name	Type	Description	Default
--input-file	text	Deprecated: Please use the positional file arguments instead. The path to the input data file to read. Repeat for more than one file. default=[] This option is required if no '--params-file' is supplied.	[]
--reader	choice (example | json_map | json_yml | multi)	The reader to use. Examples are json_map or readers from a pynxtools plugin. default='json_map' This option is required if no '--params-file' is supplied.	json_map
--nxdl	text	The name of the NeXus application definition file to use without the extension nxdl.xml. This option is required if no '--params-file' is supplied.	None
--output	text	The path to the output NeXus file to be generated. default='output.nxs'	output.nxs
--params-file	filename	Allows to pass a .yaml file with all the parameters the converter supports.	None
--append	boolean	Appends instance data to the given file if the file already exists.Will prevent an overwriting of existent data and adding of new NXentry instances.If True, will skip the validation whatever irrespective if --skip-verify is passed.	False
--ignore-undocumented	boolean	Ignore all undocumented concepts during validation.	False
--fail	boolean	Fail conversion and don't create an output file if the validation fails.	False
--skip-verify	boolean	Skips the verification routine during conversion. When --append is used the verification is always skipped irrespective if --skip-verify is used or not.	False
--mapping	text	Takes a .mapping.json file and converts data from given input files. Deprecated. Will be removed in a future release. The --config flag can be used instead.	Sentinel.UNSET
-c, --config	file	A json config file for the reader	None
--help	boolean	Show this message and exit.	False

Info

Note that simply calling pynx convert defaults to pynx convert run.

NeXus file validation — pynx validate

Validates an existing HDF5/NeXus file against the NeXus application definition it declares in NXentry/definition.

See Learn > pynxtools > Validation of NeXus files for a conceptual explanation and the how-to guide for usage examples.

pynx validate

Validate a NeXus HDF5 file against its application definition.

Usage:

pynx validate [OPTIONS] FILE

Options:

Name	Type	Description	Default
--ignore-undocumented	boolean	Ignore all undocumented concepts during validation.	False
--help	boolean	Show this message and exit.	False

NeXus file annotator — pynx read

Annotates every node in a NeXus/HDF5 file with NXDL documentation, optionality, data types, unit categories, and inheritance paths. Backed by Annotator in pynxtools.annotator.annotator.

Three operating modes:

• Default: annotate all nodes and print the default-plottable summary.
• -d (documentation): annotate the single node at a given HDF5 path.
• -c (concept): find all HDF5 nodes that satisfy an IS-A relation with a given NXDL concept. Two query forms are supported:
  • Bare class name (e.g. NXbeam): matches HDF5 groups whose NX_class attribute equals the given class exactly. Fields are not matched.
  • Appdef path (e.g. NXarpes/NXentry/NXinstrument/analyser): matches both groups and fields resolved against the file's application definition. Requires the file to declare an appdef via definition in its NXentry.

Note

Only one of -d and -c is accepted at a time.

Known limitations of -c

• Bare class queries match by exact NX_class attribute. Full IS-A chain traversal (e.g. querying NXobject to match all groups) is not yet supported.
• Fields in base-class-only files (no application definition) cannot be matched. Only groups can be found via their NX_class attribute in that case.

pynx read

Annotate each group, field, and attribute in a NeXus/HDF5 file with the matching NXDL concept path, optionality, and documentation string.

Without options, the full annotation log for the file is printed. Use -d to restrict output to a single HDF5 path, or -c to find all instances in the file that correspond to a given NXDL concept path.

Usage:

pynx read [OPTIONS] NEXUS_FILE

Options:

Name	Type	Description	Default
-d, --documentation	text	Definition path in nexus output (.nxs) file. Returns debug log relevant with that definition path. Example input: /entry/data/delays	None
-c, --concept	text	NXDL concept path. Finds all HDF5 nodes satisfying an IS-A relation with the given concept. Two forms: (1) bare class name, e.g. 'NXbeam' — matches groups by NX_class attribute; (2) appdef path, e.g. 'NXarpes/ENTRY/INSTRUMENT/analyser' — matches groups and fields via the file's application definition. Fields in base-class-only files are not supported by form (1).	None
--help	boolean	Show this message and exit.	False

ELN schema generation — pynx generate_eln

Generates an ELN YAML template from a NeXus application definition. The resulting file can be filled in to provide metadata for the dataconverter.

pynx generate-eln

Generate an ELN YAML scaffold for a NeXus application definition.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx generate-eln [OPTIONS] NXDL

Options:

Name	Type	Description	Default
--skip-top-levels	integer	To skip the level of parent hierarchy level. For example, by default the part Entry[ENTRY] from /Entry[ENTRY]/Instrument[INSTRUMENT]/... will be skipped.	0
--output-file	text	Name of file that is needed to generated output file.	None
--eln-type	choice (reader | schema)	Choose a type of ELN output (reader or schema).	eln
--optionality	choice (required | recommended | optional)	Level of requiredness to generate. If any of ('required', 'recommended', 'optional', only those concepts matching this requiredness level are created.	required
--filter-file	text	JSON configuration file to filter NeXus concepts (based on the presence of the '@eln' keyword). This is a positive filter, i.e., all concepts in the filter file will be included in the ELN.	None
--help	boolean	Show this message and exit.	False

Application definition inspector

Lists the concept paths defined in a NeXus application.

pynx inspect-appdef

List the concept paths defined in a NeXus application definition.

Prints all paths at or above the requested optionality level (required, recommended, or optional). Useful for understanding what data must be provided before converting with pynx convert, or as a lightweight alternative to pynx convert generate-template when you only need the field names rather than a fillable JSON skeleton.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx inspect-appdef [OPTIONS] NXDL

Options:

Name	Type	Description	Default
--level	choice (required | recommended | optional)	Minimum optionality level to include.	required
--help	boolean	Show this message and exit.	False