NeXus Tree API Modules¶
NeXus Tree Module¶
Module to read, write, analyze, manipulate, and visualize NeXus data.
This is designed to accomplish two goals:
To provide convenient access to existing data contained in NeXus files.
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 parameter, 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
- 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.
- 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.
- 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.
- readitem()¶
Read the object defined by the current path.
- readentries(group)¶
Return the group entries from the file.
- 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.
- readvalue(path, idx=())¶
Return the array stored in the NeXus file at the specified path.
- writevalue(path, value, idx=())¶
Write a field value at the specified path in the file.
- move(source, destination)¶
Move an object defined by its path to another location.
This is an interface to the h5py.Group move function.
- 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.
- 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.
- 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.
- 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
- 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
- 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
- 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
- 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
- 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.
- 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
- 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
- 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
- Returns
Tree containing all the NeXus fields and groups saved to the file.
- Return type
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.
- 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’.
- 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
- 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
- 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
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.
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'
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
- Returns
Index of value.
- Return type
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.
- average(axis=None)¶
Return the average of NXfield values.
- moment(order=1, center=None)¶
Return the central moments of a one-dimensional field.
This uses the array indices as the x-values.
- mean()¶
Return the mean value of a one-dimensional field.
- Returns
The mean of the group signal.
- Return type
- var()¶
Return the variance of a one-dimensional field.
- Returns
The variance of the group signal.
- Return type
- std()¶
Return the standard deviation of a one-dimensional field.
- Returns
The standard deviation of the group signal.
- Return type
- reshape(shape)¶
Return an NXfield with the specified shape.
- transpose(axes=None)¶
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.
- 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.
Size-1 arrays are returned as scalars.
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 human_size¶
Human readable string of the number of bytes in the NXfield.
- 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 for multidimensional data.
- 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.
- 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
- 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
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.
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.])
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.
- 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.
- makelink(target, name=None, abspath=False)¶
Create a linked NXobject within the group.
The root of the target and the child’s group must be the same.
- 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
- Returns
Data group containin the summed values.
- Return type
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
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.
- mean()¶
Return the mean value of one-dimensional data.
- Returns
The mean of the group signal.
- Return type
- var()¶
Return the variance of the one-dimensional data.
- Returns
The variance of the group signal.
- Return type
- std()¶
Return the standard deviation of the one-dimensional data.
- Returns
The standard deviation of the group signal.
- Return type
- get_default()¶
Return the default data group if it is defined or None.
- Returns
Data group to be plotted.
- Return type
- 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
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.
Size-1 arrays are returned as scalars.
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.
- class nexusformat.nexus.tree.NXvirtualfield(target, files, name='unknown', shape=None, dtype=None, group=None, attrs=None, abspath=False, create_vds=True, **kwargs)¶
NeXus Virtual Field
This creates a field that is stored as an HDF5 virtual dataset defined by the file path and file names of the source files.
- class nexusformat.nexus.tree.NXlink(target=None, file=None, name=None, group=None, abspath=False, soft=False)¶
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.
- 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.
- initialize_link()¶
Resolve the link class and read in key attributes.
- property internal_link¶
Return NXfield or NXgroup targeted by an internal link.
- property external_link¶
Return NXfield or NXgroup targeted by an external link.
- is_external()¶
True if the NeXus object is 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.nxgetconfig(parameter=None)¶
Return configuration parameter.
- Parameters
parameter (str) – Name of configuration parameter
- nexusformat.nexus.tree.nxsetconfig(**kwargs)¶
Set configuration parameter.
- Parameters
kwargs (dictionary) – Key/value pairs of configuration parameters
- 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
- 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.nxgetlockdirectory()¶
Return the path to the lock directory.
If the value is None, lock files are stored in the same directory as the file.
- Returns
Path to the lock directory.
- Return type
- nexusformat.nexus.tree.nxsetlockdirectory(value)¶
Define a directory to store lock files.
If the value is None, lock files are stored in the same directory as the file.
- Parameters
value (str, optional) – Path to the lock directory.
- nexusformat.nexus.tree.nxgetlockexpiry()¶
Return the number of seconds before a file lock expires.
If the value is 0, the file lock persists indefinitely.
- Returns
Number of seconds before a file lock expires.
- Return type
- nexusformat.nexus.tree.nxsetlockexpiry(value=28800)¶
Sets the lock file expiry.
This creates a file with .lock appended to the NeXus file name.
- Parameters
value (int, optional) – Number of seconds before a lock file is considered stale, by default 8*3600. If the value is set to 0, the file lock persists indefinitely.
- 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
- 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
- nexusformat.nexus.tree.nxopen(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
- nexusformat.nexus.tree.nxsave(filename, group, mode='w', **kwargs)¶
Write a NeXus file from a tree of NeXus objects.
- nexusformat.nexus.tree.nxduplicate(input_file, output_file, mode='w-', **kwargs)¶
Duplicate an existing NeXus file.
- nexusformat.nexus.tree.nxdir(filename, short=False)¶
Print the contents of the named NeXus file.
- nexusformat.nexus.tree.nxconsolidate(files, data_path, scan_path=None)¶
Create NXdata using a virtual field to combine multiple files.
- Parameters
files (list of str or NXroot) – List of files to be consolidated. If a scan variable is defined, the files are sorted by its values.
data (str or NXdata) – Path to the NXdata group to be consolidated. If the argument is a NXdata group, its path within the NeXus file is used.
scan (str or NXfield, optional) – Path to the scan variable in each file, by default None. If the argument is a NXfield, its path within the NeXus file is used. If not specified, the scan is constructed from file indices.
- nexusformat.nexus.tree.nxdemo(argv)¶
Process a list of command line commands.
- Parameters
argv (list of str) – List of commands.
- 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_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.NXbeam(*args, **kwargs)¶
NXbeam 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.NXcylindrical_geometry(*args, **kwargs)¶
NXcylindrical_geometry group. This is a subclass of the NXgroup class.
See the NXgroup documentation for more details.
- 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
- nxaxes¶
A tuple of NXfields containing the plot axes
- Type
tuple of NXfields
Examples
There are three methods of creating valid NXdata groups with the signal and axes NXfields defined according to the NeXus standard.
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)
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
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
- Returns
NeXus group containing the interpolated data
- Return type
- 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
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
Notes
Using the default limits=None should be used with caution, since it requires reading the entire data set into memory.
- transpose(axes=None)¶
Transpose the signal array and axes.
- Parameters
axes (tuple or list of ints, optional) – If specified, it must be a tuple or list which contains a permutation of [0,1,..,N-1] where N is the number of axes. If not specified, defaults to range(self.ndim)[::-1].
- Returns
NXdata group containing the data with transposed axes.
- Return type
- 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.
- 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 nxangles¶
Attribute containing angles between the axes in degrees.
- 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.NXdetector_channel(*args, **kwargs)¶
NXdetector_channel 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.NXdetector(*args, **kwargs)¶
NXdetector 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.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.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.NXfresnel_zone_plate(*args, **kwargs)¶
NXfresnel_zone_plate 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.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.NXinstrument(*args, **kwargs)¶
NXinstrument group. This is a subclass of the NXgroup class.
See the NXgroup documentation for more details.
- 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.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.NXmonitor(signal=None, axes=None, *args, **kwargs)¶
NXmonitor group, a subclass of the NXdata class.
- 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.NXoff_geometry(*args, **kwargs)¶
NXoff_geometry group. This is a subclass of the NXgroup class.
See the NXgroup documentation for more details.
- 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.NXpdb(*args, **kwargs)¶
NXpdb 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.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.
- restore(filename=None, overwrite=False)¶
Restore a backup.
- 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
- 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.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.NXsample(*args, **kwargs)¶
NXsample 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.NXsubentry(*args, **kwargs)¶
NXsubentry group, a subclass of the NXsubentry class.
- 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.
- class nexusformat.nexus.tree.NXgoniometer(*args, **kwargs)¶
NXgoniometer 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.
- class nexusformat.nexus.plot.PyplotPlotter¶
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.
Note
If the qualitative color map, ‘tab10’, is specified as a keyword argument, the color scale is chosen so that all the integer values are centered on each color band, if the maximum intensity is less than 10.
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=None, check_interval=1, expiry=28800, directory=None)¶
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
- acquire(timeout=None, check_interval=None, expiry=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.
expiry (int, optional) – Number of seconds after which a lock expires, by default self.expiry.
- 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
- Raises
NXLockException – If lock not cleared before timeout.
- is_stale(expiry=None)¶
Return True if the lock file is older than one day.
If the lock file has been cleared before this check, the function returns False to enable another attempt to acquire it.
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().