The vimos_ima_science recipe
===============================================================

.. data:: vimos_ima_science

Synopsis
--------

Science processing for imaging

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

vimos_ima_science -- VIMOS science recipe.


Take a list of science frames and correct them to remove bias, dark
and flat field signatures. Optionally defringe the reddest filter
images. Stack jitter sequences. Astrometrically and photometrically
calibrate the stacks

The program accepts the following files in the SOF:

    Tag                   Description
    OBJECT                A list of raw science images
    MASTER_BIAS           A master bias frame
    MASTER_DARK           A master dark frame
    MASTER_TWILIGHT_FLAT  A master flat frame
    MASTER_CONF           A master confidence map
    MASTER_FRINGE         A master fringe map (optional)
    MASTER_FRINGE_VAR     A master fringe variance map (optional)
    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_APASS_CATALOGUE_ASTROM A master APASS index for astrometry or
    MASTER_LOCAL_CATALOGUE_ASTROM A master local index for astrometry
    MASTER_APASS_CATALOGUE_PHOTOM A master APASS index for photometry or
    MASTER_LOCAL_CATALOGUE_PHOTOM A master local index for photometry or
    OBJECT_CATALOGUE_STD  A master processed standard star image or table
    MATCHSTD_PHOTOM       A master photometric matched standards table (optional)
    SCHLEGEL_MAP_NORTH    Northern Schlegel Map
    SCHLEGEL_MAP_SOUTH    Southern Schlegel Map
    PHOTCAL_TAB           A photometric calibration table
All of these are required unless specified otherwise.


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

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

   Create an object for the recipe vimos_ima_science.

::

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

Parameters
----------

.. py:attribute:: vimos_ima_science.param.savecat

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

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

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

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

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

    Chop crud method (str; default: 'hardconf_pix') [default="hardconf_pix"].
.. py:attribute:: vimos_ima_science.param.cdssearch_astrom

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

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

    Ignore provided fringe frame? (bool; default: False) [default=False].
.. py:attribute:: vimos_ima_science.param.stk_cat_ipix

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

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

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

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

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

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

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

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

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

    Stack using fast algorithm? (str; default: 'auto') [default="auto"].
.. py:attribute:: vimos_ima_science.param.stk_nfst

    Nframes to stack in fast mode (int; default: 16) [default=16].
.. py:attribute:: vimos_ima_science.param.cacheloc

    Location for standard star cache (str; default: '.') [default="."].
.. py:attribute:: vimos_ima_science.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
   vimos_ima_science = cpl.Recipe("vimos_ima_science")

   vimos_ima_science.param.savecat = False
   vimos_ima_science.param.savemstd = False
   vimos_ima_science.param.preview_only = False
   vimos_ima_science.param.minphotom = 1
   vimos_ima_science.param.prettynames = False
   vimos_ima_science.param.chop_crud = "hardconf_pix"
   vimos_ima_science.param.cdssearch_astrom = "none"
   vimos_ima_science.param.cdssearch_photom = "none"
   vimos_ima_science.param.ignore_fringe = False
   vimos_ima_science.param.stk_cat_ipix = 10
   vimos_ima_science.param.stk_cat_thresh = 1.5
   vimos_ima_science.param.stk_cat_icrowd = True
   vimos_ima_science.param.stk_cat_rcore = 10.0
   vimos_ima_science.param.stk_cat_nbsize = 128
   vimos_ima_science.param.stk_lthr = 3.0
   vimos_ima_science.param.stk_hthr = 3.0
   vimos_ima_science.param.stk_method = "linear"
   vimos_ima_science.param.stk_seeing = False
   vimos_ima_science.param.stk_fast = "auto"
   vimos_ima_science.param.stk_nfst = 16
   vimos_ima_science.param.cacheloc = "."
   vimos_ima_science.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
   vimos_ima_science = cpl.Recipe("vimos_ima_science")
   [...]
   res = vimos_ima_science( ..., 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 VIMOS Instrument Pipeline
Copyright (C) 2019 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>
