.. index:: !h5py; code examples

.. _Example-H5py:

============================
HDF5 in Python with ``h5py``
============================

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 APS USAXS instrument during the time it was stationed at
beam line 32ID. We will show how to write this
data using the Python language and the ``h5py`` package [#]_
(:index:`using <h5py>`  ``h5py`` calls directly rather than using the NeXus NAPI). 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.

.. [#] *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 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