.. index:: !h5py; code examples

.. _Example-python:

==============
HDF5 in Python
==============

One way to gain a quick familiarity with NeXus is to start working with some data. For at least the
first few examples in this section, we have a simple two-column set of 1-D data, collected as part of a
series of alignment scans by the Advanced Photon Source USAXS instrument during the time it was stationed at
beam line 32ID. We will show how to read and write this data in Python using both the 
``nexusformat`` [#]_ and ``h5py`` [#]_ packages.  The ``nexusformat`` package provides a simplified syntax for 
reading and writing NeXus-compliant files by automatically handling some of the features required by the 
NeXus standard, such as the attributes that define group classes and plottable data. However, it also uses 
the ``h5py`` package to read/write the HDF5 files on disk. We provide tabbed examples showing 
how to produce equivalent files either using ``nexusformat`` or directly in ``h5py``.

The actual data to be written was extracted (elsewhere) from a ``spec`` [#]_ data file 
and read as a text block from a file by the Python source code.
Our examples will start with the simplest case and add only mild complexity with each new case
since these examples are meant for those who are unfamiliar with NeXus.

.. [#] *nexusformat*: https://nexpy.github.io/nexpy/
.. [#] *h5py*: https://www.h5py.org/
.. [#] *SPEC*: http://certif.com/spec.html

Code examples
=============

.. toctree::
	:maxdepth: 1

	simple_example_basic/index
	simple_example_write1/index
	simple_example_write2/index
	external_example_write/index
	plotting/index

* `Write examples with nexusformat for different NeXus classes <https://github.com/nexusformat/exampledata/blob/-/autogenerated_examples/nxdl/python_scripts/nexusformat/README.md>`_
* `Write examples with h5py for different NeXus classes <https://github.com/nexusformat/exampledata/blob/-/autogenerated_examples/nxdl/python_scripts/h5py/README.md>`_

Example data used
=================

The data shown plotted in the next figure will be written to the NeXus HDF5 file
using only two NeXus base classes, ``NXentry`` and ``NXdata``, in the first example
and then minor variations on this structure in the next two examples.  The
data model is identical to the one in the :ref:`Introduction <fig.simple-example>` 
chapter except that the names will be different, as shown below:

.. compound::
	
	.. figure:: ../../img/Simple.png
		:width: 60%
		:alt: simple data structure
		
		data structure of the simple example
	
	.. literalinclude:: simple_example.txt
	    :tab-width: 4
	    :linenos:
	    :language: text
	
	.. _simple-example-plot:
	
	.. figure:: simple_example.png
	    :alt: simple-example-plot
	    :width: 80%
	
	    plot of the simple example data
	
	.. rubric:: Simple example values
	
	.. literalinclude:: simple_example.dat
	    :tab-width: 4
	    :linenos:
	    :language: text