The hawki_science_process recipe
===============================================================

.. data:: hawki_science_process

Synopsis
--------

HAWKI jitter recipe

Description
-----------

hawki_science_process -- HAWKI science product recipe.


Process a complete pawprint of HAWKI data. Remove instrumental
signature, remove sky background, combine jitters, photometrically
and astrometrically calibrate the pawprint image

The program accepts the following files in the SOF:

    Tag                   Description
    OBJECT                A list of raw science images 
    SKY                   A list of offset sky exposures (optional)
    MASTER_DARK           A master dark frame
    MASTER_TWILIGHT_FLAT  A master twilight flat frame
    MASTER_SKY            A master sky frame (optional)
    MASTER_SKY_VAR        A master sky variance frame (optional)
    PHOTCAL_TAB           A photometric calibration table
    MASTER_CONF           A master confidence map
    MASTER_READGAIN       A master readgain table
    MASTER_2MASS_CATALOGUE_ASTROM A master 2MASS index for astrometry or
    MASTER_PPMXL_CATALOGUE_ASTROM A master PPMXL index for astrometry or
    MASTER_LOCAL_CATALOGUE_ASTROM A master local astrometric FITS file
    MASTER_2MASS_CATALOGUE_PHOTOM A master 2MASS index for photometry or
    MASTER_PPMXL_CATALOGUE_PHOTOM A master PPMXL index for photometry or
    MASTER_LOCAL_CATALOGUE_PHOTOM A master local photometric FITS file
    MATCHSTD_PHOTOM       A master matched standards catalogue for photometry
    MASTER_OBJMASK        A master object mask (optional)
    SCHLEGEL_MAP_NORTH    Northern Schlegel Map
    SCHLEGEL_MAP_SOUTH    Southern Schlegel Map
All of the above are required unless specifically tagged as optional. Theastrometric and photometric files are not required if these can be obtainedfrom the CDS using the --cdssearch options


Constructor
-----------

.. method:: cpl.Recipe("hawki_science_process")
   :noindex:

   Create an object for the recipe hawki_science_process.

::

   import cpl
   hawki_science_process = cpl.Recipe("hawki_science_process")

Parameters
----------

.. py:attribute:: hawki_science_process.param.savecat

    Save catalogue? (bool; default: False) [default=False].
.. py:attribute:: hawki_science_process.param.savemstd

    Save matched standard catalogues? (bool; default: False) [default=False].
.. py:attribute:: hawki_science_process.param.skyalgo

    Sky subtraction algorithm (str; default: 'auto') [default="auto"].
.. py:attribute:: hawki_science_process.param.preview_only

    Preview only? (bool; default: False) [default=False].
.. py:attribute:: hawki_science_process.param.minphotom

    Minimum stars for photometry solution (int; default: 1) [default=1].
.. py:attribute:: hawki_science_process.param.prettynames

    Use pretty product names? (bool; default: False) [default=False].
.. py:attribute:: hawki_science_process.param.cdssearch_astrom

    CDS astrometric catalogue (str; default: 'none') [default="none"].
.. py:attribute:: hawki_science_process.param.cdssearch_photom

    CDS photometric catalogue (str; default: 'none') [default="none"].
.. py:attribute:: hawki_science_process.param.stk_cat_ipix

    Minimum pixel area for each detected object (int; default: 10) [default=10].
.. py:attribute:: hawki_science_process.param.stk_cat_thresh

    Detection threshold in sigma above sky (float; default: 2.5) [default=2.5].
.. py:attribute:: hawki_science_process.param.stk_cat_icrowd

    Use deblending? (bool; default: True) [default=True].
.. py:attribute:: hawki_science_process.param.stk_cat_rcore

    Value of Rcore in pixels (float; default: 10.0) [default=10.0].
.. py:attribute:: hawki_science_process.param.stk_cat_nbsize

    Background smoothing box size (int; default: 128) [default=128].
.. py:attribute:: hawki_science_process.param.stk_lthr

    Low rejection threshold (float; default: 5.0) [default=5.0].
