The NxsReader Class

NxsReader servers these purposes:

• Inspect the contents of a NeXus file.
• Access the NeXus items, in particular the data fields.
• Purge NeXus files. The purge function looks at the motor positions to identify those that appear more than once. These positions are removed from the file together with the corresponding data. Purging is necessary for absorber scans when an intensity has to be adjusted to match the dynamic range of a detector.

Let's look at an example:

In [16]: import HasyUtils

In [17]: o = HasyUtils.nxsReader( 'nexusTest_00385.nxs')

In [18]: dir(o)
Out[18]: 
[...
 'collectStatus',
 'createFile',
 'display',
 'fileName',
 'fillTestData',
 'pathDct',
 'purge',
 'search',
 ...]

Explanations:

• collectStatus, returns True, if the file contains images instead of external links. purge terminates, if this function returns False.

• createFile, dumps the object into a new file.

• display, returns a list of strings containing all groups, fields, links and attributes.

• fileName

• pathDct, a dictionary relating path names to NeXus items.

  In [16]: o.pathDct
  Out[16]: 
  {'/': <HasyUtils.nxsReader._NxsGroup instance at 0x7f3fedf5c518>,
   '/@HDF5_version': <HasyUtils.nxsReader._NxsAttr instance at 0x7f3fd9378878>,
   '/@NX_class': <HasyUtils.nxsReader._NxsAttr instance at 0x7f3fd0ec2170>,
   ...
  
   ...
  

• purge, finds scan indices with identical motor positions and removes them together with associated data.

• search
  • lst = o.search( field=None), returns a list of all fields.
  • lst = o.search( field=None, text=True), returns a list string of all fields.
  • lst = o.search( ndim=2), returns a list of 2-dimensional fields (MCA data)
  • lst = o.search( field='/scan:NXentry/instrument:NXinstrument/pilatus:NXdetector/data'), return a fully qualified field.

Let's look at a specific NeXus field holding the Pilatus data:

In [1]: import HasyUtils

In [2]: o = HasyUtils.nxsReader( 'nexusTest_00385.nxs')

In [3]:  lst = o.search(ndim=3)

In [4]: len(lst)
Out[4]: 1

In [5]: pilatus = lst[0]

In [6]: pilatus.path
Out[6]: '/scan:NXentry/instrument:NXinstrument/pilatus:NXdetector/data'

In [7]: pilatus.shape
Out[7]: (27, 195, 487)

In [8]: pilatus.dtype
Out[8]: 'int32'

In [9]: type( pilatus.value)
Out[9]: numpy.ndarray

In [10]: pilatus.value
Out[10]: 
array([[[33, 34, 32, ..., 19, 22, 19],
        [25, 19, 17, ..., 20, 12, 31],
        [33, 21, 28, ..., 14, 16, 18],
        ..., 
        [27, 16, 26, ..., 12, 19, 26],
        [33, 20, 25, ..., 17, 10, 24],
        [30, 31, 27, ..., 21, 14, 14]]], dtype=int32)

In [11]: pilatus.parent.path
Out[11]: '/scan:NXentry/instrument:NXinstrument/pilatus:NXdetector'

In [12]: pilatus.parent.parent.path
Out[12]: '/scan:NXentry/instrument:NXinstrument'

In [13]: pilatus.parent.parent.parent.path
Out[13]: '/scan:NXentry'

In [14]: pilatus.parent.parent.parent.parent.path
Out[14]: '/'

Explanation:

• [3], search for a 3-dimensional field, pilatus matches because it hass the shape (27, 195, 487)
• [4], len() == 1, there is only one 3-dimensional field.
• [5], let's call it pilatus
• [6 - 8], print path, shape and dtype.
• [9-10], the Pilatus data are a numpy array.
• [11 - 14], climbing upwards

The next example shows how a field is inserted:

In [29]: import HasyUtils

In [30]: import numpy as np

In [31]: o = HasyUtils.nxsReader( 'nexusTest_00414.nxs')

In [32]: targetGroup = o.pathDct['/']

In [33]: lst = [1, 3, 5, 7, 11, 13, 17, 19]

In [34]: newField = HasyUtils.NxsField( targetGroup, "Primes", "/Primes", 'int64', (len(lst),), np.array(lst))

In [35]: targetGroup.fields.append( newField)

In [36]: p, = o.search( field='Primes')

In [37]: p.name
Out[37]: 'Primes'

In [38]: p.path
Out[38]: '/Primes'

In [39]: p.shape
Out[39]: (8,)

In [40]: p.value
Out[40]: array([ 1,  3,  5,  7, 11, 13, 17, 19])

In [41]: newField = HasyUtils.NxsField( targetGroup, "TestString", "/TestString", 'string', (1,), "a test string")

In [42]: targetGroup.fields.append( newField)

In [43]: o.createFile( 'newFileName.nxs')

Explanation:

• [31], create the object representing 'nexusTest_00414.nxs'.
• [32], the field will be inserted into the group '/', the rootGroup.
• [33], prepare some test data
• [34], create a field object. The '(len(lst),)' parameter is the shape.
• [35], insert the newField into the fields array of the targetGroup
• [36], search for the field. Notice the ',' in 'p,'.
• [37-40], demonstrate that all is well
• [41-42], a string field is inserted
• [43], dump the object to a NeXus file to save the important changes