NeXus Tree API Modules

NeXus Tree Module

Module to read, write, analyze, manipulate, and visualize NeXus data.

This is designed to accomplish two goals:

  1. To provide convenient access to existing data contained in NeXus files.

  2. To enable new NeXus data to be created and manipulated interactively.

These goals are achieved by mapping hierarchical NeXus data structures directly into Python objects, which represent NeXus groups, fields, or attributes. Entries in a group are referenced as a dictionary containing other groups or fields. The entire data hierarchy can be referenced at any time, whether the NeXus data has been loaded from an existing NeXus file or created dynamically within the Python session. This provides a natural scripting interface for the creation, manipulation, and visualization of NeXus data.

Example 1: Loading a NeXus file

The following commands loads NeXus data from a file, displays the contents as a tree, and then accesses individual data items. Note that all the classes and functions returned by the wildcard import in the example start with ‘NX’ or ‘nx’ so name clashes with other modules are unlikely.

>>> from nexusformat.nexus import *
>>> a=nxload('sns/data/ARCS_7326.nxs')
>>> print a.tree
root:NXroot
  @HDF5_Version = 1.8.2
  @NeXus_version = 4.2.1
  @file_name = ARCS_7326.nxs
  @file_time = 2010-05-05T01:59:25-05:00
  entry:NXentry
    data:NXdata
      data = float32(631x461x4x825)
        @axes = rotation_angle:tilt_angle:sample_angle:time_of_flight
        @signal = 1
      rotation_angle = float32(632)
        @units = degree
      sample_angle = [ 210.  215.  220.  225.  230.]
        @units = degree
      tilt_angle = float32(462)
        @units = degree
      time_of_flight = float32(826)
        @units = microsecond
    run_number = 7326
    sample:NXsample
      pulse_time = 2854.94747365
        @units = microsecond
.
.
.
>>> a['entry/run_number']
NXfield(7326)

The tree returned from nxload() has an entry for each group, field and attribute. You can traverse the hierarchy using the names of the groups. For example, tree[‘entry/instrument/detector/distance’] is an example of a field containing the distance to each pixel in the detector. Entries can also be referenced by NXclass name, such as tree.NXentry[0].instrument. Since there may be multiple entries of the same NeXus class, the NXclass attribute returns a (possibly empty) list.

The nxload() and nxsave() functions are implemented using the NXFile class, a subclass of h5py.File.

Example 2: Creating a NeXus file dynamically

The second example shows how to create NeXus data dynamically and saves it to a file. The data are first created as NumPy arrays

>>> import numpy as np
>>> x=y=np.linspace(0,2*np.pi,101)
>>> X,Y=np.meshgrid(y,x)
>>> z=np.sin(X)*np.sin(Y)

Then, a NeXus data group is created and the data inserted to produce a NeXus-compliant structure that can be saved to a file

>>> root=NXroot(NXentry())
>>> print root.tree
root:NXroot
  entry:NXentry
>>> root.entry.data=NXdata(z,[x,y])

Note that in this example, we have used the alternative attribute form for accessing objects in the hierarchical structure, i.e., root.entry.data instead of root[‘entry/data’]. The attribute form is faster to type interactively, but the dictionary form is safer for scripts when there is a chance of clashes with class attributes or methods.

Additional metadata can be inserted before saving the data to a file.

>>> root.entry.sample=NXsample()
>>> root.entry.sample.temperature = 40.0
>>> root.entry.sample.temperature.units = 'K'
>>> root.save('example.nxs')

NXfield objects have much of the functionality of NumPy arrays. They may be used in simple arithmetic expressions with other NXfields, NumPy arrays or scalar values and will be cast as ndarray objects if used as arguments in NumPy modules.

>>> x=nx.NXfield(np.linspace(0,10.0,11))
>>> x
NXfield([  0.   1.   2. ...,   8.   9.  10.])
>>> x + 10
NXfield([ 10.  11.  12. ...,  18.  19.  20.])
>>> np.sin(x)
array([ 0.        ,  0.84147098,  0.90929743, ...,  0.98935825,
    0.41211849, -0.54402111])

If the arithmetic operation is assigned to a NeXus group attribute, it will be automatically cast as a valid NXfield object with the type and shape determined by the NumPy array type and shape.

>>> entry.data.result = np.sin(x)
>>> entry.data.result
NXfield([ 0.          0.84147098  0.90929743 ...,  0.98935825  0.41211849
 -0.54402111])
>>> entry.data.result.dtype, entry.data.result.shape
(dtype('float64'), (11,))

Notes

Properties of the entry in the tree are referenced by attributes that depend on the object type, different nx attributes may be available.

Objects (NXobject) have attributes shared by both groups and fields::
  • nxname object name

  • nxclass object class for groups, ‘NXfield’ for fields

  • nxgroup group containing the entry, or None for the root

  • attrs dictionary of NeXus attributes for the object

Fields (NXfield) have attributes for accessing data:
  • shape dimensions of data in the field

  • dtype data type

  • nxdata data in the field

Groups (NXgroup) have attributes for accessing children::
  • entries dictionary of entries within the group

  • component(‘nxclass’) return group entries of a particular class

  • dir() print the list of entries in the group

  • tree return the list of entries and subentries in the group

  • plot() plot signal and axes for the group, if available

Linked fields or groups (NXlink) have attributes for accessing the link:

* nxlink   reference to the linked field or group
NeXus attributes (NXattr) have a type and a value only::
  • dtype attribute type

  • nxdata attribute data

There is a subclass of NXgroup for each group class defined by the NeXus standard, so it is possible to create an NXgroup of NeXus NXsample directly using:

>>> sample = NXsample()

The default group name will be the class name following the ‘NX’, so the above group will have an nxname of ‘sample’. However, this is overridden by the attribute name when it is assigned as a group attribute, e.g.,

>>> entry.sample1 = NXsample()
>>> entry.sample1.nxname
sample1

You can traverse the tree by component class instead of component name. Since there may be multiple components of the same class in one group you will need to specify which one to use. For example:

tree.NXentry[0].NXinstrument[0].NXdetector[0].distance

references the first detector of the first instrument of the first entry. Unfortunately, there is no guarantee regarding the order of the entries, and it may vary from call to call, so this is mainly useful in iterative searches.

class nexusformat.nexus.tree.NXFile(name, mode='r', recursive=None, **kwargs)

Interface for input/output to NeXus files using h5py.

Usage:

file = NXFile(filename, ['r','rw','w'])
  - open the NeXus file
root = file.readfile()
  - read the structure of the NeXus file.  This returns a NeXus tree.
file.writefile(root)
  - write a NeXus tree to the file.

Example

nx = NXFile(‘REF_L_1346.nxs’,’r’) root = nx.readfile() for entry in root.NXentry:

process(entry)

copy = NXFile(‘modified.nxs’,’w’) copy.writefile(root)

Note that the large datasets are not loaded immediately. Instead, the when the data set is requested, the file is reopened, the data read, and the file closed again.

property root

Return the root group of the NeXus file.

property mtime

Return the modification time of the NeXus file.

property lock

Return the NXLock instance to be used in file locking.

The global variable, NX_LOCK, defines the default timeout in seconds of attempts to acquire the lock. If it is set to 0, the NXFile object is not locked by default. The lock property can be set to turn on file locking, either by setting it to a new timeout value or by setting it to True, in which case a default timeout of 10 seconds is used.

Notes

The default value of NX_LOCK can be set using the nxsetlock function.

Returns

Instance of the file lock.

Return type

NXLock

property locked

Return True if a file lock is active in the current process.

property lock_file

Return the name of the file used to establish the lock.

acquire_lock(timeout=None)

Acquire the file lock.

This uses the NXLock instance returned by self.lock.

Parameters

timeout (int, optional) – Timeout for attempts to acquire the lock, by default None.

release_lock()

Release the lock acquired by the current process.

wait_lock(timeout=True)

Wait for a file lock created by an external process to be cleared.

Parameters

timeout (bool or int, optional) – The value, in seconds, of the time to wait. If set to True, a default value of 10 seconds is used.

clear_lock(timeout=True)

Clear the file lock whether created by this or another process.

Notes

Since the use of this function implies that another process is accessing this file, file locking is turned on for future input/output. The timeout value applies to future access. The existing lock is cleared immediately.

Parameters

