Introduction
============
NeXpy provides a high-level python interface to NeXus data contained within a
simple GUI. It is designed to provide an intuitive interactive toolbox allowing 
users both to access existing NeXus files and to create new NeXus-conforming 
data structures without expert knowledge of the file format.

Installing and Running
======================

Released versions of NeXpy are available on PyPI. If you have the Python Setup 
Tools <https://pypi.python.org/pypi/setuptools> installed, then you can install 
using either::

    $ pip install nexpy

or:: 

    $ easy_install nexpy 

The latest development versions of NeXpy can be downloaded from the NeXpy Git 
repository <https://github.com/nexpy/nexpy>.

    $ git clone https://github.com/nexpy/nexpy.git

To install in the standard Python location:

    $ cd nexpy
    $ python setup.py install

To install in an alternate location:

    $ python setup.py install --prefix=/path/to/installation/dir

Prerequisites
=============
Python Command-Line API
-----------------------
The current version of NeXpy uses h5py to read and write NeXus files because
of its ability to handle large data files. There is therefore no dependency 
on the NeXus C API (http://download.nexusformat.org/doc/html/napi.html). 
This also means that the current version cannot read and write HDF4 or XML 
NeXus files.

If you only intend to utilize the Python API from the command-line, the only 
other required library is Numpy.

* nexusformat (https://github.com/nexpy/nexusformat)
* h5py (http://www.h5py.org)
* numpy (http://numpy.scipy.org/)

NeXpy GUI
---------
The GUI is built using the PyQt. The latest version supports PyQt4, PySide, 
and, with v0.10.0, PyQt5, and should load whichever library it finds. None are 
listed as a dependency but one or other must be installed. PyQt5 is included
in the Anaconda default distribution (https://store.continuum.io/cshop/anaconda/) 
while PySide is included in the Enthought Python Distribution 
(http://www.enthought.com) or within Enthought's Canopy Application 
(https://www.enthought.com/products/canopy/).

The GUI includes an IPython shell (http://ipython.org/) and a 
Matplotlib plotting pane (http://matplotlib.sourceforge.net). The IPython shell 
is embedded in the Qt GUI using an implementation based on the newly-released
Jupyter QtConsole, which has replaced the old IPython QtConsole.
          
* jupyter (http://jupyter.org/)
* IPython v4.0.0 (http://ipython.org/)
* matplotlib v1.4.0 (http://matplotlib.sourceforge.net/)

Some people have reported that NeXpy crashes on launch on some Linux systems.
We believe that this may be due to both PyQt4 and PyQt5 being installed,
although that doesn't cause a problem on all systems. If NeXpy crashes on
launch, please try setting the environment variable QT_API to either 'pyqt',
for the PyQt4 library, 'pyqt5' for the PyQt5 library, or 'pyside', for the 
PySide library, depending on what you have installed, e.g., in BASH, type::

    $ export QT_API=pyqt

Additional Packages
-------------------
Additional functionality is provided by other external Python packages.
Least-squares fitting requires Matt Newville's least-squares fitting package,
lmfit-py. Importers may also require libraries to read the imported files in
their native format, e.g., spec2nexus for reading SPEC files.

From v0.4.3, the log window is colorized if ansi2html is installed.

From v0.9.1, a new 2D smoothing option is available in the list of
interpolations in the signal tab if astropy is installed. It is labelled
'convolve' and provides, by default, a 2-pixel Gaussian smoothing of the
data. The number of pixels can be changed in the shell by setting
'plotview.smooth'.

The following packages are recommended.

* Least-squares fitting: lmfit (http://newville.github.io/lmfit-py/)
* TIFF file imports: tifffile (https://pypi.python.org/pypi/tifffile)
* CBF file imports: pycbf (http://sourceforge.net/projects/cbflib/files/cbflib/pycbf/)
* SPEC file imports: spec2nexus (http://spec2nexus.readthedocs.org/)
* Log file colorization: ansi2html (https://pypi.python.org/pypi/ansi2html/)
* Gaussian smoothing: astropy (http://www.astropy.org)

The following libraries are used by the full installation of NeXpy. There is 
more details of the nature of these dependencies in the NeXpy documentation
(http://nexpy.github.io/nexpy).

PySide v1.1.0        http://www.pyside.org/
jupyter              http://jupyter.org
IPython v1.1.0       http://ipython.org/
h5py                 http://www.h5py.org/
numpy,scipy          http://numpy.scipy.org
matplotlib v1.2.0    http://matplotlib.sourceforge.net
lmfit                http://newville.github.io/lmfit-py (Fitting only)
spec2nexus           http://spec2nexus.readthedocs.org  (SPEC reader only)
astrop

To run with the GUI
===================

To run from the install location, add the $prefix/bin directory to your path
(only if you installed outside the python installation), and then run:

    nexpy

User Support
============
Consult the NeXpy documentation at http://nexpy.github.io/nexpy for details 
of both the Python command-line API and how to use the NeXpy GUI. 

If you discover any bugs, please submit a Github issue to
https://github.com/nexpy/nexpy/issues, preferably with relevant tracebacks.