The vmmosstandard recipe
===============================================================

.. data:: vmmosstandard

Synopsis
--------

Reduce a MOS standard star exposure.

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

This recipe is used to calibrate and extract a standard star spectrum
obtained in MOS mode, and compare it with a catalog spectrum to obtain
the efficiency and the response curves.


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

  DO category:               Type:      Explanation:         Required:
  MOS_STANDARD               Raw        Science exposure        Y
  MASTER_BIAS                Calib      Master bias             Y
  EXTINCT_TABLE              Calib      Atmospheric extinction  Y
  STD_FLUX_TABLE             Calib      Standard star fluxes    Y
  MASTER_DARK                Calib      Master dark             .

  MOS_MASTER_SCREEN_FLAT     Calib      Normalised flat field   .

  EXTRACT_TABLE              Calib      Extraction table        .

  GRISM_TABLE                Calib      Grism table             Y
  CCD_TABLE                  Calib      Bad pixel table         .


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

  DO category:               Data type: Explanation:
  MOS_STANDARD_REDUCED       FITS image Extracted spectrum
  MOS_STANDARD_EXTRACTED     FITS image Sky subtracted slit spectra
  MOS_STANDARD_SKY           FITS image Sky slit spectra
  MOS_STANDARD_SKY_EXTRACTED FITS image Extracted sky spectrum
  OBJECT_TABLE               FITS table Objects spectra identification
  WINDOW_TABLE               FITS table Objects positions in slit
  MOS_SPECPHOT_TABLE         FITS table Efficiency and response curves

The standard star spectrum is calibrated and extracted as described
for the recipe vmmosobsstare. The extracted spectrum is compared to
catalog fluxes of the same star to obtain the efficiency curve and
the response curve to use for flux calibration. For this comparison
the extracted spectrum is converted into electrons/sec/Angstrom. The
catalog fluxes, as well as the atmospheric extinction factors, are
remapped to the same wavelength bins of the extracted spectrum. After
removing the effect of the atmospheric extinction (i.e., correcting
the extracted spectrum to airmass zero), the response curve is derived
as the ratio between the catalog spectrum and the calibrated spectrum.

The efficiency curve is obtained by dividing the extracted spectrum
in electrons/sec/Angstrom by the the catalog fluxes converted from
erg/cm/cm/s/Angstrom to photons/s/Angstrom (at 100% efficiency each
photon would correspond to one electron).


For more details, please refer to the VIMOS Pipeline User's Guide.


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

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

   Create an object for the recipe vmmosstandard.

::

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

Parameters
----------

.. py:attribute:: vmmosstandard.param.BiasMethod

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

    Sky level determination method. (str; default: 'Median') [default="Median"].
.. py:attribute:: vmmosstandard.param.PolyOrder

    Degree of polynomial used when the SkyMethod is set to Fit. (long;  default: 0) [default=0].
.. py:attribute:: vmmosstandard.param.SkyKSigmaLow

    Low threshold for K-sigma rejection in sky fitting. (float; default:  3.0) [default=3.0].
.. py:attribute:: vmmosstandard.param.SkyKSigmaHigh

    High threshold for K-sigma rejection in sky fitting. (float; default:  3.0) [default=3.0].
.. py:attribute:: vmmosstandard.param.Fuzz

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

    Number of excluded pixels at slit ends in object search or in sky  level determination. (long; default: 2) [default=2].
.. py:attribute:: vmmosstandard.param.LineWidth

    Size of spectrum to extract around any skyline. (long; default: 16) [default=16].
.. py:attribute:: vmmosstandard.param.DetectionLevel

    Object detection level in units of sigma. (float; default: 10.0) [default=10.0].
.. py:attribute:: vmmosstandard.param.WatershedLevels

    Number of levels in the watershed method in object detection. (long;  default: 32) [default=32].
.. py:attribute:: vmmosstandard.param.WatershedFraction

    Flux fraction to use in watershed. (float; default: 0.01) [default=0.01].
.. py:attribute:: vmmosstandard.param.MinObjectSize

    Minimal size for an object candidate to be considered an object.  (long; default: 2) [default=2].
.. py:attribute:: vmmosstandard.param.MaxObjectSize

    Maximal size for an object candidate for not trying deblend into sub-  objects. (long; default: 7) [default=7].
.. py:attribute:: vmmosstandard.param.CleanBadPixel

    Bad pixel correction on MOS science exposure. (bool; default: True) [default=True].
.. py:attribute:: vmmosstandard.param.HorneExtraction

    Use 1D Horne extraction. (bool; default: False) [default=False].
.. py:attribute:: vmmosstandard.param.ModelSlit

    Model wavelength solution within each slit. (bool; default: True) [default=True].
.. py:attribute:: vmmosstandard.param.ModelSlitOrder

    Order of polynomial for wavelength solution modeling within each slit.  (long; default: 0) [default=0].
.. py:attribute:: vmmosstandard.param.UseSkylines

    Use sky lines to refine the wavelength calibration (bool; default:  True) [default=True].
.. py:attribute:: vmmosstandard.param.ResponseOrder

    Order of the polynomial used to smooth the instrument response curve.  (long; default: 5) [default=5].
.. py:attribute:: vmmosstandard.param.ReduceAnyFrame

    Reduce any frame. (bool; default: False) [default=False].
.. py:attribute:: vmmosstandard.param.ComputeQC

    Compute QC1 parameters (bool; default: True) [default=True].
.. py:attribute:: vmmosstandard.param.SelectSlit

    Slit containing the standard star. (long; default: 0) [default=0].


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

::

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

   vmmosstandard.param.BiasMethod = "Zmaster"
   vmmosstandard.param.SkyMethod = "Median"
   vmmosstandard.param.PolyOrder = 0
   vmmosstandard.param.SkyKSigmaLow = 3.0
   vmmosstandard.param.SkyKSigmaHigh = 3.0
   vmmosstandard.param.Fuzz = 5
   vmmosstandard.param.SlitMargin = 2
   vmmosstandard.param.LineWidth = 16
   vmmosstandard.param.DetectionLevel = 10.0
   vmmosstandard.param.WatershedLevels = 32
   vmmosstandard.param.WatershedFraction = 0.01
   vmmosstandard.param.MinObjectSize = 2
   vmmosstandard.param.MaxObjectSize = 7
   vmmosstandard.param.CleanBadPixel = True
   vmmosstandard.param.HorneExtraction = False
   vmmosstandard.param.ModelSlit = True
   vmmosstandard.param.ModelSlitOrder = 0
   vmmosstandard.param.UseSkylines = True
   vmmosstandard.param.ResponseOrder = 5
   vmmosstandard.param.ReduceAnyFrame = False
   vmmosstandard.param.ComputeQC = True
   vmmosstandard.param.SelectSlit = 0


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

::

   import cpl
   vmmosstandard = cpl.Recipe("vmmosstandard")
   [...]
   res = vmmosstandard( ..., param = {"BiasMethod":"Zmaster", "SkyMethod":"Median"})


.. 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 <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 <usd-help@eso.org>
