The vmmosobsstare recipe
===============================================================

.. data:: vmmosobsstare

Synopsis
--------

Reduce a MOS science exposure.

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

This recipe is used to apply basic reduction steps to one exposure
made in MOS mode, to locate objects, and to optimally extract their
spectra.


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

  DO category:             Type:       Explanation:         Required:
  MOS_SCIENCE              Raw         Science exposure        Y
  MASTER_BIAS              Calib       Master bias             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
  EXTINCT_TABLE            Calib       Atmospheric extinction  .

  MOS_SPECPHOT_TABLE       Calib       Response curve          .

  CCD_TABLE                Calib       Bad pixel table         .


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

  DO category:             Data type:  Explanation:
  MOS_SCIENCE_REDUCED      FITS image  Extracted objects spectra
  MOS_SCIENCE_FLUX_REDUCED FITS image  Flux calibrated objects spectra
  MOS_SCIENCE_EXTRACTED    FITS image  Sky subtracted slit spectra
  MOS_SCIENCE_SKY          FITS image  Sky spectra
  MOS_SKY_REDUCED          FITS image  Extracted sky spectra
  OBJECT_TABLE             FITS table  Objects spectra identification
  WINDOW_TABLE             FITS table  Objects positions in slit

A flat field correction is applied only if a normalised master flat
field (produced by the recipe vmspflat) is specified.


The extraction table is the product of the local spectral distortions
modelling performed by the recipe vmspcaldisp. If an extraction table
is not specified, then the global distortion models read from the
science frame header are used.


The grism table contains necessary information to control the way
spectra are extracted, starting from the reference wavelength (header
entry PRO WLEN CEN), on a specific range of pixels above and below
its position on the CCD (header entries PRO SPECT LLEN LO and PRO
SPECT LLEN HI). Other parameters, used in the extraction of the
science slit spectra, are the start and the end wavelength of the
image of the extracted slit spectra (header entries PRO WLEN START
and PRO WLEN END), and the step of the sampling along the dispersion
direction (header entry PRO WLEN INC). Finally, the wavelengths of the
sky lines used in the alignment of the spectral distortion models,
necessary to keep into account the possible coordinates shifts
introduced by a variation of the instrument flexures between the
science and the calibration exposures, are listed in the header
keywords PRO SKY WLENi, with i ranging from 1 to the number specified
in the keyword PRO SKY NO.


A CCD table must be specified in input only if a bad pixel cleaning is
requested.


The slit spectra are remapped with the instrument distortions removed
and at a fixed wavelength step. A sky value is estimated for each
wavelength and then subtracted from the data. The result is stored
in the MOS_SCIENCE_EXTRACTED image, while the image MOS_SCIENCE_SKY
contains the subtracted sky model. The 1D extracted spectra are stored
in the MOS_SCIENCE_REDUCED image, while the corresponding sky spectra
extracted with the same method are stored in the MOS_SKY_REDUCED image.

The positions of the extracted slit spectra and of the detected objects
that they may contain are listed in the window table.


If a spectro-photometric table (produced by the recipe vmmosstandard)
is specified together with an atmospheric extinction table, and a flux
calibration is requested, then a MOS_SCIENCE_FLUX_REDUCED image is also
created. This image is identical to the MOS_SCIENCE_REDUCED, but the
spectra it contains are flux calibrated, and expressed in units of
erg/cm/cm/s/Angstrom.


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


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

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

   Create an object for the recipe vmmosobsstare.

::

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

Parameters
----------

.. py:attribute:: vmmosobsstare.param.BiasMethod

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

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

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

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

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

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

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

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

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

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

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

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

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

    Bad pixel correction on MOS science exposure. (bool; default: False) [default=False].
.. py:attribute:: vmmosobsstare.param.CalibrateFlux

    Extracted spectra are flux calibrated. (bool; default: False) [default=False].
.. py:attribute:: vmmosobsstare.param.HorneExtraction

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

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

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

    Use sky lines to refine the wavelength calibration (bool; default:  True) [default=True].


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

::

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

   vmmosobsstare.param.BiasMethod = "Zmaster"
   vmmosobsstare.param.SkyMethod = "Median"
   vmmosobsstare.param.PolyOrder = 0
   vmmosobsstare.param.SkyKSigmaLow = 1.0
   vmmosobsstare.param.SkyKSigmaHigh = 1.0
   vmmosobsstare.param.Fuzz = 5
   vmmosobsstare.param.SlitMargin = 2
   vmmosobsstare.param.LineWidth = 16
   vmmosobsstare.param.DetectionLevel = 2.0
   vmmosobsstare.param.WatershedLevels = 32
   vmmosobsstare.param.WatershedFraction = 0.01
   vmmosobsstare.param.MinObjectSize = 2
   vmmosobsstare.param.MaxObjectSize = 7
   vmmosobsstare.param.CleanBadPixel = False
   vmmosobsstare.param.CalibrateFlux = False
   vmmosobsstare.param.HorneExtraction = False
   vmmosobsstare.param.ModelSlit = True
   vmmosobsstare.param.ModelSlitOrder = 0
   vmmosobsstare.param.UseSkylines = True


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

::

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


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