***************************
Getting started
***************************

Requirements
============

First we need to install the requirements of the ``jwst`` package,
see `the JWST instructions
<https://github.com/spacetelescope/jwst/>`_,
reported here for convenience::

    conda create -n jwst_dev python=3.7 astropy
    source activate jwst_dev

then we need to install the ``jwst`` package, currently ``iris_pipeline``
is being tested with ``jwst`` 0.17.0::

    pip install jwst==0.17.0

Then you need to download the ``CRDS`` cache:

.. code-block:: bash

    git clone https://github.com/oirlab/tmt-crds-cache $HOME/crds_cache

the ``CRDS`` cache contains metadata for IRIS, the calibration files, flat fields,
and a set of rules_ on how to choose the right calibration file given a set of metadata,
you can browse the content on `Github <https://github.com/oirlab/tmt-crds-cache>`_.

.. _rules: https://github.com/oirlab/tmt-crds-cache/blob/master/mappings/tmt/tmt_iris_flat_0001.rmap

We need to set some environment variables so that ``CRDS`` will use the local
cache instead of trying to connect to the JWST instance:

.. code-block:: bash

    source setup_local_crds.sh

Finally, we need a custom version of the ``CRDS`` library that contains some modules specific to TMT::

    git clone https://github.com/oirlab/tmt-crds.git
    cd tmt-crds
    pip install .

Compilation requirements
========================

`iris_pipeline` also includes the `iris_readout` C library wrapped with `cython`,
therefore we require GCC, `autotools` and `libcfitsio` to compile the Python
extension.

In Debian/Ubuntu, the `cfitsio` headers are installed under a prefix, so we need
to include that folder in the search path::

    export C_INCLUDE_PATH=/usr/include/cfitsio/

Development install
===================

First fork the repository under your account on Github,
then clone your fork on your machine.

Initialize the `git` submodule for the `iris_readout` C library::

    git submodule init
    git submodule update

Then enter the root folder and create a development install
with::

  pip install -e .
  
The development install doesn't add the ``tmtrun`` script to the path,
so you should do that manually:

.. code-block:: bash

  export PATH=$(pwd)/scripts/:$PATH

or symlink the ``tmtrun`` script from the conda environment `bin/` folder.

Run the unit tests
------------------

Some of the unit tests of ``iris_pipeline`` are Jupyter Notebooks and they need
the `nbval py.test plugin <https://github.com/computationalmodelling/nbval>`_ to be executed.
Once ``py.test`` and ``nbval`` are installed, execute from the root of the package::

    python setup.py test