The vmimobsjitter recipe
===============================================================

.. data:: vmimobsjitter

Synopsis
--------

Reduce and combine a set of jittered imaging exposures.

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

This recipe is used to apply basic reduction steps to a sequence of
exposures made in direct imaging mode, and to combine them in a single
image. Each input image is processed in the same way as by recipe
vmimobsstare, therefore what characterises the vmimobsjitter is just
the final combination of the input frames.


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

  DO category:              Type:       Explanation:         Required:
  IMG_SCIENCE               Raw         Science exposure        Y
  MASTER_BIAS               Calib       Master bias             Y
  MASTER_DARK               Calib       Master dark             .

  IMG_MASTER_SKY_FLAT       Calib       Master sky flat         Y
  PHOT_COEFF_TABLE          Calib       Photometric table       .

  CCD_TABLE                 Calib       Bad pixel table         .


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

  DO category:              Data type:  Explanation:
  IMG_SCIENCE_REDUCED       FITS image  Reduced scientific exposure
  IMG_GALAXY_TABLE          FITS table  List of detected objects
  IMG_FRINGES               FITS image  Fringes map 

If a photometric table is specified, the magnitude zeropoint, the
atmospheric extinction coefficient, and the colour term are copied
from the photometric table to the header of the reduced image. The
galaxy table is the output of SExtractor converted into FITS format.

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


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


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

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

   Create an object for the recipe vmimobsjitter.

::

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

Parameters
----------

.. py:attribute:: vmimobsjitter.param.BiasMethod

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

    Bad pixel correction on reduced science images before combination.  (bool; default: False) [default=False].
.. py:attribute:: vmimobsjitter.param.ComputeQC

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

    Pixel value interpolation method. (str; default: 'BiLinear') [default="BiLinear"].
.. py:attribute:: vmimobsjitter.param.FringingCorr

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

    Frame combination method (str; default: 'Median') [default="Median"].
.. py:attribute:: vmimobsjitter.param.KSigmaLow

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

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

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

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

    Check beam temperature when updating the world coordinate system.  (bool; default: True) [default=True].
.. py:attribute:: vmimobsjitter.param.TemperatureTolerance

    Maximum allowed difference between beam and ambient temperature.  (float; default: 3.0) [default=3.0].
.. py:attribute:: vmimobsjitter.param.StarIndex

    Stellarity index used to select stars in the image. (float; default:  0.5) [default=0.5].