timeout (bool or int, optional) – The value, in seconds, of the time to wait for future file locks. If set to True, a default value of 10 seconds is used.

is_locked()

Return True if a lock file exists for this NeXus file.

get(*args, **kwargs)

Return the value defined by the h5py object path.

property file

The h5py File object, which is opened if necessary.

open(**kwargs)

Open the NeXus file for input/output.

close()

Close the NeXus file.

Notes

The file modification time of the root object is updated.

is_open()

Return True if the file is open for input/output in h5py.

is_accessible()

Return True if a lock file exists for this NeXus file.

readfile()

Read the NeXus file and return a tree of NeXus objects.

The hierarchy is traversed using nxpath to record the current location within the file. It is initially set to the root object, i.e., ‘/’.

Notes

This lazily loads all the file objects, i.e., the values stored in large dataset arrays are not read until they are needed.

writefile(root)

Write the whole NeXus tree to the file.

The file is assumed to start empty.

Parameters

root (NXroot) – Root group of the NeXus tree.

readpath(path)

Read the object defined by the given path.

Parameters

path (str) – Path to the NeXus object.

Returns

The group or field defined by the specified path.

Return type

NXgroup or NXfield

readitem()

Read the object defined by the current path.

Returns

The group or field defined by the current path.

Return type

NXgroup or NXfield

readentries(group)

Return the group entries from the file.

Parameters

group (NXgroup) – The group whose entries are to be loaded.

Returns

A dictionary of all the group entries.

Return type

dict

readvalues(attrs=None)

Read the values of the field at the current path.

Notes

The values are only read if the array size is less than 10000.

Parameters

attrs (dict, optional) – Attribute of the field, by default None

Returns

Value, shape, dtype, and attributes of the field

Return type

tuple

readvalue(path, idx=())

Return the array stored in the NeXus file at the specified path.

Parameters
  • path (str) – Path to the NeXus field.

  • idx (tuple, optional) – Slice of field to be returned, by default the whole field.

Returns

Array or string stored in the NeXus file at the current path.

Return type

array_like or str

writevalue(path, value, idx=())

Write a field value at the specified path in the file.

Parameters
  • path (str) – Specified path

  • value (NXfield or array-like) – Value to be written at the specified path.

  • idx (tuple, optional) – Slice to be written, by default the whole field.

move(source, destination)

Move an object defined by its path to another location.

This is an interface to the h5py.Group move function.

Parameters
  • source (str) – Path to the object to be moved.

  • destination (str) – Path of the new destination.

copy(source, destination, **kwargs)

Copy an object defined by its path to another location.

This is an interface to the h5py.Group copy function. All the h5py keyword arguments can be used.

Parameters
  • source (str) – Path to the object to be copied.

  • destination (str) – Path of the new copy.

copyfile(input_file, **kwargs)

Copy an entire NeXus file to another file.

All the h5py.Group.copy() keyword arguments can be used.

Parameters

input_file (NXFile) – NeXus file to be copied.

update(item)

Update the specifed object in the NeXus file.

Notes

If the specified object is an NXobject, it is assumed to contain the path, file, and keyword arguments to be used to copy it to the specified item path, using the h5py.Group copy function.

Parameters

item (NXgroup or NXfield or AttrDict) – Group, field or attributes to be updated in the NeXus file.

reload()

Reload the entire NeXus file.

This may be necessary if another process has modified the file on disk.

rename(old_path, new_path)

Rename an object defined by its path to a new path.

Parameters
  • old_path (str) – Old path to the NeXus object.

  • new_path (str) – New path to the NeXus object.

property filename

The file name on disk.

property mode

File mode of the NeXus file.

property attrs

Attributes of the object defined by the current path.

property nxpath

Current path in the NeXus file.

property nxparent

Path to the parent of the current path.

property nxname

Name of the object at the current path

class nexusformat.nexus.tree.NXobject(*args, **kwargs)

Abstract base class for elements in NeXus files.

The object has a subclass of NXfield, NXgroup, or one of the NXgroup subclasses. Child nodes should be accessible directly as object attributes. Constructors for NXobject objects are defined by either the NXfield or NXgroup classes.

nxclass

The class of the NXobject. NXobjects can have class NXfield, NXgroup, or be one of the NXgroup subclasses.

Type

str

nxname

The name of the NXobject. Since it is possible to reference the same Python object multiple times, this is not necessarily the same as the object name. However, if the object is part of a NeXus tree, this will be the attribute name within the tree.

Type

str

nxgroup

The parent group containing this object within a NeXus tree. If the object is not part of any NeXus tree, it will be set to None.

Type

NXgroup

nxpath

The path to this object with respect to the root of the NeXus tree. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

str

nxroot

The root object of the NeXus tree containing this object. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

NXgroup

nxfile

The file handle of the root object of the NeXus tree containing this object.

Type

NXFile

nxfilename

The file name of NeXus object’s tree file handle.

Type

str

attrs

A dictionary of the NeXus object’s attributes.

Type

dict

dir(attrs=False, recursive=False)

Print the group directory.

The directory is a list of NeXus objects within this group, either NeXus groups or NXfield data. If ‘attrs’ is True, NXfield attributes are displayed. If ‘recursive’ is True, the contents of child groups are also displayed.

Parameters
  • attrs (bool, optional) – Display attributes in the directory if True, by default False.

  • recursive (bool, optional) – Display the directory contents recursively if True, by default False.

property tree

Return the directory tree as a string.

The tree contains all child objects of this object and their children. It invokes the ‘dir’ method with ‘attrs’ set to False and ‘recursive’ set to True.

Returns

String containing the hierarchical structure of the tree.

Return type

str

property short_tree

Return a shortened directory tree as a string.

The tree contains all child objects of this object and their children. It invokes the ‘dir’ method with ‘attrs’ set to False and ‘recursive’ set to True.

Returns

String containing the hierarchical structure of the tree.

Return type

str

rename(name)

Rename the NeXus object.

This changes the signal or axes attributes to use the new name if necessary.

Parameters

name (str) – New name of the NeXus object.

save(filename=None, mode='w-', **kwargs)

Save the NeXus object to a data file.

If the object is an NXroot group, this can be used to save the whole NeXus tree. If the tree was read from a file and the file was opened as read only, then a file name must be specified. Otherwise, the tree is saved to the original file.

An error is raised if the object is an NXroot group from an external file that has been opened as readonly and no file name is specified.

If the object is not an NXroot, group, a filename must be specified. The saved NeXus object is wrapped in an NXroot group (with name ‘root’) and an NXentry group (with name ‘entry’), if necessary, in order to produce a valid NeXus file. Only the children of the object will be saved. This capability allows parts of a NeXus tree to be saved for later use, e.g., to store an NXsample group to be added to another file at a later time.

Parameters
  • filename (str) – Name of the data file.

  • mode (str, optional) – Mode for opening the file, by default ‘w-’

Returns

Tree containing all the NeXus fields and groups saved to the file.

Return type

NXroot

Example

>>> data = NXdata(sin(x), x)
>>> data.save('file.nxs')
>>> print data.nxroot.tree
root:NXroot
  @HDF5_Version = 1.8.2
  @NeXus_version = 4.2.1
  @file_name = file.nxs
  @file_time = 2012-01-20T13:14:49-06:00
  entry:NXentry
    data:NXdata
      axis1 = float64(101)
      signal = float64(101)
        @axes = axis1
        @signal = 1
>>> root['entry/data/axis1'].units = 'meV'
>>> root.save()
copy(name=None, **kwargs)

Returns information allowing the object to be copied.

If no group is specified and the current group is saved to a file, a skeleton group is created with information to be used by a h5py copy. This is resolved when the skeleton group is assigned to a parent group.

Parameters
  • name (str, optional) – Name of copied object if different from current object.

  • **kwargs – Keyword arguments to be transferred to the h5py copy function.

Returns

NeXus object containing information for subsequent copies.

Return type

NXobject

update()

Update the object values in its NeXus file if necessary.

property changed

True if the object has been changed.

This property is for use by external scripts that need to track which NeXus objects have been changed.

set_changed()

Set an object’s change status to changed.

set_unchanged(recursive=False)

Set an object’s change status to unchanged.

property nxclass

NeXus object class.

property nxname

NeXus object name.

property nxgroup

Parent group of NeXus object.

