The fors_img_screen_flat recipe
===============================================================

.. data:: fors_img_screen_flat

Synopsis
--------

Compute master screen flat frame

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

After bias subtraction, the input flat field frames are combined using
the given stack method. The combined frame is finally normalised dividing
it by its large scale illumination trend. The large scale trend is obtained
by applying a median filter with a large kernel. To avoid boundary effects, 
the median filter is applied only to the specified region.

The overscan regions, if present, are removed from the result.


Input files
^^^^^^^^^^^^
::

  DO category:               Type:       Explanation:         Required:
  SCREEN_FLAT_IMG            Raw         Screen flat field    Y
  MASTER_BIAS                Raw         Master bias          Y

Output files
^^^^^^^^^^^^
::

  DO category:               Data type:  Explanation:
  MASTER_SCREEN_FLAT_IMG     FITS image  Master screen flat field

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

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

   Create an object for the recipe fors_img_screen_flat.

::

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

Parameters
----------

.. py:attribute:: fors_img_screen_flat.param.stack_method

    Frames combination method (str; default: 'average') [default="average"].
.. py:attribute:: fors_img_screen_flat.param.minrejection

    Number of lowest values to be rejected (int; default: 1) [default=1].
.. py:attribute:: fors_img_screen_flat.param.maxrejection

    Number of highest values to be rejected (int; default: 1) [default=1].
.. py:attribute:: fors_img_screen_flat.param.klow

    Low threshold in ksigma method (float; default: 3.0) [default=3.0].
.. py:attribute:: fors_img_screen_flat.param.khigh

    High threshold in ksigma method (float; default: 3.0) [default=3.0].
.. py:attribute:: fors_img_screen_flat.param.kiter

    Max number of iterations in ksigma method (int; default: 999) [default=999].
.. py:attribute:: fors_img_screen_flat.param.xradius

    Median filter x radius (unbinned pixels) (int; default: 50) [default=50].
.. py:attribute:: fors_img_screen_flat.param.yradius

    Median filter y radius (unbinned pixels) (int; default: 50) [default=50].
.. py:attribute:: fors_img_screen_flat.param.degree

    Degree of fitting polynomial (int; default: -1) [default=-1].
.. py:attribute:: fors_img_screen_flat.param.sampling

    Sampling interval for fitting (int; default: 100) [default=100].


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

::

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

   fors_img_screen_flat.param.stack_method = "average"
   fors_img_screen_flat.param.minrejection = 1
   fors_img_screen_flat.param.maxrejection = 1
   fors_img_screen_flat.param.klow = 3.0
   fors_img_screen_flat.param.khigh = 3.0
   fors_img_screen_flat.param.kiter = 999
   fors_img_screen_flat.param.xradius = 50
   fors_img_screen_flat.param.yradius = 50
   fors_img_screen_flat.param.degree = -1
   fors_img_screen_flat.param.sampling = 100


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

::

   import cpl
   fors_img_screen_flat = cpl.Recipe("fors_img_screen_flat")
   [...]
   res = fors_img_screen_flat( ..., param = {"stack_method":"average", "minrejection":1})


.. 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 `Jonas M. Larsen <usd-help@eso.org>`_. Alternatively, you may 
send a report to the `ESO User Support Department <usd-help@eso.org>`_.

Copyright
---------

This file is currently part of the FORS Instrument Pipeline
Copyright (C) 2002-2011 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA


.. codeauthor:: Jonas M. Larsen <usd-help@eso.org>