Getting started and installation
################################

This document is broken into a few secions. First of all, there is information
about getting a Python installation up and running. This is followed by a
section on the basic usage of these programs to manipulate, plot, and execute
simple non-negative least squares fits on GCMS datasets. The final section
covers generating calibration curves and automating data extraction with this
calibration information. You can skip to that section if all you want to do is
automate some data extractions. (It is not necessary to understand the data
manipulation/plotting as that is automated in the final section.)


Installation
------------

Python
++++++

*Gcmstools* requires Python and a number of third-party packages. Below is a
complete list of packages and minium versions:

* Python >=2.7 (3.x versions not yet supported)
* Pip >=6.0.6 (might be part of new Python releases)
* Setuptools >=11.3.1 (might be part of newer Python releases)
* Numpy >=1.9.1 
* Matplotlib >= 1.4.2
* netCDF4 >=1.0.4
* PyTables >=3.1.1
* Scipy >=0.14.0
* Sphinx >=1.2.2 (Optional for documentation.)

Although not required, IPython (v 2.3.1 tested) provides a very useful
advanced interactive Python interpreter, and examples in this documentation
assume that you are using this environment.

All of these packages can easily be installed using the all-in-one `Anaconda
Python distribution`_. It combines a large number of Python packages for
scientific data analysis and a program (``conda``) for managing package
updates (in addition to many other advanced features). The Anaconda developers
(Continuum Analytics) have a lot of useful documentation for `installing
Anaconda`_ and `using conda`_. There are other ways to install Python and it's
packages, but for this documentation, it will be assumed that Anaconda is
being used.

.. note::

    On Mac/Linux systems, Python is already part of the operating systems.  Do
    not try to install these packages into the builtin Python distribution
    unless you really know what you are doing. You might overwrite and
    important file, which can cause problems for your system.  Confusion
    between the system and Anaconda Python installation is a common source of
    problems for beginners, so make sure that your Anaconda Python is
    "activated" before running the commands in this document. (See the
    Anaconda documentation for more information on the activation process.)
    
.. note::
 
    On Windows, Anaconda may not install netCDF4. In this case, you can get a
    prebuilt installer from `Christoph Gohlke`_: be sure to get the Python 2.7
    ("cp27") 64-bit ("amd64") build for the most recent version. 

Learning the usage of all of these Python packages is far beyond the scope of
this document. However, excellent documentation for most of the packages as
well as full tutorials are `easily discovered`_.

.. _Anaconda Python distribution: http://continuum.io/downloads
.. _installing Anaconda: http://docs.continuum.io/anaconda/
.. _using conda: http://conda.pydata.org/docs/
.. _Christoph Gohlke: http://www.lfd.uci.edu/~gohlke/pythonlibs/
.. _easily discovered: https://google.com

gcmstools
+++++++++

To install *gcmstools* from `the main repository`_, there are two options: 1)
download the source file and install the package or 2) install using ``git``
(recommended). 

*Option 1*

Download a zip file of the current state of the repository. (Look for the
button shown below (:num:`Figure #gitzip`)at `the main repository`_.) Unzip
this package wherever you'd like.

.. _gitzip:

.. figure:: ./_static/images/git_zip.png
    
    The zipfile download button.

From the command line, navigate the newly extracted folder and use ``pip`` to
install the package. (In this case, *path-to-gcmstools-folder* is the location
of the newly unzipped *gcmstools* folder.)

.. code::

    home>$ cd path-to-gcmstools-folder
    gcmstools>$ pip install .

*Option 2 (recommended)*

First, install the `version-control software Git`_. Now, download and install
*gcmstools* with one command.

.. code::

    home>$ pip install git+https://github.com/rnelsonchem/gcms_nnls.git

The advantage here is that the same command will update your *gcmstools*
installation with any any changes that have been made to the main repository. 

*Uninstall*

Uninstallation of *gcmstools* is identical regardless of the installation
method used above.

.. code::

    home>$ pip uninstall gcmstools

.. _the main repository: https://github.com/rnelsonchem/gcms_nnls
.. _version-control software Git: http://git-scm.com/