Volume I: NeXus User Manual
Prev		Next

Volume I: NeXus User Manual

Id: 984:1037M, Thu Jan 26 13:27:13 GMT 2012

Ray Osborn

Argonne National Laboratory

<rosborn@anl.gov>

Mark Koennecke

Paul Scherrer Institut

<Mark.Koennecke@psi.ch>

Przemek Klosowski

U. of Maryland and NIST

<przemek.klosowski@nist.gov>

Frederick Akeroyd

Rutherford Appleton Laboratory

<freddie.akeroyd@stfc.ac.uk>

Peter F. Peterson

Spallation Neutron Source

<petersonpf@ornl.gov>

Pete R. Jemian

Advanced Photon Source

<jemian@anl.gov>

Stuart I. Campbell

Oak Ridge National Laboratory

<campbellsi@ornl.gov>

Tobias Richter

Diamond Light Source Ltd.

<Tobias.Richter@diamond.ac.uk>

This version of the NeXus documentation is still in draft. Expected release is fall-2011.

The NeXus manual is licensed under the terms of the GNU Free Documentation License version 1.3. See the FDL license file included with the source of this manual or refer to http://www.gnu.org/licenses/fdl-1.3.txt for more details.

The examples in the NeXus manual are licensed under the terms of the GNU Lesser General Public License version 3. See the LGPL license file included with the source of this manual or refer to http://www.gnu.org/licenses/lgpl-3.0.txt for more details.

2011

Revision History
	2009	PFP
Started conversion from the old NeXus mediawiki documentation.
Revision initial draft	2010 spring	PRJ
Most of the content from the old NeXus mediawiki documentation is included. Some new wiki content has been introduced but should be easy to identify for inclusion in the manual.
Revision draft	2010-11	PRJ
Nearly complete but still much finishing work remains. The description of dimensions and the description of the coordinate system needs major revision and improvement. More examples are needed. The manual is now divided into two volumes. Volume I is the User Manual, Volume II is the Reference Documentation. Much of the NXDL chapter in Volume II is autogenerated from the `nxdl.xsd` Schema and the NXDL source files. Initial release of NXDL, manual, and next release of NAPI (compatibility release) expected in mid-2011.
Revision 1.0b	2011-11	PRJ
Preparing manual for initial release. Also preparing to convert manual source from DocBook to Sphinx for next release of manual.

Table of Contents

Preface

Representation of data examples
Class path specification

1. NeXus Introduction

What is NeXus?

A Set of Design Principles
A Set of Data Storage Objects
A Set of Subroutines
Scientific Community

Motivations for the NeXus standard in the Scientific Community

Simple plotting
Unified format for reduction and analysis
Defined dictionary of terms

NAPI: The NeXus Application Programming Interface

How do I write a NeXus file?
How do I read a NeXus file?
How do I browse a NeXus file?

2. NeXus Design

NeXus Objects and Terms

Data Groups
Data Fields
Data Attributes
Links
NeXus Base Classes
NeXus Application Definitions

NeXus Coordinate Systems

McStas and NXgeometry System
Simple (Spherical Polar) Coordinate System
Coordinate Transformations

Rules for Structuring Information in NeXus Files

Content of a Raw Data NXentry Group
Content of a processed data NXentry group
NXsubentry or Multi-Method Data
Rules for Special Cases

Rules for Storing Data Items in NeXus Files

Naming Conventions
NeXus Array Storage Order
NeXus Data Types
NeXus Data Units
Linking Multi Dimensional Data with Axis Data
Storing Detectors
Monitors are Special
Find the plottable data

Physical File format

Choice of HDF as Underlying File Format
Mapping NeXus into HDF
Mapping NeXus into XML
Special Attributes

3. Constructing NeXus Files and Application Definitions

The WOnderful New Instrument (WONI)

Constructing a NeXus file for WONI

Decide which parameters need to be stored
Mapping parameters to NeXus
Decide on NXdata
Fill in auxiliary Information

Creating a NXDL Specification