property nxpath

Path to the object in the NeXus tree.

property nxroot

NXroot object of the NeXus tree.

property nxentry

Parent NXentry group of the NeXus object.

property nxfile

NXFile storing the NeXus data.

property nxfilename

File name of the NeXus file containing the NeXus object.

If the NeXus object is an external link, this is the filename containing the linked data.

property nxfilepath

File path containing the NeXus object.

If the NeXus object is an external link, this is the path to the object in the external file.

property nxfullpath

String containing the file name and path of the NeXus object.

property nxfilemode

Read/write mode of the NeXus file if saved to a file.

property nxtarget

Target path of an NXlink.

property attrs

Dictionary of object attributes.

is_plottable()

True if the NeXus object is plottable.

is_linked()

True if the NeXus object is embedded in a link.

is_external()

True if the NeXus object is an external link.

file_exists()

True if the file containing the NeXus object exists.

path_exists()

True if the path to the NeXus object exists.

exists()

True if the NeXus object file and path is accessible.

class nexusformat.nexus.tree.NXfield(value=None, name='unknown', shape=None, dtype=None, group=None, attrs=None, **kwargs)

NeXus field for containing scalars, arrays or strings with attributes.

NXfields usually consist of arrays of numeric data with associated meta-data, the NeXus attributes. The exception is when they contain character strings. This makes them similar to NumPy arrays, and this module allows the use of NXfields in numerical operations in the same way as NumPy arrays. NXfields are technically not a sub-class of the ndarray class, but most NumPy operations work on NXfields, returning either another NXfield or, in some cases, an ndarray that can easily be converted to an NXfield.

Parameters
  • value (int, float, array_like or string) – Numerical or string value of the NXfield, which is directly accessible as the NXfield attribute ‘nxvalue’.

  • name (str) – Name of the NXfield.

  • dtype (np.dtype or str) – Data type of the NXfield value. Valid dtypes correspond to standard NumPy data types, using names defined by the NeXus API, i.e., ‘float32’ ‘float64’ ‘int8’ ‘int16’ ‘int32’ ‘int64’ ‘uint8’ ‘uint16’ ‘uint32’ ‘uint64’ ‘char’ If the data type is not specified, it is determined automatically by the data type of the ‘value’.

  • shape (list of ints) – Shape of the NXfield data. This corresponds to the shape of the NumPy array. Scalars (numeric or string) are stored as zero-rank arrays, for which shape=().

  • group (NXgroup) – Parent group of NeXus field.

  • attrs (dict) – Dictionary containing NXfield attributes.

  • kwargs (dict) – Dictionary containing allowed h5py.Dataset keyword arguments, i.e., ‘chunks’, ‘compression’, ‘compression_opts’, ‘fillvalue’, ‘fletcher32’, ‘maxshape’, ‘scaleoffset’, and ‘shuffle’.

nxclass

The class of the NXobject.

Type

str

nxname

The name of the NXfield. Since it is possible to reference the same Python object multiple times, this is not necessarily the same as the object name. However, if the field is part of a NeXus tree, this will be the attribute name within the tree.

Type

string

nxgroup

The parent group containing this field within a NeXus tree. If the field is not part of any NeXus tree, it will be set to None.

Type

NXgroup

dtype

The data type of the NXfield value. If the NXfield has been initialized but the data values have not been read in or defined, this is a string. Otherwise, it is set to the equivalent NumPy dtype.

Type

string or NumPy dtype

shape

The dimensions of the NXfield data. If the NXfield has been initialized but the data values have not been read in or defined, this is a list of ints. Otherwise, it is set to the equivalent NumPy shape, which is a tuple. Scalars (numeric or string) are stored as NumPy zero-rank arrays, for which shape=().

Type

list or tuple of ints

attrs

A dictionary of all the NeXus attributes associated with the field. These are objects with class NXattr.

Type

dict

nxdata

The data value of the NXfield. This is normally initialized using the ‘value’ parameter (see above). If the NeXus data is contained in a file and the size of the NXfield array is too large to be stored in memory, the value is not read in until this attribute is directly accessed. Even then, if there is insufficient memory, a value of None will be returned. In this case, the NXfield array should be read as a series of smaller slabs using ‘get’.

Type

scalar, NumPy array or string

nxpath

The path to this object with respect to the root of the NeXus tree. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

string

nxroot

The root object of the NeXus tree containing this object. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

NXgroup

Notes

NeXus attributes are stored in the attrs dictionary of the NXfield, but can usually be assigned or referenced as if they are Python attributes, as long as the attribute name is not the same as one of those listed above. This is to simplify typing in an interactive session and should not cause any problems because there is no name clash with attributes so far defined within the NeXus standard. When writing modules, it is recommended that the attributes always be referenced using the attrs dictionary if there is any doubt.

  1. Assigning a NeXus attribute

    In the example below, after assigning the NXfield, the following three NeXus attribute assignments are all equivalent:

    >>> entry['sample/temperature'] = NXfield(40.0)
    >>> entry['sample/temperature'].attrs['units'] = 'K'
    >>> entry['sample/temperature'].units = NXattr('K')
    >>> entry['sample/temperature'].units = 'K'
    
  2. Referencing a NeXus attribute

    If the name of the NeXus attribute is not the same as any of the Python attributes listed above, or one of the methods listed below, or any of the attributes defined for NumPy arrays, they can be referenced as if they were a Python attribute of the NXfield. However, it is only possible to reference attributes with one of the proscribed names using the attrs dictionary.

    >>> entry['sample/temperature'].tree = 10.0
    >>> entry['sample/temperature'].tree
    temperature = 40.0
      @tree = 10.0
      @units = K
    >>> entry['sample/temperature'].attrs['tree']
    NXattr(10.0)
    

Examples

The following examples show how fields can usually be treated like NumPy arrays.

>>> x=NXfield((1.0,2.0,3.0,4.0))
>>> print x+1
[ 2.  3.  4.  5.]
>>> print 2*x
[ 2.  4.  6.  8.]
>>> print x/2
[ 0.5  1.   1.5  2. ]
>>> print x**2
[  1.   4.   9.  16.]
>>> print x.reshape((2,2))
[[ 1.  2.]
 [ 3.  4.]]
>>> y=NXfield((0.5,1.5,2.5,3.5))
>>> x+y
NXfield(array([1.5, 3.5, 5.5, 7.5]))
>>> x*y
NXfield(array([ 0.5,  3. ,  7.5, 14. ]))
>>> (x+y).shape
(4,)
>>> (x+y).dtype
dtype('float64')

All these operations return valid NXfield objects containing the same attributes as the first NXobject in the expression. The ‘reshape’ and ‘transpose’ methods also return NXfield objects.

It is possible to use the standard slice syntax.

>>> x=NXfield(np.linspace(0,10,11))
>>> x
NXfield([  0.   1.   2. ...,   8.   9.  10.])
>>> x[2:5]
NXfield([ 2.  3.  4.])

In addition, it is possible to use floating point numbers as the slice indices. If one of the indices is not integer, both indices are used to extract elements in the array with values between the two index values.

>>> x=NXfield(np.linspace(0,100.,11))
>>> x
NXfield([   0.   10.   20. ...,   80.   90.  100.])
>>> x[20.:50.]
NXfield([ 20.  30.  40.  50.])

The standard NumPy ndarray attributes and methods will also work with NXfields, but will return scalars or NumPy arrays.

>>> x.size
4
>>> x.sum()
10.0
>>> x.max()
4.0
>>> x.mean()
2.5
>>> x.var()
1.25
>>> x.reshape((2,2)).sum(1)
NXfield(array([3., 7.]))

Finally, NXfields are cast as ndarrays for operations that require them. The returned value will be the same as for the equivalent ndarray operation, e.g.,

>>> np.sin(x)
NXfield(array([ 0.        ,  0.84147098,  0.90929743, ...,  0.98935825,
0.41211849, -0.54402111]))
>>> np.sqrt(x)
NXfield(array([0.        , 1.        , 1.41421356, ..., 2.82842712, 3.,
3.16227766]))
any()

Return False if all values are 0 or False, True otherwise.

all()

Return False if any values are 0 or False, True otherwise.

index(value, max=False)

Return the index of a value in a one-dimensional NXfield.

The index is less than (greater than) or equal to the given value for a monotonically increasing (decreasing) array.

