The hawki_twilight_flat_combine recipe
===============================================================

.. data:: hawki_twilight_flat_combine

Synopsis
--------

HAWKI twilight combination recipe

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

hawki_twilight_flat_combine -- HAWKI twilight flat combine recipe.


Combine a list of twilight flat frames into a mean frame. Optionally
compare the output frame to a master twilight flat frame

The program accepts the following files in the SOF:

    Tag                   Description
    FLAT_TWILIGHT         A list of raw twilight flat images
    MASTER_DARK           A master dark frame
    REFERENCE_TWILIGHT_FLAT Optional reference twilight flat frame
    MASTER_BPM            Optional master bad pixel map or
    MASTER_CONF           Optional master confidence map
If no reference twilight flat is made available, then no comparison will be
done. This means there will be no output ratio image. If either a masterbad pixel mask or a master confidence map is specified, this will be usedto help mask out bad pixels


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

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

   Create an object for the recipe hawki_twilight_flat_combine.

::

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

Parameters
----------

.. py:attribute:: hawki_twilight_flat_combine.param.lthr

    Low rejection threshold for underexpsed images (float; default:  4000.0) [default=4000.0].
.. py:attribute:: hawki_twilight_flat_combine.param.hthr

    High rejection threshold for overexposed images (float; default:  30000.0) [default=30000.0].
.. py:attribute:: hawki_twilight_flat_combine.param.combtype

    Combination algorithm (str; default: 'median') [default="median"].
.. py:attribute:: hawki_twilight_flat_combine.param.scaletype

    Scaling algorithm (str; default: 'multiplicative') [default="multiplicative"].
.. py:attribute:: hawki_twilight_flat_combine.param.xrej

    True if using extra rejection cycle (bool; default: True) [default=True].
.. py:attribute:: hawki_twilight_flat_combine.param.thresh

    Rejection threshold in sigma above background (float; default: 5.0) [default=5.0].
.. py:attribute:: hawki_twilight_flat_combine.param.ncells

    Number of cells for data channel stats (int; default: 8) [default=8].
.. py:attribute:: hawki_twilight_flat_combine.param.prettynames

    Use pretty output file names? (bool; default: False) [default=False].


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

::

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

   hawki_twilight_flat_combine.param.lthr = 4000.0
   hawki_twilight_flat_combine.param.hthr = 30000.0
   hawki_twilight_flat_combine.param.combtype = "median"
   hawki_twilight_flat_combine.param.scaletype = "multiplicative"
   hawki_twilight_flat_combine.param.xrej = True
   hawki_twilight_flat_combine.param.thresh = 5.0
   hawki_twilight_flat_combine.param.ncells = 8
   hawki_twilight_flat_combine.param.prettynames = False


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

::

   import cpl
   hawki_twilight_flat_combine = cpl.Recipe("hawki_twilight_flat_combine")
   [...]
   res = hawki_twilight_flat_combine( ..., param = {"lthr":4000.0, "hthr":30000.0})


.. 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>