.. py:attribute:: vmimobsjitter.param.SExtractor.AnalysisThresh

    Surface brightness threshold for FWHM computation. (float; default:  2.5) [default=2.5].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocData

    Column indices for columns to copy to the catalog output. (str;  default: '2,3,4') [default="2,3,4"].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocName

    Name of the ASSOC file. (str; default: 'sky.list') [default="sky.list"].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocParams

    Column indices in the ASSOC file to use as coordinates and weight for  cross-matching. (str; default: '2,3,4') [default="2,3,4"].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocRadius

    Search radius for ASSOC. (float; default: 2.0) [default=2.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocSelecType

    Output selector for detected sources. (str; default: 'MATCHED') [default="MATCHED"].
.. py:attribute:: vmimobsjitter.param.SExtractor.AssocType

    Method for cross-matching. (str; default: 'MAG_SUM') [default="MAG_SUM"].
.. py:attribute:: vmimobsjitter.param.SExtractor.BackFilterSize

    Size (in background meshes) of the background filtering mask. (long;  default: 3) [default=3].
.. py:attribute:: vmimobsjitter.param.SExtractor.BackPhotoThick

    Thickness of the background LOCAL annulus. (long; default: 24) [default=24].
.. py:attribute:: vmimobsjitter.param.SExtractor.BackPhotoType

    Select background for magnitude computation. (str; default: 'GLOBAL') [default="GLOBAL"].
.. py:attribute:: vmimobsjitter.param.SExtractor.BackSize

    Size of a background mesh. (long; default: 64) [default=64].
.. py:attribute:: vmimobsjitter.param.SExtractor.BackValue

    Constant to subtract from the images for MANUAL background  subtraction. (float; default: 0.0) [default=0.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.CatalogType

    Select output catalog format (only ASCII_HEAD is supported). (str;  default: 'ASCII_HEAD') [default="ASCII_HEAD"].
.. py:attribute:: vmimobsjitter.param.SExtractor.CheckImageName

    Check image file name. (str; default: 'check.fits') [default="check.fits"].
.. py:attribute:: vmimobsjitter.param.SExtractor.CheckImageType

    Select information to put in the `check image'. (str; default: 'NONE') [default="NONE"].
.. py:attribute:: vmimobsjitter.param.SExtractor.Clean

    If `Y', clean catalog before writing. (str; default: 'Y') [default="Y"].
.. py:attribute:: vmimobsjitter.param.SExtractor.CleanParam

    Cleaning efficiency. (float; default: 1.0) [default=1.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.DeblendMinCont

    Minimum contrast for deblending. (float; default: 0.005) [default=0.005].
.. py:attribute:: vmimobsjitter.param.SExtractor.DeblendNthresh

    Number of deblending sub-thresholds. (long; default: 32) [default=32].
.. py:attribute:: vmimobsjitter.param.SExtractor.DetectMinArea

    Minimum number of pixels above threshold triggering detection. (long;  default: 5) [default=5].
.. py:attribute:: vmimobsjitter.param.SExtractor.DetectThresh

    Detection threshold (relative to background RMS). (float; default:  2.0) [default=2.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.DetectType

    Device type the image originates from. (str; default: 'CCD') [default="CCD"].
.. py:attribute:: vmimobsjitter.param.SExtractor.Filter

    If `Y', filter data before extraction. (str; default: 'N') [default="N"].
.. py:attribute:: vmimobsjitter.param.SExtractor.FilterName

    Name of the file containing the filter definition. (str; default:  '/usr/share/esopipes/vimos-3.0.6/config/vimos.conv') [default="/usr/share/esopipes/vimos-3.0.6/config/vimos.conv"].
.. py:attribute:: vmimobsjitter.param.SExtractor.FilterThresh

    Lower, upper threshold (in background sigmas) for filtering (retina-  filtering only). (str; default: '') [default=""].
.. py:attribute:: vmimobsjitter.param.SExtractor.FlagImage

    Flag image file name. (str; default: 'flag.fits') [default="flag.fits"].
.. py:attribute:: vmimobsjitter.param.SExtractor.FlagType

    Flag combination method. (str; default: 'OR') [default="OR"].
.. py:attribute:: vmimobsjitter.param.SExtractor.InterpMaxXlag

    Maximum X gap allowed in interpolation. (long; default: 16) [default=16].
.. py:attribute:: vmimobsjitter.param.SExtractor.InterpMaxYlag

    Maximum Y gap allowed in interpolation. (long; default: 16) [default=16].
.. py:attribute:: vmimobsjitter.param.SExtractor.InterpType

    Interpolation method. (str; default: 'ALL') [default="ALL"].
.. py:attribute:: vmimobsjitter.param.SExtractor.MagGamma

    Gamma of emulsion (only used in PHOTO mode). (float; default: 4.0) [default=4.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.MagZeropoint

    Zero-point offset to apply to magnitudes. (float; default: 0.0) [default=0.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.MaskType

    Masking of neighbours for photometry. (str; default: 'CORRECT') [default="CORRECT"].
.. py:attribute:: vmimobsjitter.param.SExtractor.MemoryBufSize

    Number of scan-lines in the image buffer. (long; default: 1024) [default=1024].
.. py:attribute:: vmimobsjitter.param.SExtractor.MemoryObjStack

    Maximum number of objects the object stack can contain. (long;  default: 2000) [default=2000].
.. py:attribute:: vmimobsjitter.param.SExtractor.MemoryPixStack

    Maximum number of pixels the pixel stack can contain. (long; default:  100000) [default=100000].
.. py:attribute:: vmimobsjitter.param.SExtractor.PhotApertures

    Aperture diameters used for MAG_APER. (float; default: 5.0) [default=5.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.PhotAutoParams

    MAG_AUTO controls: 1st order moment scaling parameter, minimum Rmin.  (str; default: '2.5,3.5') [default="2.5,3.5"].
.. py:attribute:: vmimobsjitter.param.SExtractor.SExtractor

    Path to the sextractor executable. (str; default: '/usr/bin/sex') [default="/usr/bin/sex"].
.. py:attribute:: vmimobsjitter.param.SExtractor.SaturLevel

    Pixel values above are considered saturated. (float; default: 60000.0) [default=60000.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.StarNnwName

    Name of the neuronal network weights file. (str; default:  '/usr/share/esopipes/vimos-3.0.6/config/vimos.nnw') [default="/usr/share/esopipes/vimos-3.0.6/config/vimos.nnw"].
.. py:attribute:: vmimobsjitter.param.SExtractor.Timeout

    Time after which sextractor will be aborted. (float; default: 300.0) [default=300.0].
.. py:attribute:: vmimobsjitter.param.SExtractor.VerboseType

    Selects verbosity level. (str; default: 'QUIET') [default="QUIET"].
.. py:attribute:: vmimobsjitter.param.SExtractor.WeightType

    Selects the weighting scheme. (str; default: 'NONE') [default="NONE"].
.. py:attribute:: vmimobsjitter.param.SExtractor.Window

    Frame window used in SExtractor detection. (str; default:  '100,100,1948,2340') [default="100,100,1948,2340"].


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

::

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

   vmimobsjitter.param.BiasMethod = "Zmaster"
   vmimobsjitter.param.CleanBadPixel = False
   vmimobsjitter.param.ComputeQC = True
   vmimobsjitter.param.Resampling = "BiLinear"
   vmimobsjitter.param.FringingCorr = False
   vmimobsjitter.param.StackMethod = "Median"
   vmimobsjitter.param.KSigmaLow = 5.0
   vmimobsjitter.param.KSigmaHigh = 5.0
   vmimobsjitter.param.MinRejection = 1
   vmimobsjitter.param.MaxRejection = 1
   vmimobsjitter.param.TemperatureCheck = True
   vmimobsjitter.param.TemperatureTolerance = 3.0
   vmimobsjitter.param.StarIndex = 0.5
   vmimobsjitter.param.SExtractor.AnalysisThresh = 2.5
   vmimobsjitter.param.SExtractor.AssocData = "2,3,4"
   vmimobsjitter.param.SExtractor.AssocName = "sky.list"
   vmimobsjitter.param.SExtractor.AssocParams = "2,3,4"
   vmimobsjitter.param.SExtractor.AssocRadius = 2.0
   vmimobsjitter.param.SExtractor.AssocSelecType = "MATCHED"
   vmimobsjitter.param.SExtractor.AssocType = "MAG_SUM"
   vmimobsjitter.param.SExtractor.BackFilterSize = 3
   vmimobsjitter.param.SExtractor.BackPhotoThick = 24
   vmimobsjitter.param.SExtractor.BackPhotoType = "GLOBAL"
   vmimobsjitter.param.SExtractor.BackSize = 64
   vmimobsjitter.param.SExtractor.BackValue = 0.0
   vmimobsjitter.param.SExtractor.CatalogType = "ASCII_HEAD"
   vmimobsjitter.param.SExtractor.CheckImageName = "check.fits"
   vmimobsjitter.param.SExtractor.CheckImageType = "NONE"
   vmimobsjitter.param.SExtractor.Clean = "Y"
   vmimobsjitter.param.SExtractor.CleanParam = 1.0
   vmimobsjitter.param.SExtractor.DeblendMinCont = 0.005
   vmimobsjitter.param.SExtractor.DeblendNthresh = 32
   vmimobsjitter.param.SExtractor.DetectMinArea = 5
   vmimobsjitter.param.SExtractor.DetectThresh = 2.0
   vmimobsjitter.param.SExtractor.DetectType = "CCD"
   vmimobsjitter.param.SExtractor.Filter = "N"
   vmimobsjitter.param.SExtractor.FilterName = "/usr/share/esopipes/vimos-3.0.6/config/vimos.conv"
   vmimobsjitter.param.SExtractor.FilterThresh = ""
   vmimobsjitter.param.SExtractor.FlagImage = "flag.fits"
   vmimobsjitter.param.SExtractor.FlagType = "OR"
   vmimobsjitter.param.SExtractor.InterpMaxXlag = 16
   vmimobsjitter.param.SExtractor.InterpMaxYlag = 16
   vmimobsjitter.param.SExtractor.InterpType = "ALL"
   vmimobsjitter.param.SExtractor.MagGamma = 4.0
   vmimobsjitter.param.SExtractor.MagZeropoint = 0.0
   vmimobsjitter.param.SExtractor.MaskType = "CORRECT"
   vmimobsjitter.param.SExtractor.MemoryBufSize = 1024
   vmimobsjitter.param.SExtractor.MemoryObjStack = 2000
   vmimobsjitter.param.SExtractor.MemoryPixStack = 100000
   vmimobsjitter.param.SExtractor.PhotApertures = 5.0
   vmimobsjitter.param.SExtractor.PhotAutoParams = "2.5,3.5"
   vmimobsjitter.param.SExtractor.SExtractor = "/usr/bin/sex"
   vmimobsjitter.param.SExtractor.SaturLevel = 60000.0
   vmimobsjitter.param.SExtractor.StarNnwName = "/usr/share/esopipes/vimos-3.0.6/config/vimos.nnw"
   vmimobsjitter.param.SExtractor.Timeout = 300.0
   vmimobsjitter.param.SExtractor.VerboseType = "QUIET"
   vmimobsjitter.param.SExtractor.WeightType = "NONE"
   vmimobsjitter.param.SExtractor.Window = "100,100,1948,2340"


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

::

   import cpl
   vmimobsjitter = cpl.Recipe("vmimobsjitter")
   [...]
   res = vmimobsjitter( ..., param = {"BiasMethod":"Zmaster", "CleanBadPixel":False})


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