Application Definition Steps
Step 1: Think! hard about data
Step 2: Map Data into the NeXus Hierarchy
Step 3: Describe this map in a NXDL file
Step 4: Standardize with the NIAC
Full listing of the WONI Application Definition
Using an Application Definition

Processed Data

4. Brief history of the NeXus format

5. NeXus Community

NIAC: The NeXus International Advisory Committee

NeXus Mailing Lists

NeXus Subversion Repositories

Login
Committing Changes
URLs described in this section

NeXus Issue Reporting

A. Installation

Precompiled Binary Installation

Prerequisites
Linux RPM Distribution Kits
Microsoft Windows Installation Kit
Mac OS X Installation Kit

Source Installation

NeXus Source Code Distribution
Cygwin Kits

B. Verification and validation of files

Overview

Definitions of these terms

NeXus data files may use multiple base classes or application definitions

Validation techniques

Validation of NeXus data files
Validation of NeXus Definition Language (NXDL) specification files
Validation of the NXDL rules
Validation of XSLT files
Transformation of NXDL files to Schematron

C. NeXus Utilities

Utilities supplied with NeXus
Data Analysis
HDF Tools

D. Frequently Asked Questions

E. Licenses

FDL: GNU Free Documentation License
LGPL: GNU Lesser Gnu Public License

Index

List of Figures

1. example of NeXus data
1.1. Example of a NeXus file
1.2. NXinstrument excerpt
1.3. Simple Example
1.4. N separate file formats
1.5. N separate file formats joined by a common NeXus converter
2.1. Linking in a NeXus file
2.2. The McStas Coordinate System
2.3. NeXus Simple (Spherical Polar) Coordinate System
2.4. NeXus Raw Data Hierarchy
2.5. NeXus Processed Data Hierarchy
2.6. NeXus Multi Method Hierarchy
2.7. NeXus Simple Scan Example
2.8. NeXus Simple Scan Example with Area Detector
2.9. NeXus Complex hkl Scan
2.10. NeXus Multi-parameter scan: XAS
2.11. NXcollection Example
3.1. The (fictional) WONI example powder diffractometer
3.2. Example Powder Diffraction Plot from (fictional) WONI at HYNES
3.3. Basic structure of a NeXus file
3.4. Basic structure of a NeXus file with a monochromator added
B.1. Flowchart of the NeXus validation process.

List of Tables

2.1. NeXus File Global Attributes
2.2. NeXus Data Attributes. For the full specification of attributes, see the NXDL section in Volume II of the manual.
2.3. Actions of standard NeXus fields
2.4. Matching regular expressions for NeXus data types
3.1. basic information required from WONI
3.2. Full mapping of WONI data into NeXus
5.1. TRAC RSS feed

List of Examples

1.1. verysimple.xml: A very simple NeXus Data file (in XML)
1.2. verysimple.py: Using NeXpy to write a very simple NeXus Data file (in HDF5)
1.3. verysimple.nxdl.xml: A very simple NeXus Definition Language (NXDL) file
1.4. Simple example of reading data using the NeXus API
1.5. Writing a simple NeXus file using NAPI
1.6. Reading a simple NeXus file using NAPI
1.7. Using nxbrowse
2.1. implicit order of NeXus spherical coordinate system
2.2. Regular expression pattern for NXDL group and field names
2.3. Offset and Stride for 1 D data:
2.4. Offset and Stride for 2D Data
2.5. Offset and Stride for 3D Data
2.6. strftime() format specifiers for ISO-8601 time
2.7. Preferred way of denoting axes
2.8. Original way of denoting axes
2.9. h5dump of a NeXus NXentry group
2.10. h5dump of a NeXus field (HDF5 dataset)
2.11. h5dump of a NeXus attribute
2.12. h5dump of a NeXus link
2.13. NeXus group element in XML
2.14. NeXus data elements
3.1. NXDL template file
B.1. Use of xmllint to validate a NXDL specification.
B.2. Use of xmllint to validate the NXDL rules.