.. _user.desc.basis:

Basis of the librairy
*********************


.. _user.desc.basis.arch:

General architecture
====================

.. _fig.arch:

.. figure:: static/modules.*

    Schematic view of (most of) the library modules (in green)
    and of some required external modules (in red).



The library is organised  as follow:

- :mod:`~vacumm.misc.misc` : Generic place where to put what cannot be placed elsewhere.
- :mod:`~vacumm.misc.axes` : Utilities about CDAT axes.
- :mod:`~vacumm.misc.atime` : Working with time.
- :mod:`~vacumm.misc.color` : Working with colors and colorbars (:mod:`matplotlib`).
- :mod:`~vacumm.misc.config` : Managing advanced configuration (:mod:`configobj`).
- :mod:`~vacumm.misc.core_plot` : Core classes used by :mod:`~vacumm.misc.plot`.
- :mod:`~vacumm.misc.filters` : 1D et 2D filters.
- :mod:`~vacumm.misc.plot` : Plot functions.
- :mod:`~vacumm.misc.stats` : Special statistical functions.
- :mod:`~vacumm.misc.grid` : About CDAT grids.

    - :mod:`~vacumm.misc.grid.misc` : General functions.
    - :mod:`~vacumm.misc.grid.regridding` : Interpolation and regidding.
    - :mod:`~vacumm.misc.grid.kriging` : Pure kriging.
    - :mod:`~vacumm.misc.grid.masking` : Masking data.
    - :mod:`~vacumm.misc.grid.basemap` : Utilities related to geographic maps
      (:mod:`~mpl_toolkits.basemap`).

- :mod:`~vacumm.misc.phys` : About physics.

    - :mod:`~vacumm.misc.phys.constants` : Useful constants.
    - :mod:`~vacumm.misc.phys.units` : Units conversions.

- :mod:`~vacumm.data` : Advanced interfaces to datasets.
- :mod:`~vacumm.diag` : Advanced diagnostics.


.. _user.desc.cdat:

CDAT as numeric basis
=====================

The choice was made to take `CDAT <http://www2-pcmdi.llnl.gov/cdat>`_
as the basis for all library developments.

Array as extended variables [:mod:`MV2`]
----------------------------------------

The numerical vectors used are generated by the module  :mod:`MV2` (:mod:`cdms2`) of CDAT,
if they represent a quantity located in space and/or time.
These tables are not purely numerical and contain in particular:

    - **numerical** values,
    - the associated **mask**,
    - the **axes** (1D or 2D) that locate the variable (longitude, time...),
    - **attributes** (name, units...).

The advantage is that you do not have to pass explicitly and separately
to the functions all this information in addition to the numerical vector.
In addition, these "extended" tables are associated with a large number of functionalities
developed by CDAT, adapted to an oceanographic and meteorological framework.
Finally, let's note that CDAT is an excellent interface for reading and
writing netcdf files.

Consequently, reading and drawing a map will be done
for example as follows:

    >>> import cdms2
    >>> f = cdms2.open('file.nc')
    >>> sst = f('sst') # Lecture
    >>> f.close()
    >>> from vacumm.misc.plot import map
    >>> map(sst) # Plot


The time [:mod:`cdtime`]
------------------------

The time in the sense of the module :mod:`cdtime` of CDAT allows to manage
several types of calendar, consider absolute times (year, month, etc.)
or relative (number and units since a given date)
with no age limit,
and to integrate naturally in the variables :mod:`MV2` to
across time axes.

This is the type of time used as the basis in the library.
Nevertheless, many functions (see :mod:`~vacumm.misc.atime`)
allow conversions to be made to other
time types (string, numeric, :class:`datetime.datetime`, etc).



.. _user.desc.mpl:

Matplotlib as graphic basis
===========================

The library is based almost exclusively on `Matplotlib <http://matplotlib.org>`_ and
`Basemap <http://matplotlib.org/basemap>`_ for all graphics.
Matplotlib is a library allowing to make representations
digital data graphics, in an environment close to Matlab.
The graphics generated are of excellent quality,
and are potentially available in many formats.

The module :mod:`vacumm.misc.plot` merges CDAT and matplotlib.
It contains a set of functions taking as argument CDAT variables.