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: https://github.com/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)[source]

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("master")
    
  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()

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()[source]

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

close()[source]

close the HDF5 file (if it is open)

finding_score()[source]

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)[source]

return a summary dictionary of the count of findings by status

summary statistics ======= ===== =========================================================== status count description ======= ===== =========================================================== OK 10 meets NeXus specification NOTE 1 does not meet NeXus specification, but acceptable WARN 0 does not meet NeXus specification, not generally acceptable ERROR 0 violates NeXus specification TODO 3 validation not implemented yet UNUSED 2 optional NeXus item not used in data file COMMENT 0 comment from the punx source code – – – TOTAL 16 – ======= ===== ===========================================================

print_report()[source]

print a validation report

record_finding(v_item, key, status, comment)[source]

prepare the finding object and record it

usedAsBaseClass(nx_class)[source]

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)[source]

start the validation process from the file root

validate_application_definition(v_item)[source]

validate group as a NeXus application definition

validate_group(v_item)[source]

validate the NeXus content of a HDF5 data file group

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

HDF5 data file object for validation

determine_NeXus_classpath()[source]

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