Parameters
  • value (int or float) – Value to be indexed.

  • max (bool, optional) – True if the index is greater than (less than) or equal to the value for a monotonically increasing (decreasing) array, by default False.

Returns

Index of value.

Return type

int

Examples

>>> field
NXfield([ 0.   0.1  0.2 ...,  0.8  0.9  1. ])
>>> field.index(0.1)
1
>>> field.index(0.11)
1
>>> field.index(0.11, max=True)
2
>>> reverse_field
NXfield([ 1.   0.9  0.8 ...,  0.2  0.1  0. ])
>>> reverse_field.index(0.89)
1
>>> reverse_field.index(0.89, max=True)
2

The value is considered to be equal to an NXfield element’s value if it differs by less than 1% of the step size to the neighboring element.

min(axis=None)

Return the minimum value of the array ignoring NaNs.

max(axis=None)

Return the maximum value of the array ignoring NaNs.

sum(axis=None)

Return the sum of NXfield values.

Parameters

axis (int or tuple of ints, optional) – Axis or axes to be summed over, by default all axes.

Returns

Summed values.

Return type

NXfield

average(axis=None)

Return the average of NXfield values.

Parameters

axis (int or tuple of ints, optional) – Axis or axes to be averaged, by default all axes.

Returns

Averaged values.

Return type

NXfield

reshape(shape)

Return an NXfield with the specified shape.

transpose()

Return an NXfield containing the transpose of the data array.

centers()

Return a NXfield with bin centers.

This is used for one-dimensional fields containing axes that are stored as bin boundaries.

boundaries()

Return a NXfield with bin boundaries.

This is used for one-dimensional fields containing axes that are stored as bin centers.

add(data, offset)

Add a slab into the data array.

Parameters
  • data (array_like) – Slab values to be added to the field.

  • offset (tuple) – Offsets containing the lowest slab indices.

convert(units='')

Returns the data in the requested units.

This is not currently implemented.

replace(value)

Replace the value of a field.

If the size or dtype of the field differs from an existing field within a saved group, the original field will be deleted and replaced by the newone. Otherwise, the field values are updated.

property nxaxes

List of NXfields containing axes.

If the NXfield does not have the ‘axes’ attribute but is defined as the signal in its parent group, a list of the parent group’s axes will be returned.

valid_axes(axes)

Return True if the axes are consistent with the field.

It checks that all the axes are one-dimensional, and that the size of each axis is equal to or one greater than the field dimension.

Parameters

axes (list) – List of NXfields

Notes

The function removes scalar axes before the check even though these are returned by the nxaxes property. That is because ndim is 0 for scalars. They are automatically removed when plotting so this does not invalidate the check.

property nxvalue

NXfield value.

This is the value stored in the NeXus file, with the following exceptions.

  1. Size-1 arrays are returned as scalars.

  2. String or byte arrays are returns as a list of strings.

Notes

If unmodified values are required, use the nxdata property.

property nxdata

NXfield data as stored in a file.

If the requested data is larger than NX_MEMORY,the return value is None.

property nxtitle

Title as a string.

If there is no title attribute in the parent group, the group’s path is returned.

property mask

NXfield’s mask as an array.

Only works if the NXfield is in a group and has the ‘mask’ attribute set or if the NXfield array is defined as a masked array.

resize(shape, axis=None)

Resize the NXfield.

Parameters
  • shape (tuple of ints) – Requested shape.

  • axis (int, optional) – Axis whose length is to be resized, by default None

checkshape(shape)

Return True if the shape argument is compatible with the NXfield.

property shape

Shape of the NXfield.

property dtype

Dtype of the NXfield.

get_h5opt(name)

Return the option set for the h5py dataset.

Parameters

name (str) – Name of the h5py option.

set_h5opt(name, value)

Set the value of a h5py option.

Parameters
  • name (str) – Name of option.

  • value – Option value.

property compression

NXfield compression.

property compression_opts

NXfield compression options.

property fillvalue

NXfield fill value.

property fletcher32

True if Fletcher32 checksum used.

property chunks

NXfield chunk size.

property maxshape

NXfield maximum shape.

property scaleoffset

NXfield scale offset.

property shuffle

True if the shuffle filter enabled.

property ndim

Rank of the NXfield.

property size

Total size of the NXfield.

property nbytes

Number of bytes in the NXfield array.

property safe_attrs

Attributes that can be safely copied to derived NXfields.

property reversed

True if the one-dimensional field has decreasing values.

property plot_shape

Shape of NXfield for plotting.

Size-1 axes are removed from the shape.

property plot_rank

Rank of the NXfield when plotting.

is_numeric()

True if the NXfield contains numeric data.

is_string()

True if the NXfield contains strings.

is_plottable()

True if the NXfield is plottable.

is_image()

True if the field is compatible with an RGB(A) image.

plot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the NXfield.

The format argument is used to set the color and type of the markers or lines for one-dimensional plots, using the standard Matplotlib syntax. The default is set to blue circles. All keyword arguments accepted by matplotlib.pyplot.plot can be used to customize the plot.

Parameters
  • fmt (str, optional) – Matplotlib format string, by default ‘’

  • xmin (float, optional) – Minimum x-value in plot, by default None

  • xmax (float, optional) – Maximum x-value in plot, by default None

  • ymin (float, optional) – Minimum y-value in plot, by default None

  • ymax (float, optional) – Maximum y-value in plot, by default None

  • vmin (float, optional) – Minimum signal value for 2D plots, by default None

  • vmax (float, optional) – Maximum signal value for 2D plots, by default None

Notes

In addition to the Matplotlib keyword arguments, the following are defined

log = True     - plot the intensity on a log scale
logy = True    - plot the y-axis on a log scale
logx = True    - plot the x-axis on a log scale
over = True    - plot on the current figure
image = True   - plot as an RGB(A) image
oplot(fmt='', **kwargs)

Plot the NXfield over the current figure.

logplot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the NXfield on a log scale.

implot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plots the NXfield as an RGB(A) image.

class nexusformat.nexus.tree.NXgroup(*args, **kwargs)

NeXus group.

This is a subclass of NXobject and is the base class for the specific NeXus group classes, e.g., NXentry, NXsample, NXdata.

Parameters
  • name (str) – The name of the NXgroup. If the NXgroup is initialized as the attribute of a parent group, the name is automatically set to the name of this attribute. If ‘nxclass’ is specified and has the usual prefix ‘NX’, the default name is the class name without this prefix.

  • nxclass (str) – The class of the NXgroup.

  • entries (dict) – A dictionary containing a list of group entries. This is an alternative way of adding group entries to the use of keyword arguments.

  • group (NXgroup) – The parent NeXus group, which is accessible as the group attribute ‘group’. If the group is initialized as the attribute of a parent group, this is set to the parent group.

  • args (NXfield or NXgroup) – Positional arguments must be valid NeXus objects, either an NXfield or a NeXus group. These are added without modification as children of this group.

  • kwargs (dict) – Keyword arguments are used to add children to the group. The keyword values must be valid NeXus objects, either NXfields or NXgroups. The keys are used to set the names within the group.

nxclass

The class of the NXgroup.

Type

str

nxname

The name of the NXfield.

Type

str

entries

A dictionary of all the NeXus objects contained within an NXgroup.

Type

dict

attrs

A dictionary of all the NeXus attributes, i.e., attribute with class NXattr.

Type

AttrDict

nxpath

The path to this object with respect to the root of the NeXus tree. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

str

nxroot

The root object of the NeXus tree containing this object. For NeXus data read from a file, this will be a group of class NXroot, but if the NeXus tree was defined interactively, it can be any valid NXgroup.

Type

NXgroup

Examples