.. py:attribute:: hawki_science_process.param.stk_hthr

    Upper rejection threshold (float; default: 5.0) [default=5.0].
.. py:attribute:: hawki_science_process.param.stk_method

    Stacking method (str; default: 'linear') [default="linear"].
.. py:attribute:: hawki_science_process.param.stk_seeing

    Weight by seeing? (bool; default: False) [default=False].
.. py:attribute:: hawki_science_process.param.stk_fast

    Use fast stacking? (str; default: 'auto') [default="auto"].
.. py:attribute:: hawki_science_process.param.stk_nfst

    Nframes for slow stacking (int; default: 30) [default=30].
.. py:attribute:: hawki_science_process.param.psm_ipix

    Minimum pixel area for each detected object (int; default: 10) [default=10].
.. py:attribute:: hawki_science_process.param.psm_niter

    Number of iterations in pawsky mask (int; default: 5) [default=5].
.. py:attribute:: hawki_science_process.param.psm_thresh

    Detection threshold in sigma above sky (float; default: 1.5) [default=1.5].
.. py:attribute:: hawki_science_process.param.psm_nbsize

    Background smoothing box size (int; default: 128) [default=128].
.. py:attribute:: hawki_science_process.param.psm_smkern

    Smoothing kernel size (pixels) (float; default: 2.0) [default=2.0].
.. py:attribute:: hawki_science_process.param.cacheloc

    Location for standard star cache (str; default: '.') [default="."].
.. py:attribute:: hawki_science_process.param.magerrcut

    Magnitude error cut (float; default: 100.0) [default=100.0].


The following code snippet shows the default settings for the available 
parameters.

::

   import cpl
   hawki_science_process = cpl.Recipe("hawki_science_process")

   hawki_science_process.param.savecat = False
   hawki_science_process.param.savemstd = False
   hawki_science_process.param.skyalgo = "auto"
   hawki_science_process.param.preview_only = False
   hawki_science_process.param.minphotom = 1
   hawki_science_process.param.prettynames = False
   hawki_science_process.param.cdssearch_astrom = "none"
   hawki_science_process.param.cdssearch_photom = "none"
   hawki_science_process.param.stk_cat_ipix = 10
   hawki_science_process.param.stk_cat_thresh = 2.5
   hawki_science_process.param.stk_cat_icrowd = True
   hawki_science_process.param.stk_cat_rcore = 10.0
   hawki_science_process.param.stk_cat_nbsize = 128
   hawki_science_process.param.stk_lthr = 5.0
   hawki_science_process.param.stk_hthr = 5.0
   hawki_science_process.param.stk_method = "linear"
   hawki_science_process.param.stk_seeing = False
   hawki_science_process.param.stk_fast = "auto"
   hawki_science_process.param.stk_nfst = 30
   hawki_science_process.param.psm_ipix = 10
   hawki_science_process.param.psm_niter = 5
   hawki_science_process.param.psm_thresh = 1.5
   hawki_science_process.param.psm_nbsize = 128
   hawki_science_process.param.psm_smkern = 2.0
   hawki_science_process.param.cacheloc = "."
   hawki_science_process.param.magerrcut = 100.0


You may also set or overwrite some or all parameters by the recipe 
parameter `param`, as shown in the following example:

::

   import cpl
   hawki_science_process = cpl.Recipe("hawki_science_process")
   [...]
   res = hawki_science_process( ..., param = {"savecat":False, "savemstd":False})


.. seealso:: `cpl.Recipe <https://packages.python.org/python-cpl/recipe.html>`_
   for more information about the recipe object.

Bug reports
-----------

Please report any problems to `Jim Lewis <jrl@ast.cam.ac.uk>`_. Alternatively, you may 
send a report to the `ESO User Support Department <usd-help@eso.org>`_.

Copyright
---------

This file is part of the HAWKI Instrument Pipeline
Copyright (C) 2015 European Southern Observatory

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
MA  02111-1307  USA

.. codeauthor:: Jim Lewis <jrl@ast.cam.ac.uk>
