Validation : validate

The process of validation compares each item in an HDF5 data file and compares it with the NeXus standards to check that the item is valid within that standard. Each test is assigned a finding result, a Severity object, with values and meanings as shown in the table below.

value	color	meaning
OK	green	meets NeXus specification
NOTE	palegreen	does not meet NeXus specification, but acceptable
WARN	yellow	does not meet NeXus specification, not generally acceptable
ERROR	red	violates NeXus specification
TODO	blue	validation not implemented yet
UNUSED	grey	optional NeXus item not used in data file
COMMENT	grey	comment from the punx source code

Items marked with the WARN severity status are as noted in either the NeXus manual [1], the NXDL language specification [2], or the NeXus Definition Language (NXDL) files [3].

The color is a suggestion for use in a GUI.

Numerical values are associated with each finding value. The sum of these values is averaged to produce a numerical indication of the validation of the file against the NeXus standard. An average of 100 indicates that the file meets the NeXus specification for every validation test applied. An average that is less than zero indicates that the file contains content that is not valid with the NeXus standard.

NeXus HDF5 Data Files

NeXus data files are HDF5 [4] and are validated against the suite of NXDL files using tools provided by this package. The strategy is to compare the structure of the HDF file with the structure of the NXDL file(s) as specified by the NX_class attributes of the various HDF groups in the data file.

NeXus NXDL Definition Language Files

NXDL files are XML and are validated against the XML Schema file: nxdl.xsd. See the GitHub repository [5] for this file.

[1]

NeXus manual: http://download.nexusformat.org/doc/html/user_manual.html

[2]

NXDL Language: http://download.nexusformat.org/doc/html/nxdl.html

[3]

NeXus Class Definitions (NXDL files): http://download.nexusformat.org/doc/html/classes/index.html

[4]

HDF5: https://support.hdfgroup.org/HDF5/

[5]

NeXus GitHub Definitions repository: nexusformat/definitions

---

source code documentation

validate files against the NeXus/HDF5 standard

PUBLIC

Data_File_Validator([ref])

manage the validation of a NeXus HDF5 data file

INTERNAL

ValidationItem(parent, obj[, attribute_name])

HDF5 data file object for validation

class punx.validate.Data_File_Validator(ref=None)

manage the validation of a NeXus HDF5 data file

USAGE

1. make a validator with a certain schema:

   validator = punx.validate.Data_File_Validator()    # default
   

   You may have downloaded additional NeXus Schema (NXDL file sets). If so, pick any of these by name as follows:

   validator = punx.validate.Data_File_Validator("v3.2")
   validator = punx.validate.Data_File_Validator("main")
   

2. use to validate a file or files:

   result = validator.validate(hdf5_file_name)
   result = validator.validate(another_file)
   

3. close the HDF5 file when done with validation:

   validator.close()
   

PUBLIC METHODS

close()	close the HDF5 file (if it is open)
validate(fname)	start the validation process from the file root
print_report([statuses])	Print a validation report.

INTERNAL METHODS

build_address_catalog()	find all HDF5 addresses and NeXus class paths in the data file
_group_address_catalog_(parent, group)	catalog this group's address and all its contents
validate_item_name(v_item)

build_address_catalog()

find all HDF5 addresses and NeXus class paths in the data file

close()

close the HDF5 file (if it is open)

finding_score()

return a numerical score for the set of findings

count: number of findings total: sum of status values for all findings score: total / count – average status / finding

finding_summary(report_statuses=None)

Return a summary dictionary of the count of findings by status.

Summary Statistics

print_report(statuses=None)

Print a validation report.

record_finding(v_item, key, status, comment)

prepare the finding object and record it

usedAsBaseClass(nx_class)

returns bool: is the nx_class a base class?

NXDL specifications in the contributed definitions directory could be intended as either a base class or an application definition. NeXus provides no easy identifier for this difference. The most obvious distinction between them is the presence of the definition field in the NXentry group of an application definition. This field is not present in base classes.

validate(fname)

start the validation process from the file root

validate_application_definition(v_item)

validate group as a NeXus application definition

validate_group(v_item)

validate the NeXus content of a HDF5 data file group

class punx.validate.ValidationItem(parent, obj, attribute_name=None)

HDF5 data file object for validation

determine_NeXus_classpath()

determine the NeXus class path

See:

http://download.nexusformat.org/sphinx/preface.html#class-path-specification

EXAMPLE

Given this NeXus data file structure:

/
    entry: NXentry
        data: NXdata
            @signal = data
            data: NX_NUMBER

For the “signal” attribute of this HDF5 address: /entry/data, its NeXus class path is: /NXentry/NXdata@signal

The @signal attribute has the value of data which means that the local field named data is the plottable data.

The HDF5 address of the plottable data is: /entry/data/data, its NeXus class path is: /NXentry/NXdata/data