Just as in a NeXus file, NeXus groups can contain either data or other groups, represented by NXfield and NXgroup objects respectively. To distinguish them from regular Python attributes, all NeXus objects are stored in the ‘entries’ dictionary of the NXgroup. However, they can usually be assigned or referenced as if they are Python attributes, i.e., using the dictionary name directly as the group attribute name, as long as this name is not the same as one of the Python attributes defined above or as one of the NXfield Python attributes.

  1. Assigning a NeXus object to a NeXus group

    In the example below, after assigning the NXgroup, the following three NeXus object assignments to entry.sample are all equivalent:

    >>> entry.sample = NXsample()
    >>> entry.sample['temperature'] = NXfield(40.0)
    >>> entry['sample/temperature'] = NXfield(40.0)
    >>> entry.sample.temperature = 40.0
    >>> entry.sample.temperature
    NXfield(40.0)
    

    If the assigned value is not a valid NXobject, then it is cast as an NXfield with a type determined from the Python data type.

    >>> entry.sample.temperature = 40.0
    >>> entry.sample.temperature
    NXfield(40.0)
    >>> entry.data.data.x=np.linspace(0,10,11).astype('float32')
    >>> entry.data.data.x
    NXfield([  0.   1.   2. ...,   8.   9.  10.])
    
  2. Referencing a NeXus object in a NeXus group

    If the name of the NeXus object is not the same as any of the Python attributes listed above, or the methods listed below, they can be referenced as if they were a Python attribute of the NXgroup. However, it is only possible to reference attributes with one of the proscribed names using the group dictionary, i.e.,

    >>> entry.sample.temperature = 100.0
    >>> print entry.sample.temperature
    sample:NXsample
      temperature = 100.0
    >>> entry.sample['temperature']
    NXfield(100.0)
    

    For this reason, it is recommended to use the group dictionary to reference all group objects within Python scripts.

Notes

All NeXus attributes are stored in the ‘attrs’ dictionary of the NXgroup, but can be referenced as if they are Python attributes as long as there is no name clash.

>>> entry.sample.temperature = 40.0
>>> entry.sample.attrs['value'] = 10.0
>>> print(entry.sample.value)
sample:NXsample
  @value = 10.0
  temperature = 40.0
>>> entry.sample.attrs['value']
NXattr(10.0)

Examples

>>> x = NXfield(np.linspace(0,2*np.pi,101), units='degree')
>>> entry = NXgroup(x, name='entry', nxclass='NXentry')
>>> entry.sample = NXgroup(temperature=NXfield(40.0,units='K'),
                       nxclass='NXsample')
>>> print entry.sample.tree
sample:NXsample
  temperature = 40.0
    @units = K

All the currently defined NeXus classes are defined as subclasses of the NXgroup class. It is recommended that these are used directly, so that the above examples become:

>>> entry = NXentry(x)
>>> entry['sample'] = NXsample(temperature=NXfield(40.0,units='K'))

or

>>> entry['sample/temperature'] = 40.0
>>> entry['sample/temperature'].units='K'
walk()

Walk through all the values in the group.

update()

Update the NXgroup, including its children, in the NeXus file.

get(name, default=None)

Retrieve the group entry, or return default if it doesn’t exist.

keys()

Return the names of NeXus objects in the group.

iterkeys()

Return an iterator over group object names.

values()

Return the values of NeXus objects in the group.

itervalues()

Return an iterator over group objects.

items()

Return a list of the NeXus objects as (key,value) pairs.

iteritems()

Return an iterator over (name, object) pairs.

has_key(name)

Return true if an object of the specified name is in the group.

component(nxclass)

Return a list of entries in the group of the same class.

Parameters

nxclass (str) – Class name

Returns

List of fields or groups of the same class.

Return type

list of NXfields or NXgroups

move(item, group, name=None)

Move an item in the group to another group within the same tree.

Parameters
  • item (NXobject or str) – Item to be moved, defined either by the item itself or by its name.

  • group (NXgroup or str) – New group to contain the item.

  • name (str, optional) – Name of the item in the new group. By default, the name is unchanged.

insert(value, name='unknown')

Add an NeXus field or group to the current group.

If it is not a valid NeXus object, the value is converted to an NXfield. If the object is an internal link within an externally linked file, the linked object in the external file is copied.

Parameters
  • value (NXfield or NXgroup or str or array-like) – NeXus field or group to be added.

  • name (str, optional) – Name of the new entry, by default the name of the added object.

Create a linked NXobject within the group.

The root of the target and the child’s group must be the same.

Parameters
  • target (str) – Path to the parent object.

  • name (str, optional) – The name of the linked object, by default the same as the target.

  • abspath (bool, optional) – True if the target is an absolute path, by default False

sum(axis=None, averaged=False)

Return a sum of the signal in the group.

This function should only be used on NXdata groups. The sum is over a single axis or a tuple of axes using the NumPy sum method.

Parameters
  • axis (int, optional) – Axis to be summed, by default all of the axes.

  • averaged (bool, optional) – If True, divide the sum by the signal size, by default False.

Returns

Data group containin the summed values.

Return type

NXdata

Notes

The result contains a copy of all the metadata contained in the NXdata group.

average(axis=None)

Return the average of the signal of the group.

This function should only be used on NXdata groups. The sum is over a single axis or a tuple of axes using the NumPy sum method. The result is then divided by the number of summed bins to produce an average.

Parameters

axis (int, optional) – Axis to be averaged, by default all of the axes.

Returns

Averaged value.

Return type

NXfield

Notes

The result contains a copy of all the metadata contained in the NXdata group.

moment(order=1, center=None)

Return the central moments of the one-dimensional signal.

Parameters
  • order (int, optional) – Order of the calculated moment, by default 1.

  • center (float, optional) – Center if defined externally for use by higher order moments, by default None.

Returns

Value of moment.

Return type

NXfield

mean()

Return the mean value of one-dimensional data.

Returns

The mean of the group signal.

Return type

NXfield

var()

Return the variance of the one-dimensional data.

Returns

The variance of the group signal.

Return type

NXfield

std()

Return the standard deviation of the one-dimensional data.

Returns

The standard deviation of the group signal.

Return type

NXfield

get_default()

Return the default data group if it is defined or None.

Returns

Data group to be plotted.

Return type

NXdata

set_default(over=False)

Set the current group as the default for plotting.

This function is overridden by the NXentry and NXdata classes. For all other groups, it raises an error.

is_plottable()

Return True if the group contains plottable data.

property plottable_data

Return the first NXdata group within the group’s tree.

plot(**kwargs)

Plot data contained within the group.

Valid keyword arguments are passed to Matplotlib.

oplot(**kwargs)

Overplot the group signal over the current figure.

logplot(**kwargs)

Plot the group signal on a log scale.

implot(**kwargs)

Plot the group signal as an RGB(A) image.

signals()

Return a dictionary of NXfield’s containing signal data.

The key is the value of the signal attribute.

property nxtitle

The group title.

If there is no title field in the group or its parent group, the group’s path is returned.

property entries

Dictionary of NeXus objects in the group.

If the NeXus data is stored in a file that was loaded with the ‘recursive’ keyword set to False, only the root entries will have been read. This property automatically reads any missing entries as they are referenced.

Returns

Dictionary of group objects.

Return type

dict of NXfields and/or NXgroups

property entries_loaded

True if the NXgroup entriees have been initialized.

class nexusformat.nexus.tree.NXattr(value=None, dtype=None, shape=None)

Class for NeXus attributes of a NXfield or NXgroup object.

nxvalue

The value of the NeXus attribute modified as described below.

Type

str, scalar, or array-like

nxdata

The unmodified value of the NeXus attribute.

Type

str, scalar, or array-like

dtype

The data type of the NeXus attribute value.

Type

str

shape

The shape of the NeXus attribute value.

Type

tuple

Notes

NeXus attributes are stored in the ‘attrs’ dictionary of the parent object, NXfield or NXgroup, but can often be referenced or assigned using the attribute name as if it were an object attribute.

For example, after assigning the NXfield, the following three attribute assignments are all equivalent:

>>> entry.sample.temperature = NXfield(40.0)
>>> entry.sample.temperature.attrs['units'] = 'K'
>>> entry.sample.temperature.units = NXattr('K')
>>> entry.sample.temperature.units = 'K'

The last version above is only allowed for NXfield attributes and is not allowed if the attribute has the same name as one of the following internally defined attributes, i.e.,

[‘entries’, ‘attrs’, ‘dtype’,’shape’]

or if the attribute name begins with ‘nx’ or ‘_’. It is only possible to reference attributes with one of the proscribed names using the ‘attrs’ dictionary.

property nxvalue

The attribute value for use in Python scripts.

This is the value stored in the NeXus file, with the following exceptions.

  1. Size-1 arrays are returned as scalars.

  2. String or byte arrays are returns as a list of strings.

Notes

If unmodified values are required, use the ‘nxdata’ property.

