cpl-plugin-vimos-doc 3.0.6+dfsg-4 / usr / share / doc / cpl-plugin-vimos-doc / html / _sources / vmmosobsjitter.txt

The vmmosobsjitter recipe
===============================================================

.. data:: vmmosobsjitter

Synopsis
--------

Reduce and combine a set of jittered MOS observations.

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

This recipe is used to apply basic reduction steps to a sequence of
exposures made in MOS mode, to combine them in a single image, to
locate objects, and to optimally extract their spectra. Each input
image is processed in the same way as by recipe vmmosobsstare,
therefore what mainly characterises the vmmosobsjitter recipe is
the task of combining the input frames.


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
  MOS_FRINGES_SKY          Calib       Sky+fringes map ('Raw')   .

  MOS_FRINGES              Calib       Fringe map ('Resampled')  .

  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 slit spectra
  MOS_SKY_REDUCED          FITS image  Extracted sky spectra
  MOS_FRINGES_SKY          FITS image  Sky+fringes map (method 'Raw')
  MOS_FRINGES              FITS image  Fringe map (method 'Resampled')
  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.


Sky fringes may be subtracted from the data using two different
methods. The 'Raw' method will subtract the median sky+fringes
pattern from each input image, and then fit away the residuals
possibly introduced by sky variations between exposures. The
'Resampled' method will fit the sky first, and then subtract the
median image of the residuals (stored in the product MOS_FRINGES).

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


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

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

   Create an object for the recipe vmmosobsjitter.

::

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

Parameters
----------

.. py:attribute:: vmmosobsjitter.param.BiasMethod

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Apply fringing corrections. (bool; default: False) [default=False].
.. py:attribute:: vmmosobsjitter.param.FringingMethod

    Sky fringes removal method. (str; default: 'Raw') [default="Raw"].
.. py:attribute:: vmmosobsjitter.param.FringingOffset

    Minimum required offset between exposures for applying the sky  fringing correction. (float; default: 3.0) [default=3.0].
.. py:attribute:: vmmosobsjitter.param.HorneExtraction

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

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

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

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

    Save intermediate reduction steps (bool; default: False) [default=False].


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

::

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

   vmmosobsjitter.param.BiasMethod = "Zmaster"
   vmmosobsjitter.param.StackMethod = "Average"
   vmmosobsjitter.param.KSigmaLow = 5.0
   vmmosobsjitter.param.KSigmaHigh = 5.0
   vmmosobsjitter.param.MinRejection = 1
   vmmosobsjitter.param.MaxRejection = 1
   vmmosobsjitter.param.SkyMethod = "Median"
   vmmosobsjitter.param.PolyOrder = 2
   vmmosobsjitter.param.SkyKSigmaLow = 1.0
   vmmosobsjitter.param.SkyKSigmaHigh = 1.0
   vmmosobsjitter.param.Fuzz = 5
   vmmosobsjitter.param.SlitMargin = 2
   vmmosobsjitter.param.LineWidth = 16
   vmmosobsjitter.param.DetectionLevel = 2.0
   vmmosobsjitter.param.WatershedLevels = 32
   vmmosobsjitter.param.WatershedFraction = 0.01
   vmmosobsjitter.param.MinObjectSize = 2
   vmmosobsjitter.param.MaxObjectSize = 7
   vmmosobsjitter.param.CleanBadPixel = False
   vmmosobsjitter.param.CalibrateFlux = False
   vmmosobsjitter.param.FringingCorr = False
   vmmosobsjitter.param.FringingMethod = "Raw"
   vmmosobsjitter.param.FringingOffset = 3.0
   vmmosobsjitter.param.HorneExtraction = False
   vmmosobsjitter.param.ModelSlit = True
   vmmosobsjitter.param.ModelSlitOrder = 0
   vmmosobsjitter.param.UseSkylines = True
   vmmosobsjitter.param.SaveIntermediate = False


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

::

   import cpl
   vmmosobsjitter = cpl.Recipe("vmmosobsjitter")
   [...]
   res = vmmosobsjitter( ..., param = {"BiasMethod":"Zmaster", "StackMethod":"Average"})


.. 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 currently part of the VIMOS 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:: ESO VIMOS Pipeline Team and VIMOS Consortium <usd-help@eso.org>