The vmspflat recipe
===============================================================

.. data:: vmspflat

Synopsis
--------

Build master flat field from a set of raw MOS flat fields.

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

This recipe is used to create the MOS normalised master flat field
from a set of MOS flat field exposures. A _not_ normalised master
flat field is also required by the recipe vmspcaldisp to determine
the spectral curvature model. The recipe vmspflat does compute its
own curvature model, but this is generally incompatible with the
wavelength calibration and the optical distortion models computed
by vmspcaldisp. For this reason this curvature model is just used
internally in the process of flat field normalisation, where the
compatibility with the Y component of the optical distortion model
is irrelevant.


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

  DO category:               Type:       Explanation:         Required:
  MOS_SCREEN_FLAT            Raw         Flat field exposures    Y
  MASTER_BIAS                Calib       Master bias             Y
  MASTER_DARK                Calib       Master dark             .

  GRISM_TABLE                Calib       Grism table             Y
  CCD_TABLE                  Calib       Bad pixel table         .


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

  DO category:               Data type:  Explanation:
  MOS_MASTER_SCREEN_FLAT     FITS image  Master flat field
  MOS_COMBINED_SCREEN_FLAT   FITS image  Combined flat field
  (none)                     PAF         Distortion models

At least one raw flat field exposure should be present in the input
SOF. The acquisition of input flat fields may be done using different
mask shutter settings (to avoid contamination between different
spectral orders in LR grisms used with multiplexed masks. The vmspflat
recipe will properly combine all the input frames according to a
specified method.


The bad pixel table needs to be specified only if the cleaning of bad
pixels is requested.


The grism table contains necessary information to control the way
spectra are extracted, and the determination of the spectral distortion
models. The vmspflat recipe gets from the grism table the wavelength
that should be used as reference (header entry PRO WLEN CEN), and the
spectrum extension in CCD pixels above and below the position of the
reference wavelength (header entries PRO SPECT LLEN LO and PRO SPECT
LLEN HI).


The PAF file just contains the curvature and the optical distortion
models computed in the process of spectra normalisation. Such models
are available just for debug purposes, and are not to be used in
further data reduction steps.


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

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

   Create an object for the recipe vmspflat.

::

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

Parameters
----------

.. py:attribute:: vmspflat.param.AllowSingleFrames

    Frame combination method is ignored. (bool; default: True) [default=True].
.. py:attribute:: vmspflat.param.BiasMethod

    Bias removal method. (str; default: 'Zmaster') [default="Zmaster"].
.. py:attribute:: vmspflat.param.StackMethod

    Frames combination method. (str; default: 'Average') [default="Average"].
.. py:attribute:: vmspflat.param.KSigmaLow

    Low threshold for K-sigma clipping method. (float; default: 5.0) [default=5.0].
.. py:attribute:: vmspflat.param.KSigmaHigh

    High threshold for K-sigma clipping method. (float; default: 5.0) [default=5.0].
.. py:attribute:: vmspflat.param.MinRejection

    Number of lowest rejected values for rejection method (long; default:  1) [default=1].
.. py:attribute:: vmspflat.param.MaxRejection

    Number of highest rejected values for rejection method (long; default:  1) [default=1].
.. py:attribute:: vmspflat.param.Fuzz

    Extra pixels from expected position of spectrum edge in spectral  extraction. (long; default: 5) [default=5].
.. py:attribute:: vmspflat.param.FlatMethod

    Flat field trends removal method. (str; default: 'Median') [default="Median"].
.. py:attribute:: vmspflat.param.PolyOrderX

    Degree of polynomial used for fitting the flat spectrum along X.  (long; default: 3) [default=3].
.. py:attribute:: vmspflat.param.PolyOrderY

    Degree of polynomial used for fitting the flat spectrum along Y.  (long; default: 8) [default=8].
.. py:attribute:: vmspflat.param.SmoothBoxSize

    Size of running box used for smoothing along the dispersion direction  (currently unused). (long; default: 11) [default=11].
.. py:attribute:: vmspflat.param.CleanBadPixel

    Bad pixel correction on master flat. (bool; default: False) [default=False].
.. py:attribute:: vmspflat.param.CleanCosmic

    Cosmic ray events cleaning from raw flats. (bool; default: False) [default=False].
.. py:attribute:: vmspflat.param.ComputeQC

    Compute QC1 parameters. (bool; default: True) [default=True].


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

::

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

   vmspflat.param.AllowSingleFrames = True
   vmspflat.param.BiasMethod = "Zmaster"
   vmspflat.param.StackMethod = "Average"
   vmspflat.param.KSigmaLow = 5.0
   vmspflat.param.KSigmaHigh = 5.0
   vmspflat.param.MinRejection = 1
   vmspflat.param.MaxRejection = 1
   vmspflat.param.Fuzz = 5
   vmspflat.param.FlatMethod = "Median"
   vmspflat.param.PolyOrderX = 3
   vmspflat.param.PolyOrderY = 8
   vmspflat.param.SmoothBoxSize = 11
   vmspflat.param.CleanBadPixel = False
   vmspflat.param.CleanCosmic = False
   vmspflat.param.ComputeQC = True


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

::

   import cpl
   vmspflat = cpl.Recipe("vmspflat")
   [...]
   res = vmspflat( ..., param = {"AllowSingleFrames":True, "BiasMethod":"Zmaster"})


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

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

Please report any problems to `ESO VIMOS Pipeline Team and VIMOS Consortium <usd-help@eso.org>`_. 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) 2002-2005 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:: ESO VIMOS Pipeline Team and VIMOS Consortium <usd-help@eso.org>