property nxdata

The attribute value as stored in the NeXus file.

property dtype

The attribute dtype

property shape

The attribute shape.

Parent class for NeXus linked objects.

The link is initialized by specifying the path to the link target and, if the link is to an external file, the filename. When it is possible to access the target, the class of the link is changed to NXlinkfield or NXlinkgroup.

Target of link.

Type

NXfield or NXgroup

update()

Update the NeXus file if necessary.

property nxlink

Target of link.

If called for the first time, this attempts to initialize the link class (NXlinkfield or NXlinkgroup) and attributes if the target is accessible.

Resolve the link class and read in key attributes.

Returns

Target of link.

Return type

NXfield or NXgroup

Return NXfield or NXgroup targeted by an internal link.

Return NXfield or NXgroup targeted by an external link.

property attrs

Return attributes of the linked NXfield or NXgroup.

property nxfilemode

Read/write mode of the NeXus file if saved to a file.

Notes

External links are always read-only.

property abspath

True if the filename is to be stored as an absolute path.

class nexusformat.nexus.tree.NXlinkfield(target=None, file=None, name=None, abspath=False, soft=False, **kwargs)

Class for NeXus linked fields.

property nxdata

Data of linked NXfield.

class nexusformat.nexus.tree.NXlinkgroup(target=None, file=None, name=None, abspath=False, soft=False, **kwargs)

Class for NeXus linked groups.

property entries

Dictionary of NeXus objects in the linked group.

Returns

Dictionary of group objects.

Return type

dict of NXfields and/or NXgroups

exception nexusformat.nexus.tree.NeXusError

NeXus Error

nexusformat.nexus.tree.nxgetcompression()

Return default compression filter.

nexusformat.nexus.tree.nxsetcompression(value)

Set default compression filter.

nexusformat.nexus.tree.nxgetencoding()

Return the default encoding for input strings (usually ‘utf-8’).

nexusformat.nexus.tree.nxsetencoding(value)

Set the default encoding for input strings (usually ‘utf-8’).

nexusformat.nexus.tree.nxgetlock()

Return the number of seconds before a lock acquisition times out.

If the value is 0, file locking is disabled.

Returns

Number of seconds before a lock acquisition times out.

Return type

int

nexusformat.nexus.tree.nxsetlock(value=10)

Initialize NeXus file locking.

This creates a file with .lock appended to the NeXus file name.

Parameters

value (int, optional) – Number of seconds before a lock acquisition times out, by default 10. If the value is set to 0, file locking is disabled.

nexusformat.nexus.tree.nxgetmaxsize()

Return the default maximum size for arrays without using core memory.

nexusformat.nexus.tree.nxsetmaxsize(value)

Set the default maximum size for arrays without using core memory.

nexusformat.nexus.tree.nxgetmemory()

Return the memory limit for data arrays (in MB).

nexusformat.nexus.tree.nxsetmemory(value)

Set the memory limit for data arrays (in MB).

nexusformat.nexus.tree.nxgetrecursive()

Return True if files are opened recursively by default.

Returns

True if files are to be opened recursively.

Return type

bool

nexusformat.nexus.tree.nxsetrecursive(value)

Set whether files are opened recursively by default.

The default can be overridden by setting the ‘recursive’ keyword when opening a file.

Parameters

value (bool) – True if files are to be opened recursively by default.

nexusformat.nexus.tree.nxload(filename, mode='r', recursive=None, **kwargs)

Open or create a NeXus file and load its tree.

Notes

This is aliased to nxload to avoid name clashes with other packages, such as NumPy. nxload is the version included in wild card imports.

Parameters
  • filename (str) – Name of the file to be opened or created.

  • mode ({'r', 'rw', 'r+', 'w', 'a'}, optional) – File mode, by default ‘r’

  • recursive (bool, optional) – If True, the file tree is loaded recursively, by default True. If False, only the entries in the root group are read. Other group entries will be read automatically when they are referenced.

Returns

NXroot object containing the NeXus tree.

Return type

NXroot

nexusformat.nexus.tree.nxsave(filename, group, mode='w', **kwargs)

Write a NeXus file from a tree of NeXus objects.

Parameters
  • filename (str) – Name of the file to be saved.

  • group (NXgroup) – Group containing the tree to be saved.

  • mode ({'w', 'w-', 'a'}, optional) – Mode to be used opening the file, by default ‘w’.

nexusformat.nexus.tree.nxduplicate(input_file, output_file, mode='w-', **kwargs)

Duplicate an existing NeXus file.

Parameters
  • input_file (str) – Name of file to be copied.

  • output_file (str) – Name of the new file.

  • mode ({'w', 'w-', 'a'}, optional) – Mode to be used in opening the new file, by default ‘w-‘.

nexusformat.nexus.tree.nxdir(filename)

Print the contents of the named NeXus file.

Parameters

filename (str) – Name of the file to be read.

nexusformat.nexus.tree.nxdemo(argv)

Process a list of command line commands.

Parameters

argv (list of str) – List of commands.

class nexusformat.nexus.tree.NXroot(*args, **kwargs)

NXroot group, a subclass of the NXgroup class.

This group has additional methods to lock or unlock the tree.

reload()

Reload the NeXus file from disk.

is_modified()

True if the NeXus file has been modified by an external process.

lock()

Make the tree readonly.

unlock()

Make the tree modifiable.

backup(filename=None, dir=None)

Backup the NeXus file.

Parameters
  • filename (str, optional) – Name of file to contain the backup. If not specified, the backup is saved with a randomized name.

  • dir (str, optional) – Directory to contain the backup, by default the current directory.

restore(filename=None, overwrite=False)

Restore a backup.

Parameters
  • filename (str, optional) – Name of file to restore the backup to. If no file name is given, the backup replaces the current NeXus file, provided ‘overwrite’ has been set to True.

  • overwrite (bool, optional) – True if the file is to be overwritten, by default False

close()

Close the underlying HDF5 file.

set_default(over=False)

Override function to set default for plotting.

Parameters

over (bool) – True if previous default should be overwritten

property plottable_data

The default data group to be plotted in this tree.

This will return the default group if the default attribute has been set. Otherwise, the first NXdata, NXmonitor, or NXlog group will be returned.

Returns

Data group to be plotted.

Return type

NXdata

property nxfile

NXFile storing the NeXus data.

property nxbackup

Path to the backup file if it exists.

property mtime

Modification time of the last change to root group.

class nexusformat.nexus.tree.NXentry(*args, **kwargs)

NXentry group, a subclass of the NXgroup class.

set_default(over=False)

Set group as the default for plotting.

This will set defaults for parents of the parent group unless they have been set previously.

Parameters

over (bool) – True if previous default should be overwritten

property plottable_data

The default data group to be plotted in this entry.

This will return the default group if the default attribute has been set. Otherwise, the first NXdata, NXmonitor, or NXlog group will be returned.

class nexusformat.nexus.tree.NXsubentry(*args, **kwargs)

NXsubentry group, a subclass of the NXsubentry class.

class nexusformat.nexus.tree.NXdata(signal=None, axes=None, errors=None, weights=None, *args, **kwargs)

NXdata group, a subclass of the NXgroup class.

The constructor assumes that the first argument contains the signal and the second contains either the axis, for one-dimensional data, or a list of axes, for multidimensional data. These arguments can either be NXfield objects or NumPy arrays, which are converted to NXfield objects with default names. Alternatively, the signal and axes NXfields can be defined using the ‘nxsignal’ and ‘nxaxes’ properties. See the examples below.

Various arithmetic operations (addition, subtraction, multiplication, and division) have been defined for combining NXdata groups with other NXdata groups, NumPy arrays, or constants, raising a NeXusError if the shapes don’t match. Data errors are propagated in quadrature if they are defined, i.e., if the ‘nexerrors’ attribute is not None,

Parameters
  • signal (NXfield) – Field defining the data to be plotted.

  • axes (tuple of NXfields) – Tuple of one-dimensional fields defining the plot axes in the order of the corresponding signal dimensions.

  • errors (NXfield, optional) – Field containing the standard deviations of the signal values.

nxsignal

The NXfield containing the data to be plotted.

Type

NXfield

nxaxes

A tuple of NXfields containing the plot axes

Type

tuple of NXfields

nxerrors

The NXfield containing the standard deviations of the signal values.

