Nexus Python API - README

Contents

• 1. Overview
• 2. Installation
  • 2.1 Requirements
  • 2.2 Building and Installing
  • 2.3 Linux
  • 2.4 Windows
• 3. Using API from Python
  • 3.1 Test Files
  • 3.2 Using The API And An Example
  • 3.3 NeXus API Routines

Overview

NeXus Python Api binds the NeXus libraries to Python. It brings functionality of the NeXus API to Python for reading, writing and modifying NeXus Files. Python NeXus API imitates the functionality NeXus API though with a more object oriented flavour.

Information on NeXus Dataformat: http://www.nexusformat.org/Introduction.

Information on IDL: http://www.nexusformat.org/Introduction.

Installation

Requirements

This package provides a ctypes binding from Python+numpy to the precompiled NeXus library. It has been tested on Python 2.5 in Windows, OS X and Linux. The bindings should be easily modified for any version of Python which supports ctypes and numpy.

The NeXus packages and installation instructions are available at http://www.nexusformat.org/Download.

For Windows the NeXus Data Format Windows Installer Kit, which includes the necessary hdf5, hdf4 and xml libraries, is recommended. http://download.nexusformat.org/kits/windows/

Building and Installing

$ python setup.py install

Using API from Python

Test Files

The Python NeXus-API includes nxstest.py, which provides similar tests to the original C api file napi_test.c.

    python [options] [formats]

Using The API And An Example

The API's functions aim to reproduce the funtionality of the C API closely. Some low level functionality has been hidden from the user. Memory allocation functions NXmalloc and NXfree are done automatically in the API when needed. The file handle is an object with methods rather than a parameter to functions. Instead of checking status codes, errors raise exceptions.

The input and returned values match the format of the data in the files. On return, python creates values of the correct type. However on input, numeric types must be created correctly using numpy.array(...,dtype='type'). The matching datatypes are:

1. Creates a NeXus file with access method HDF5
2. adds datagroups
3. makes a data array of data type NX_INT32
4. puts data to the array
5. reads the data and attributes
6. prints data and attribute value
7. closes the groups and the file.

import nxs,numpy

# Access method accepts strings or integer (e.g., nxs.ACC_CREATE5)
f = nxs.open("test.h5", 'w5')
f.makegroup("testgroup", "NXentry")
f.opengroup("testgroup", "NXentry")
f.makegroup("anothergroup", "NXentry")

# Some data to store in the file, this of type int16
data = numpy.array([[0,1,2,3],[4,5,6,7],[8,9,10,11],[12,13,14,15] ],'int16')

# Make a data set for the array. Note that this could also
# be done as f.makedata('data1','int16',[4,4])
f.makedata('data1', dtype=data.dtype, shape=data.shape)
f.opendata("data1")
f.putdata(data)

# Attribute type can be inferred from the data or specified.  If inferred, it
# must match the type of the data.  Attributes are scalars or strings, with
# string length inferred from value.
f.putattr('integer-attribute', 42, 'int16')
f.putattr('double-attribute', 3.14159)
f.closedata() 
# NeXus returns arrays from getattr/getdata/getslab
f.opendata("data1")
print 'data :',f.getdata()

# getnext functions return tuples
attrname,length,type = f.getnextattr ()
value = f.getattr(attrname, length, type)
print 'first attribute: ', value

# ... or you can use iterators for attrs and entries
print 'all attributes'
for attr,value in f.attrs(): 
    print "  %s: %s"%(attr,value)

f.closedata()
f.closegroup()
f.close()

NeXus API Routines

Documentation for the individual methods, and how they differ from the basic NAPI methods is available from the Python command line. Rather than duplicate it here, use the following in Python:

import nxs
help(nxs)