The vmimobsstare recipe
===============================================================

.. data:: vmimobsstare

Synopsis
--------

Reduce an imaging science exposure.

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

This recipe is used to apply basic reduction steps to one exposure
made in direct imaging mode. SExtractor v2.1.6 is run on the reduced
image, producing a table of detected objects with their instrumental
magnitudes, their celestial and image coordinates, and their stellarity
index. The image WCS, together with the component describing the
instrument optical distortions, is converted into the convention
followed by VMMPS (the VIMOS mask preparation software). This set of
coefficients, the CO-matrix used in the SAO WCSTools package, is
written to the header of the reduced image.


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

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. A CCD
table must be specified in input only if a bad pixel cleaning is
requested. The galaxy table is the output of SExtractor converted
into FITS format. The content of this table is defined within the
VIMOS pipeline DRS, with the only intent of serving the purpose of
the involved pipeline recipes. For a customised output SExtractor
table, it is always possible to run SExtractor separately, after
configuring the native SExtractor parameter files. For a complete
explanation of the output parameters please refer to the SExtractor
documentation - see for instance:

   http://terapix.iap.fr/rubrique.php?id_rubrique=91/index.html).


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


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

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

   Create an object for the recipe vmimobsstare.

::

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

Parameters
----------

.. py:attribute:: vmimobsstare.param.BiasMethod

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

    Bad pixel correction on reduced science image. (bool; default: False) [default=False].
.. py:attribute:: vmimobsstare.param.CleanCosmic

    Cosmic ray removal from input science image. (bool; default: True) [default=True].
.. py:attribute:: vmimobsstare.param.CosmicsThreshold

    Threshold for cosmic ray candidate selection. (float; default: 4.0) [default=4.0].
.. py:attribute:: vmimobsstare.param.CosmicsRatio

    Ratio for discrimination of objects and cosmics. (float; default: 2.0) [default=2.0].
.. py:attribute:: vmimobsstare.param.StarIndex

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

    Aperture used for object identification. (float; default: 2.0) [default=2.0].
.. py:attribute:: vmimobsstare.param.TemperatureCheck

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

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

    Compute QC1 parameters (bool; default: True) [default=True].
.. py:attribute:: vmimobsstare.param.SExtractor.AnalysisThresh

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

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

    Name of the ASSOC file. (str; default: 'sky.list') [default="sky.list"].
.. py:attribute:: vmimobsstare.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:: vmimobsstare.param.SExtractor.AssocRadius

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    If `Y', filter data before extraction. (str; default: 'N') [default="N"].
.. py:attribute:: vmimobsstare.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:: vmimobsstare.param.SExtractor.FilterThresh

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

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

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

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

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

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

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

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

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

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

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

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

    Aperture diameters used for MAG_APER. (float; default: 5.0) [default=5.0].
.. py:attribute:: vmimobsstare.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:: vmimobsstare.param.SExtractor.SExtractor

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

    Pixel values above are considered saturated. (float; default: 60000.0) [default=60000.0].
.. py:attribute:: vmimobsstare.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:: vmimobsstare.param.SExtractor.Timeout

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

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

    Selects the weighting scheme. (str; default: 'NONE') [default="NONE"].
.. py:attribute:: vmimobsstare.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
   vmimobsstare = cpl.Recipe("vmimobsstare")

   vmimobsstare.param.BiasMethod = "Zmaster"
   vmimobsstare.param.CleanBadPixel = False
   vmimobsstare.param.CleanCosmic = True
   vmimobsstare.param.CosmicsThreshold = 4.0
   vmimobsstare.param.CosmicsRatio = 2.0
   vmimobsstare.param.StarIndex = 0.5
   vmimobsstare.param.SearchRadius = 2.0
   vmimobsstare.param.TemperatureCheck = True
   vmimobsstare.param.TemperatureTolerance = 3.0
   vmimobsstare.param.ComputeQC = True
   vmimobsstare.param.SExtractor.AnalysisThresh = 2.5
   vmimobsstare.param.SExtractor.AssocData = "2,3,4"
   vmimobsstare.param.SExtractor.AssocName = "sky.list"
   vmimobsstare.param.SExtractor.AssocParams = "2,3,4"
   vmimobsstare.param.SExtractor.AssocRadius = 2.0
   vmimobsstare.param.SExtractor.AssocSelecType = "MATCHED"
   vmimobsstare.param.SExtractor.AssocType = "MAG_SUM"
   vmimobsstare.param.SExtractor.BackFilterSize = 3
   vmimobsstare.param.SExtractor.BackPhotoThick = 24
   vmimobsstare.param.SExtractor.BackPhotoType = "GLOBAL"
   vmimobsstare.param.SExtractor.BackSize = 64
   vmimobsstare.param.SExtractor.BackValue = 0.0
   vmimobsstare.param.SExtractor.CatalogType = "ASCII_HEAD"
   vmimobsstare.param.SExtractor.CheckImageName = "check.fits"
   vmimobsstare.param.SExtractor.CheckImageType = "NONE"
   vmimobsstare.param.SExtractor.Clean = "Y"
   vmimobsstare.param.SExtractor.CleanParam = 1.0
   vmimobsstare.param.SExtractor.DeblendMinCont = 0.005
   vmimobsstare.param.SExtractor.DeblendNthresh = 32
   vmimobsstare.param.SExtractor.DetectMinArea = 5
   vmimobsstare.param.SExtractor.DetectThresh = 2.0
   vmimobsstare.param.SExtractor.DetectType = "CCD"
   vmimobsstare.param.SExtractor.Filter = "N"
   vmimobsstare.param.SExtractor.FilterName = "/usr/share/esopipes/vimos-3.0.6/config/vimos.conv"
   vmimobsstare.param.SExtractor.FilterThresh = ""
   vmimobsstare.param.SExtractor.FlagImage = "flag.fits"
   vmimobsstare.param.SExtractor.FlagType = "OR"
   vmimobsstare.param.SExtractor.InterpMaxXlag = 16
   vmimobsstare.param.SExtractor.InterpMaxYlag = 16
   vmimobsstare.param.SExtractor.InterpType = "ALL"
   vmimobsstare.param.SExtractor.MagGamma = 4.0
   vmimobsstare.param.SExtractor.MagZeropoint = 0.0
   vmimobsstare.param.SExtractor.MaskType = "CORRECT"
   vmimobsstare.param.SExtractor.MemoryBufSize = 1024
   vmimobsstare.param.SExtractor.MemoryObjStack = 2000
   vmimobsstare.param.SExtractor.MemoryPixStack = 100000
   vmimobsstare.param.SExtractor.PhotApertures = 5.0
   vmimobsstare.param.SExtractor.PhotAutoParams = "2.5,3.5"
   vmimobsstare.param.SExtractor.SExtractor = "/usr/bin/sex"
   vmimobsstare.param.SExtractor.SaturLevel = 60000.0
   vmimobsstare.param.SExtractor.StarNnwName = "/usr/share/esopipes/vimos-3.0.6/config/vimos.nnw"
   vmimobsstare.param.SExtractor.Timeout = 300.0
   vmimobsstare.param.SExtractor.VerboseType = "QUIET"
   vmimobsstare.param.SExtractor.WeightType = "NONE"
   vmimobsstare.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
   vmimobsstare = cpl.Recipe("vmimobsstare")
   [...]
   res = vmimobsstare( ..., 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 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>
