Addressing objects: the NeXus path

An introduction

Every object within a NeXus file can be addressed by a so called NeXus path. Nexus paths can become rather complex and a good starting point is to have a look on some examples. Lets start with a very simple one

detector_1.nxs://scan_1/instrument/detector/transformation/phi

which refers to the field holding the data of motor phi in the transformation group of a detector. To access the units attribute we could use

detector_1.nxs://scan_1/instrument/detector/transformation/phi@units

However, this path is merely more than a standard HDF5 path with a filename prepended and an attribute name appended to it. To make this path more NeXus-style we can add the group types

detector_1.nxs://scan_1:NXentry/instrument:NXinstrument/ \
                detector:NXdetector/transformation:NXtransformation/phi@units

in which case we do not only specify the names of the groups but also their types. In a final step we could make this path more generic by omitting the group names

detector_1.nxs://:NXentry/:NXinstrument/:NXdetector/:NXtransformation/phi@units

Which would still work if every type appears only once below its parent. However, as we have removed the group names the path becomes generic in a sense that the paths no longer depends on the particular names given to the individual groups. It thus gives more freedom to the beamline scientist naming groups according to his needs and even change the naming over the coarse of time. As long as the overall structure is not altered this approach will still work. It is important to note that the leading : before the group types is requied to indicate the parser that the following string refers to a type rather than to a name.

The anatomy of a Nexus path

A NeXus path consists of three sections

• the file-section determining the file within which a particular object is stored. The file-section preceds the entire path and is terminated by ://.
• the object-section pointing to the object within the file
• and the attribute-section which refers to an attribute stored a the object referenced by the previous object-section. The attribute section consists of the name of the referenced attaribute and is preceded by the @ symbol. The attribute-section follows immediately after the last element of the object-section.

The file- as well as the attribute-section are optional while the object-section is the onmy mandatory path of a path.

The major part of the path is the object-section. The elements of the object section are separated by a / like file- or directory-names on a unix system. For groups an element can have the form name:type while for a field it is only the name. As we have seen in the examples above the name can be omitted group in which case the element reduces to :type.

Path equality and match

Two paths are equal if all their elements (including file and attribute section) are equal. Equality is thus a rather strict criteria when comparing two paths. A more relaxed version is a match. Two paths are matching if they would be in principle able to reference the same object. The problem can be reduced to define when the elements of the object-section are matching. Three rules can be defined which determine whether two elements match

1. Two elements, a and b are matching, if each element they are equal in the strict sense. For instance detector:NXdetector and detector:NXdetector would match, as would data and data.
2. Two elements, a and b are considered matching, if both have the same type and for only one the name field is set. For instance :NXdetector and mythen:NXdetector would match but pilatus:NXdetector and mythen:NXdetector would not.
3. If both have either their name or type field set and those are equal. This is again simple. For instance :NXdetector and :NXdetector would match as well as data and data would.

Using paths

All that theory sounds rather complicated. However, it is quite simple in practice. Nearly all objects in the NeXus API have a path attribute (read-only) which returns the absolute path of an object. It should be mentioned that this path does not include the file name. The latter one could be obtained via the, read-only, filename attribute.

Functions and classes concerning NeXus paths are available from the pni.io.nx package. A NeXus path is represented by an instance of nxpath. The make_path() utiltiy function creates a new instance of a path

from pni.io.nx import nxpath,make_path

p = make_path("/:NXentry/:NXinstrument/:NXdetector/data")

An empyt instance can be obtained by usint the default constructor of nxpath

from pni.io.nx import nxpath

p = nxpath()

The file- and attribute-section of the path is accessible via the filename and attribute attributes of a path instance which are both read- and writeable

from __future__ import print_function
from pni.io.nx import make_path

path = make_path("test.nxs://:NXentry/:NXinstrument/:NXsample/:NXtransformation/x@units")

print(path.filename)
path.filename = "test.nxs"

print(path.attribute)
path.attribute = "units"

For the object-section a path acts like a stack whose first element is accessible via the front and the last element vai the back attribute. These attributes are only readable.

from __future__ import print_function
from pni.io.nx import make_path

path =  make_path("/:NXentry/:NXinstrument")

print(path.front) #output: {'name':'/','base_class':'NXroot'}
print(path.back)  #output: {'name':'','base_class':'NXinstrument'}

The elements of the object-section are represented as Python dictionaries with keys name and base_class where the former one is the name of the group or field and the latter one, in the case of a group, is the value of the NX_class attribute of the object. In the case of fields the base_class entry is always an empty string.

Appending and prepending elements to the object-section

from __future__ import print_function
from pni.io.nx make_path
path = make_path("/")

path.push_back("scan_1:NXentry")
path.push_back(name="instrument",base_class="NXinstrument")

print(path)
#output: scan_1:NXentry/instrument:NXinstrument

path = make_path("scan_1:NXentry/:NXinstrument")
path.push_front("/:NXroot")
print(path)
#output: /scan_1:NXentry/:NXinstrument

Using a path as a stack

from __future__ import print_function
from pni.io.nx import make_path

path = nxpath("/:NXentry/:NXinstrument/mythen:NXdetector/data")
print(path)
#output: /:NXentry/:NXinstrument/mythen:NXdetector/data

print(path.front)
#output: {name:"/",type:"NXroot"}

#remove the root group
path.pop_front()
print(path)
#output: ":NXentry/:NXinstrument/mythen:NXdetector/data"

#remove the back entry
path.pop_back()
print(path)
#output: ":NXentry/:NXinstrument/mythen:NXdetector"

One can iterate of the object-section of a path

from __future__ import print_function
from pni.io.nx import make_path

path = make_path(":NXentry/:NXinstrument/:NXdetector/data")

for e in path:
    print(e["name"],p["base_class"])

Paths can be joined using the + operator

from __future__ import print_function
from pni.io.nx import make_path

a = make_path("/:NXentry/:NXinstrument")
b = make_path(":NXdetector/data")

c = a+b

print(c)
#output: /:NXentry/:NXinstrument/:NXdetector/data

However, the two paths have to follow some rules in order to be joined

• a must not have a attribute-section
• b must not have a file-section
• b must not be an absolute path

Though these rules seem to be complicated at the first glimpse they are totally natural if you think about them for a moment. For instance, how would you join two paths if the left hand side of the operator has an attribute section which is most naturally the terminal element of every path. If any of these rules is violated a ValueError exception will be thrown.

One can also join a path object with a string representing a path

from __future__ import print_function
from pni.io.nx import make_path

base_path     = make_path("/:NXentry/:NXinstrument/")
detector_path = base_path + ":NXdetector"

To check if two paths are matching use the match() function

from __future__ import print_function
from pni.io.nx import make_path,match

det_path = make_path("/:NXentry/:NXinstrument/:NXdetector")
p = make_path("/scan_1:NXentry/p08:NXinstrument/mythen:NXdetector")

print(match(det_path,p))
#output: True