Type

NXfield

nxweights

The NXfield containing signal value weights.

Type

NXfield

Examples

There are three methods of creating valid NXdata groups with the signal and axes NXfields defined according to the NeXus standard.

  1. Create the NXdata group with NumPy arrays that will be assigned default names.

    >>> x = np.linspace(0, 2*np.pi, 101)
    >>> line = NXdata(sin(x), x)
    data:NXdata
      signal = float64(101)
        @axes = x
        @signal = 1
      axis1 = float64(101)
    
  2. Create the NXdata group with NXfields that have their internal names already assigned.

    >>> x = NXfield(linspace(0,2*pi,101), name='x')
    >>> y = NXfield(linspace(0,2*pi,101), name='y')
    >>> X, Y = np.meshgrid(x, y)
    >>> z = NXfield(sin(X) * sin(Y), name='z')
    >>> entry = NXentry()
    >>> entry.grid = NXdata(z, (x, y))
    >>> grid.tree()
    entry:NXentry
      grid:NXdata
        x = float64(101)
        y = float64(101)
        z = float64(101x101)
          @axes = x:y
          @signal = 1
    
  3. Create the NXdata group with keyword arguments defining the names and set the signal and axes using the nxsignal and nxaxes properties.

    >>> x = linspace(0,2*pi,101)
    >>> y = linspace(0,2*pi,101)
    >>> X, Y = np.meshgrid(x, y)
    >>> z = sin(X) * sin(Y)
    >>> entry = NXentry()
    >>> entry.grid = NXdata(z=sin(X)*sin(Y), x=x, y=y)
    >>> entry.grid.nxsignal = entry.grid.z
    >>> entry.grid.nxaxes = [entry.grid.x,entry.grid.y]
    >>> grid.tree()
    entry:NXentry
      grid:NXdata
        x = float64(101)
        y = float64(101)
        z = float64(101x101)
          @axes = x:y
          @signal = 1
    
weighted_data()

Return group with the signal divided by the weights

prepare_smoothing()

Create a smooth interpolation function for one-dimensional data.

smooth(n=1001, factor=None, xmin=None, xmax=None)

Return a NXdata group containing smooth interpolations of 1D data.

The number of point is either set by n or by decreasing the average step size by factor - if factor is not None, it overrides the value of n`.

Parameters
  • n (int, optional) – Number of x-values in interpolation, by default 1001

  • factor (int, optional) – Factor by which the step size will be reduced, by default None

  • xmin (float, optional) – Minimum x-value, by default None

  • xmax (float, optional) – Maximum x-value, by default None

Returns

NeXus group containing the interpolated data

Return type

NXdata

select(divisor=1.0, offset=0.0, symmetric=False, smooth=False, max=False, min=False, tol=1e-08)

Return a NXdata group with axis values divisible by a given value.

This function only applies to one-dimensional data.

Parameters
  • divisor (float, optional) – Divisor used to select axis values, by default 1.0

  • offset (float, optional) – Offset to add to selected values, by default 0.0

  • symmetric (bool, optional) – True if the offset is to be applied symmetrically about selections, by default False

  • smooth (bool, optional) – True if data are to be smoothed before the selection, by default False

  • max (bool, optional) – True if the local maxima should be selected, by default False

  • min (bool, optional) – True if the local minima should be selected, by default False

  • tol (float, optional) – Tolerance to be used in defining the remainder, by default 1e-8

Returns

NeXus group containing the selected data

Return type

NXdata

Notes

It is assumed that the offset changes sign when the axis values are negative. So if divisor=1 and offset=0.2, the selected values close to the origin are -1.2, -0.2, 0.2, 1.2, etc. When symmetric is True, the selected values are -1.2, -0.8, -0.2, 0.2, 0.8, 1.2, etc.

The min and max keywords are mutually exclusive. If both are set to True, only the local maxima are returned.

project(axes, limits=None, summed=True)

Return a projection of the data with specified axes and limits.

This function is used to create two-dimensional projections of two- or higher-dimensional data. The axes can be in any order. The limits are defined for all the dimensions. They either define the axis limits in the two-dimensional projection or the range over which the data are summed or averaged for additional dimensions.

Parameters
  • axes (tuple of ints) – Axes to be used in the two-dimensional projection.

  • limits (tuple) – A tuple of minimum and maximum values for each dimension. By default, all values are set to None. For signals of greater than two dimensions, this sums all the data in the orthogonal dimensions.

  • summed (bool, optional) – True if the data is summed over the limits, False if the data is averaged, by default True.

Returns

NXdata group containing the projection.

Return type

NXdata

Notes

Using the default limits=None should be used with caution, since it requires reading the entire data set into memory.

slab(idx)

Return a tuple containing the signal slice and sliced axes.

Real values in the slice objects are converted to array indices given by the axis values of the corresponding dimension.

Parameters

idx (slice) – Indices of the slab.

Returns

Tuple containing the signal slice and a list of sliced axes.

Return type

tuple

get_default()

Return this NXdata group as the default for plotting.

set_default(over=False)

Set group as the default for plotting.

Parameters

over (bool) – True if previous default should be overwritten

property plottable_data

True if the NXdata group is plottable.

property plot_shape

Shape of plottable data.

Size-one axes are removed from the shape.

property plot_rank

Rank of the plottable data.

Size-one axes are removed from the rank.

property plot_axes

Plottable axes.

Size-one axes are removed.

is_image()

True if the data are compatible with an RGB(A) image.

plot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the NXdata group.

The format argument is used to set the color and type of the markers or lines for one-dimensional plots, using the standard Matplotlib syntax. The default is set to blue circles. All keyword arguments accepted by matplotlib.pyplot.plot can be used to customize the plot.

Parameters
  • fmt (str, optional) – Matplotlib format string, by default ‘’

  • xmin (float, optional) – Minimum x-value in plot, by default None

  • xmax (float, optional) – Maximum x-value in plot, by default None

  • ymin (float, optional) – Minimum y-value in plot, by default None

  • ymax (float, optional) – Maximum y-value in plot, by default None

  • vmin (float, optional) – Minimum signal value for 2D plots, by default None

  • vmax (float, optional) – Maximum signal value for 2D plots, by default None

Notes

In addition to the Matplotlib keyword arguments, the following are defined

log = True     - plot the intensity on a log scale
logy = True    - plot the y-axis on a log scale
logx = True    - plot the x-axis on a log scale
over = True    - plot on the current figure
image = True   - plot as an RGB(A) image
oplot(fmt='', **kwargs)

Plot the data over the current figure.

logplot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the data intensity on a log scale.

implot(fmt='', xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the data intensity as an RGB(A) image.

property ndim

Rank of the NXdata signal.

property shape

Shape of the NXdata signal.

property nxsignal

NXfield containing the signal data.

property nxaxes

List of NXfields containing the axes.

property nxerrors

NXfield containing the signal errors.

property nxweights

NXfield containing the signal weights.

property mask

NXfield containing the signal mask if one exists.

This is set to a value of None or np.ma.nomask to remove the mask.

class nexusformat.nexus.tree.NXmonitor(signal=None, axes=None, *args, **kwargs)

NXmonitor group, a subclass of the NXdata class.

class nexusformat.nexus.tree.NXlog(*args, **kwargs)

NXlog group, a subclass of the NXgroup class.

plot(**kwargs)

Plot the logged values against the elapsed time.

Valid Matplotlib parameters, specifying markers, colors, etc, can be specified using the ‘kwargs’ dictionary.

class nexusformat.nexus.tree.NXsample(*args, **kwargs)

NXsample group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXinstrument(*args, **kwargs)

NXinstrument group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXaperture(*args, **kwargs)

NXaperture group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXattenuator(*args, **kwargs)

NXattenuator group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXbeam(*args, **kwargs)

NXbeam group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXbeam_stop(*args, **kwargs)

NXbeam_stop group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXbending_magnet(*args, **kwargs)

NXbending_magnet group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXcapillary(*args, **kwargs)

NXcapillary group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXcite(*args, **kwargs)

NXcite group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXcollection(*args, **kwargs)

NXcollection group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXcollimator(*args, **kwargs)

NXcollimator group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXcrystal(*args, **kwargs)

NXcrystal group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXdetector(*args, **kwargs)

NXdetector group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXdetector_group(*args, **kwargs)

NXdetector_group group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXdetector_module(*args, **kwargs)

NXdetector_module group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXdisk_chopper(*args, **kwargs)

NXdisk_chopper group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXenvironment(*args, **kwargs)

NXenvironment group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXevent_data(*args, **kwargs)

NXevent_data group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXfermi_chopper(*args, **kwargs)

NXfermi_chopper group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXfilter(*args, **kwargs)

NXfilter group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXflipper(*args, **kwargs)

NXflipper group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXgeometry(*args, **kwargs)

NXgeometry group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXgrating(*args, **kwargs)

NXgrating group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXgoniometer(*args, **kwargs)

NXgoniometer group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXguide(*args, **kwargs)

NXguide group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXinsertion_device(*args, **kwargs)

NXinsertion_device group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXmirror(*args, **kwargs)

NXmirror group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXmoderator(*args, **kwargs)

NXmoderator group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXmonochromator(*args, **kwargs)

NXmonochromator group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXnote(*args, **kwargs)

NXnote group, a subclass of the NXgroup class.

class nexusformat.nexus.tree.NXorientation(*args, **kwargs)

NXorientation group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXparameters(*args, **kwargs)

NXparameters group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXpinhole(*args, **kwargs)

NXpinhole group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXpolarizer(*args, **kwargs)

NXpolarizer group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXpositioner(*args, **kwargs)

NXpositioner group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXprocess(*args, **kwargs)

NXprocess group, a subclass of the NXgroup class.

class nexusformat.nexus.tree.NXreflections(*args, **kwargs)

NXreflections group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXsample_component(*args, **kwargs)

NXsample_component group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXsensor(*args, **kwargs)

NXsensor group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXshape(*args, **kwargs)

NXshape group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXslit(*args, **kwargs)

NXslit group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXsource(*args, **kwargs)

NXsource group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXtransformations(*args, **kwargs)

NXtransformations group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXtranslation(*args, **kwargs)

NXtranslation group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXuser(*args, **kwargs)

NXuser group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXvelocity_selector(*args, **kwargs)

NXvelocity_selector group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

class nexusformat.nexus.tree.NXxraylens(*args, **kwargs)

NXxraylens group. This is a subclass of the NXgroup class.

See the NXgroup documentation for more details.

NeXus Plot Module

Module to provide standard Matplotlib plotting to the NeXus Python API.

nexusformat.nexus.plot.centers(axis, dimlen)

Return the centers of the axis bins.

This works regardless of whether the axis consists of bin boundaries, i.e, dimlen = len(axis) + 1`, or centers, i.e., dimlen = len(axis).

