Package: nyaml
Converting nyaml to NXDLnyamlis a versatile tool designed for converting NeXus application definitions from YAML (nyaml) to the Nexus Definitions Language (nxdl) format and vice versa. This command-line interface offers a simple and efficient way to work with NeXus data definitions.InstallationYou can easily install the tool usingpip:pipinstallnyamlAlternatively, you can install it as a development package from the GitHub repository:gitclonehttps://github.com/FAIRmat-NFDI/nyaml.gitcdnyaml
pipinstall-e".[dev]"We also provide a pre-commit hook for code formatting and linting, which you can install with:pre-commitinstallUsageThe primary commands for using nyaml arenyaml2nxdland its shortcut,n2n. Here is an overview of the available options:user@box:~$nyaml2nxdl--help
Usage:nyaml2nxdl[OPTIONS]INPUT_FILEMainfunctionthatdistinguishestheinputfileformatandlaunchesthetools.

Options:--output-fileTEXTSpecifytheoutputfilepathfortheconvertedfile.--check-consistencyCheckwhetherYAMLandNXDLcanberecursivelyconverted,ensuringversionconsistency.--do-not-store-nxdlPreventtheinputNXDLfilefrombeingstoredasacommentattheendoftheoutputYAMLfile.--verboseDisplaykeywordsandvaluetypesinstandardoutputtoassistinidentifyingissuesinYAMLfiles.--helpShowthismessageandexit.How It WorksThe tool operates by:Reading the user-specified NeXus definition, either in YAML or XML format.If the input is in YAML, it creates an instantiated NXDL schema XML tree by parsing the YAML dictionary.If the input is in XML, it creates a YAML file by parsing the XML tree.The tool then writes the resulting data structure to either a YAML or NXDL file on disk.DocumentationRule SetWhen transcribing YAML files, it's important to adhere to the following rules:Named NeXus Groups: Instances of NeXus classes, especially base or contributed classes, are represented as named NeXus groups. For example, creating(NXbeam)is a simple example of defining a group according to NeXus default rules. You can create multiple named instances at the same hierarchy level, such asmybeam1(NXbeam)ormybeam2(NXbeam).Members of Groups: Members within groups are referred to as fields or attributes. A simple example is the fieldvoltage, where the data type is implied automatically as the default NeXusNX_CHARtype. To specify a different type, usevoltage(NX_FLOAT).Attributes: Attributes of groups or fields are preceded by the '@' symbol.Optionality: By default, all groups, fields, and attributes in application definitions are required, except those explicitly marked as recommended or optional.Special Keywords: There exists a set of special keywords that can be used as children of groups, fields, and attributes to specify their properties. These elements are nodes of the XML tree.Doc StructureThedockeyword is used for adding human-readable descriptions or docstrings. It can be a single block or a list of doc parts. Here's an example:energy:doc:-|Part1 of the entire doc.part1 of the entire doc.-|xref:spec: <spec>term: <term>url: <url>-|Rest of the docrest of the docvelocity:# fielddoc:|A single block of doc string.This structure appears in Nxdl as follows:<fieldname="energy"><doc>Part1oftheentiredoc.part1oftheentiredoc.Thisconceptisrelatedtoterm`&lt;term&gt;`_ofthe&lt;spec&gt;standard..._&lt;term&gt;:&lt;url&gt;Restofthedocrestofthedoc</doc><fieldname="velocity"><doc>Asingleblockofdocstring.</doc></field></field>Additional Keywordsexists: Options forexistscan be recommended, required, or specified as[min, 1, max, infty]. Replace1with any unsigned integer or useinftyto indicate no restriction on occurrence within the Nxdl schema at the same hierarchy level.link: Defineslinksbetween nodes.units: IntroducesNeXus-compliantNXDLunitsarguments, such asNX_VOLTAGE.dimensions: Details the expected dimensional arrays.dim: A shorthand notation for dimensions, e.g.,(n, )for a 1D array of lengthnor(n, m)for a 2D array of sizen x m.enumeration: A Python list of strings considered as recommended entries.dim_parameters: A child ofdimensionwith attributes likerefandincr, includingindexandvalue.Keep in mind that the length of all lists must match. Note that the attributesref,incr, andindexare deprecated.Project RoadmapThe NOMAD team is actively working on establishing a one-to-one mapping between NeXus definitions and theNOMAD schemas(scientific data model in NOMAD). Once completed, YAML files will be annotated with additional metadata to serve dual purposes: as an instance for a schema to create a GUI representation of a NOMAD Oasis ELN schema and as a YAML to NXDL converter that ignores irrelevant information from a NeXus perspective.