The **gridDataFormats** package provides classes to unify reading and
writing n-dimensional datasets. One can read grid data from files,
make them available as a ``Grid`` object, and allows one to
write out the data again.

The Grid class
==============

A ``Grid`` consists of a rectangular, regular, N-dimensional
array of data. It contains

(1) The position of the array cell edges.
(2) The array data itself.


This is equivalent to knowing

(1) The origin of the coordinate system (i.e. which data cell
    corresponds to (0,0,...,0)
(2) The spacing of the grid in each dimension.
(3) The data on a grid.

``Grid`` objects have some convenient properties:

* The data is represented as a ``numpy.array`` and thus shares
  all the advantages coming with this sophisticated and powerful
  library.

* They can be manipulated arithmetically, e.g. one can simply add or
  subtract two of them and get another one, or multiply by a
  constant. Note that all operations are defined point-wise (see the
  NumPy documentation for details) and that only grids defined
  on the same cell edges can be combined.

* A ``Grid`` object can also be created from within python code
  e.g. from the output of the `numpy.histogramdd`_ function.

* The representation of the data is abstracted from the format that
  the files are saved in. This makes it straightforward to add
  additional readers for new formats.

* The data can be written out again in formats that are understood by
  other programs such as VMD_ or PyMOL_.

.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
.. _PyMOL: http://www.pymol.org/
.. _`numpy.histogramdd`: http://docs.scipy.org/doc/numpy/reference/generated/numpy.histogramdd.html
.. _OpenDX: http://www.opendx.org

Supported file formats
----------------------

The package can be easily extended. The OpenDX_ format is widely
understood by many molecular viewers and is sufficient for many
applications that were encountered so far. Hence, at the moment only a
small number of file formats is directly supported.

==========  =========  =====  =====  =========================================
format      extension  read   write  remarks
==========  =========  =====  =====  =========================================
OpenDX_     dx         x      x      subset of OpenDX implemented
gOpenMol    plt        x
pickle      pickle     x      x      standard Python pickle of the Grid class
==========  =========  =====  =====  =========================================


Examples
========

In most cases, only one class is important, the
``gridData.Grid``, so we just load this right away::

  from gridData import Grid


Loading data
------------

From a OpenDX file::

  g = Grid("density.dx")

From a gOpenMol PLT file::

  g = Grid("density.plt")

From the output of `numpy.histogramdd`_::

  import numpy
  r = numpy.random.randn(100,3)
  H, edges = numpy.histogramdd(r, bins = (5, 8, 4))
  g = Grid(H, edges=edges)

For other ways to load data, see the docs for ``gridData.Grid``



Subtracting two densities
-------------------------

Assuming one has two densities that were generated on the same grid
positions, stored in files ``A.dx`` and ``B.dx``, one first reads the
data into two ``Grid`` objects::

  A = Grid('A.dx')
  B = Grid('B.dx')

Subtract A from B::

  C = B - A

and write out as a dx file::

  C.export('C.dx')

The resulting file ``C.dx`` can be visualized with any OpenDX-capable
viewer, or later read-in again.


Resampling
----------

Load data::

 A = Grid('A.dx')

Interpolate with a cubic spline to twice the sample density::

 A2 = A.resample_factor(2)

Downsample to half of the bins in each dimension::

 Ahalf = A.resample_factor(0.5)

Resample to the grid of another density, B::

 B = Grid('B.dx')
 A_on_B = A.resample(B.edges)

or even simpler ::

 A_on_B = A.resample(B)

.. Note:: The cubic spline generates region with values that did not
   occur in the original data; in particular if the original data's
   lowest value was 0 then the spline interpolation will probably
   produce some values <0 near regions where the density changed
   abruptly.