Parameters
  • axis (ndarray) – Array containing the axis values.

  • dimlen (int) – Length of corresponding data dimension.

Returns

Array of bin centers with a size of dimlen.

Return type

ndarray

nexusformat.nexus.plot.boundaries(axis, dimlen)

Return the axis bin boundaries.

This works regardless of whether the axis consists of bin boundaries, i.e, dimlen = len(axis) + 1, or centers, i.e., dimlen = len(axis).

Parameters
  • axis (ndarray) – Array containing the axis values.

  • dimlen (int) – Length of corresponding data dimension.

Returns

Array of bin boundaries with a size of dimlen + 1.

Return type

ndarray

nexusformat.nexus.plot.label(field)

Return a label for a data field suitable for use on a graph axis.

This returns the attribute ‘long_name’ if it exists, or the field name, followed by the units attribute if it exists.

Parameters

field (NXfield) – NeXus field used to construct the label.

Returns

Axis label.

Return type

str

class nexusformat.nexus.plot.PylabPlotter

Matplotlib plotter class for 1D or 2D NeXus data.

When the nexusformat package is used within NeXpy, plots are produced by calling the NXPlotView class function, ‘plot’. This provides a function with the same call signature for use outside NeXpy.

plot(data_group, fmt=None, xmin=None, xmax=None, ymin=None, ymax=None, vmin=None, vmax=None, **kwargs)

Plot the NXdata group.

Parameters
  • data_group (NXdata) – NeXus group containing the data to be plotted.

  • fmt (str, optional) – Formatting options that are compliant with PyPlot, by default None

  • xmin (float, optional) – Minimum x-boundary, by default None

  • xmax (float, optional) – Maximum x-boundary, by default None

  • ymin (float, optional) – Minimum y-boundary, by default None

  • ymax (float, optional) – Maximum y-boundary, by default None

  • vmin (float, optional) – Minimum signal value for 2D plots, by default None

  • vmax (float, optional) – Maximum signal value for 2D plots, by default None

  • **kwargs (dict) – Options used to customize the plot.

NeXus Lock Module

Module to provide a file locking mechanism to prevent data corruption.

exception nexusformat.nexus.lock.NXLockException
class nexusformat.nexus.lock.NXLock(filename, timeout=60, check_interval=1)

Class for acquiring and releasing file-based locks.

lock_file

Name of the lock file. This has the extension .lock appended to the name of the locked file.

Type

str

pid

Current process id.

Type

int

fd

File descriptor of the opened lock file.

Type

int

acquire(timeout=None, check_interval=None)

Acquire the lock.

Parameters
  • timeout (int, optional) – Number of seconds to wait for a prior lock to clear before raising a NXLockException, by default self.timeout.

  • check_interval (int, optional) – Number of seconds between attempts to acquire the lock, by default self.check_interval.

Raises

NXLockException – If lock not acquired before timeout.

release()

Release the lock.

Note

This will only work if the lock was created by the current process.

property locked

Return True if the current process has locked the file.

clear()

Clear the lock even if created by another process.

This will either release a lock created by the current process or remove the lock file created by an external process.

Note

This is used to clear stale locks caused by a process that terminated prematurely. It should be used with caution.

wait(timeout=None, check_interval=None)

Wait until an existing lock is cleared.

This is for use in processes checking for external locks.

Parameters
  • timeout (int, optional) – Number of seconds to wait for a prior lock to clear before raising a NXLockException, by default self.timeout.

  • check_interval (int, optional) – Number of seconds between attempts to acquire the lock, by default self.check_interval.

Raises

NXLockException – If lock not cleared before timeout.

NeXus Completer Module

IPython extension to allow autocompletion of NeXus object names.

This modifies h5py.ipy_completer, written by Darren Dale, to accommodate the completion of NeXus paths defined as nested dictionaries. It will also autocomplete attributes at the end of a dictionary path. The NeXus objects can follow an assignment or be embedded in function arguments.

Examples

Autocompletion works on each component of the following commands:

>>> signal = root[entry/data/signal]
>>> units = root[entry/data/signal].units
>>> data = NXdata(root[entry/data/signal])
nexusformat.nexus.completer.nxitem_completer(shell, command)

Compute possible dictionary matches for NXgroups or NXfields.

This matches NeXus objects referenced as nested dictionary paths.

Parameters
  • shell (InteractiveShell) – IPython shell containing the namespace to be searched.

  • command (str) – Command to be autocompleted

Returns

List of possible completions.

Return type

list of str

nexusformat.nexus.completer.nxattr_completer(shell, command)

Compute possible matches for NXgroup or NXfield attributes.

This matches attributes at the end of NeXus dictionary references. If the entire NeXus path is defined using attribute references, then the autocompletion is handled by other completers.

Parameters
  • shell (InteractiveShell) – IPython shell containing the namespace to be searched.

  • command (str) – Command to be autocompleted

Returns

List of possible completions.

Return type

list of str

nexusformat.nexus.completer.nxcompleter(shell, event)

Completer function to be loaded into IPython.

Only text that ends with a valid NXobject is inspected.

Parameters
  • shell (InteractiveShell) – IPython shell containing the namespace to be searched.

  • event – IPython object containing the command to be completed.

Returns

List of possible completions.

Return type

list of str

Raises

TryNext – If no completions are found.

nexusformat.nexus.completer.load_ipython_extension(ip=None)

Load completer function into IPython.

This calls the IPython set_hook function to add nxcompleter to the list of completer functions. This function disables the use of Jedi autcompletion, which is currently incompatible with the nexusformat classes.

Parameters

ip (InteractiveShell, optional) – IPython shell to be modified. By default, it is set by get_ipython().