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

To install PIPE, run::

    git clone https://github.com/alphapsa/PIPE.git
    cd PIPE
    python setup.py install

PIPE uses python3 and requires the following packages: numpy, scipy, astropy

Required file structure
+++++++++++++++++++++++

PIPE uses astropy's configuration machinery to manage for your default data and
reference library locations. By default, you will find an empty directory in

.. code-block:: python

    >>> from pipe.config import cache_dir
    >>> print(cache_dir)  # doctest: +SKIP
    '~/.astropy/cache/.pipe-cheops'

Data from DACE should be placed in ``cache_dir``, in a subdirectory called:
``data_root/name/visit/``, where ``name`` is the name of your target, and ``visit``
is an index for the visit number. Output will then be saved to
``data_root/name/visit/Outdata/version/`` where "version" is a number. Multiple
versions can be generated in the ``Outdata`` directory, e.g. from multiple runs
with different input parameters.

Reference files are put into a subdirectory of ``cache_dir`` called
``ref_lib_data/``. These files might include: the gain correction file:
``CH_TU2020-02-18T06-15-13_REF_APP_GainCorrection_V0109.fits``, the flat field
library: ``flats.fits``, and the non-linearity correction: ``nonlin.txt``.

PSF-files that are constructed by PIPE will be stored within ``cache_dir`` in
``ref_lib_data/psf_lib/``, as are ``eigenlib``, libraries of principal PSF
components, also generated.

If you would like to direct PIPE towards different locations for the
``data_root`` and ``ref_lib_data`` directories temporarily (within the specific
Python instance you're currently running), you can set them by setting
the following variables:

.. code-block:: python

    from pipe import conf

    conf.data_root = 'path/to/data_root'
    conf.ref_lib_data = 'path/to/ref_lib_data

If you'd like to set the path to the ``data_root`` and ``ref_lib_data``
directories more permanently, for each and every time PIPE accesses them, you
can edit the paths in ``pipe/config/conf.json`` and run ``python setup.py install``.

Usage
+++++

PIPE needs a library of PSF principal components to extract PSF photometry.
This "eigen" library is generated from derived PSF functions. The PSF functions
can be derived from several visits to improve their quality, in particular if
the visits are short. By default on PSF function is dervied per CHEOPS orbit,
so long visits will have several PSF functions derived.

For a visit, PSF functions are generated by `~pipe.pipe_control.PipeControl.make_psf_lib`.
This is a time consuming process (~ hours) and takes
advantage of multiple CPU cores (up to one thread per PSF being derived).

PCA analysis of the PSFs is fast (a few seconds), and is performed by
`~pipe.pipe_control..PipeControl.make_eigen`.

Once the eigenlib is generated (it is put into ``ref_lib_data/psf_lib/`` by
default) it can be used for photometric extraction. Input parameters are defined
in a `~pipe.pipe_param.PipeParam` object, that is input to a
`~pipe.pipe_control.PipeControl` object.