The fors_pmos_calib recipe
===============================================================

.. data:: fors_pmos_calib

Synopsis
--------

Determination of the extraction mask

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

This recipe is used to identify reference lines on PMOS arc lamp
exposures, and trace the spectral edges on the corresponding flat field
exposures. This information is used to determine the spectral extraction
mask to be applied in the scientific data reduction, performed with the
recipe fors_science.

This recipe accepts both FORS1 and FORS2 frames. The input arc lamps and
flat field exposures are assumed to be obtained quasi-simultaneously, so
that they would be described by exactly the same instrument distortions.

A line catalog must be specified, containing the wavelengths of the
reference arc lamp lines used for the wavelength calibration. A grism
table (typically depending on the instrument mode, and in particular on
the grism used) may also be specified: this table contains a default
recipe parameter setting to control the way spectra are extracted for
a specific instrument mode, as it is used for automatic run of the
pipeline on Paranal and in Garching. If this table is specified, it
will modify the default recipe parameter setting, with the exception of
those parameters which have been explicitly modifyed on the command line.

If a grism table is not specified, the input recipe parameters values
will always be read from the command line, or from an esorex configuration
file if present, or from their generic default values (that are rarely
meaningful). Finally a master bias frame must be input to this recipe.

The products SPECTRA_DETECTION_PMOS, SLIT_MAP_PMOS, and DISP_RESIDUALS_PMOS,
are just created if the --check parameter is set to true.

The MASTER_DISTORTION_TABLE is marked as required, but it is not so if all
slits have different offsets, and in the case of FORS1 observations made
with the old TK2048EB4-1 1604 chip read in windowed mode (2048x400)

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

  DO category:              Type:       Explanation:          Required:
  SCREEN_FLAT_PMOS          Raw         Flat field exposures     Y
  LAMP_PMOS                 Raw         Arc lamp exposure        Y
  MASTER_BIAS or BIAS       Calib       Bias frame               Y
  MASTER_LINECAT            Calib       Line catalog             Y
  GRISM_TABLE               Calib       Grism table              .

  MASTER_DISTORTION_TABLE   Calib       Master distortions table Y

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

  DO category:              Data type:  Explanation:
  MASTER_SCREEN_FLAT_PMOS   FITS image  Combined (sum) flat field
  MASTER_NORM_FLAT_PMOS     FITS image  Normalised flat field
  MAPPED_SCREEN_FLAT_PMOS   FITS image  Wavelength calibrated flat field
  MAPPED_NORM_FLAT_PMOS     FITS image  Wavelength calibrated normalised flat
  REDUCED_LAMP_PMOS         FITS image  Wavelength calibrated arc spectrum
  DISP_COEFF_PMOS           FITS table  Inverse dispersion coefficients
  DISP_RESIDUALS_PMOS       FITS image  Residuals in wavelength calibration
  DISP_RESIDUALS_TABLE_PMOS FITS table  Residuals in wavelength calibration
  DELTA_IMAGE_PMOS          FITS image  Offset vs linear wavelength calib
  WAVELENGTH_MAP_PMOS       FITS image  Wavelength for each pixel on CCD
  SPECTRA_DETECTION_PMOS    FITS image  Check for preliminary detection
  SLIT_MAP_PMOS             FITS image  Map of central wavelength on CCD
  CURV_TRACES_PMOS          FITS table  Spectral curvature traces
  CURV_COEFF_PMOS           FITS table  Spectral curvature coefficients
  SPATIAL_MAP_PMOS          FITS image  Spatial position along slit on CCD
  SPECTRAL_RESOLUTION_PMOS  FITS table  Resolution at reference arc lines
  SLIT_LOCATION_PMOS        FITS table  Slits on product frames and CCD


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

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

   Create an object for the recipe fors_pmos_calib.

::

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

Parameters
----------

.. py:attribute:: fors_pmos_calib.param.dispersion

    Expected spectral dispersion (Angstrom/pixel) (float; default: 0.0) [default=0.0].
.. py:attribute:: fors_pmos_calib.param.peakdetection

    Initial peak detection threshold (ADU) (float; default: 0.0) [default=0.0].
.. py:attribute:: fors_pmos_calib.param.wdegree

    Degree of wavelength calibration polynomial (int; default: 0) [default=0].
.. py:attribute:: fors_pmos_calib.param.wradius

    Search radius if iterating pattern-matching with first-guess method  (int; default: 4) [default=4].
.. py:attribute:: fors_pmos_calib.param.wreject

    Rejection threshold in dispersion relation fit (pixel) (float;  default: 0.7) [default=0.7].
.. py:attribute:: fors_pmos_calib.param.wcolumn

    Name of line catalog table column with wavelengths (str; default:  'WLEN') [default="WLEN"].
.. py:attribute:: fors_pmos_calib.param.cdegree

    Degree of spectral curvature polynomial (int; default: 0) [default=0].
.. py:attribute:: fors_pmos_calib.param.cmode

    Interpolation mode of curvature solution (0 = no interpolation, 1 =  fill gaps, 2 = global model) (int; default: 1) [default=1].
.. py:attribute:: fors_pmos_calib.param.startwavelength

    Start wavelength in spectral extraction (float; default: 0.0) [default=0.0].
.. py:attribute:: fors_pmos_calib.param.endwavelength

    End wavelength in spectral extraction (float; default: 0.0) [default=0.0].
.. py:attribute:: fors_pmos_calib.param.stack_method

    Frames combination method (str; default: 'average') [default="average"].
.. py:attribute:: fors_pmos_calib.param.minrejection

    Number of lowest values to be rejected (int; default: 1) [default=1].
.. py:attribute:: fors_pmos_calib.param.maxrejection

    Number of highest values to be rejected (int; default: 1) [default=1].
.. py:attribute:: fors_pmos_calib.param.klow

    Low threshold in ksigma method (float; default: 3.0) [default=3.0].
.. py:attribute:: fors_pmos_calib.param.khigh

    High threshold in ksigma method (float; default: 3.0) [default=3.0].
.. py:attribute:: fors_pmos_calib.param.kiter

    Max number of iterations in ksigma method (int; default: 999) [default=999].
.. py:attribute:: fors_pmos_calib.param.ddegree

    Degree of flat field fitting polynomial along dispersion direction  (int; default: -1) [default=-1].
.. py:attribute:: fors_pmos_calib.param.dradius

    Smooth box radius for flat field along dispersion direction (int;  default: 10) [default=10].
.. py:attribute:: fors_pmos_calib.param.qc

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

    Create intermediate products (bool; default: False) [default=False].


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

::

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

   fors_pmos_calib.param.dispersion = 0.0
   fors_pmos_calib.param.peakdetection = 0.0
   fors_pmos_calib.param.wdegree = 0
   fors_pmos_calib.param.wradius = 4
   fors_pmos_calib.param.wreject = 0.7
   fors_pmos_calib.param.wcolumn = "WLEN"
   fors_pmos_calib.param.cdegree = 0
   fors_pmos_calib.param.cmode = 1
   fors_pmos_calib.param.startwavelength = 0.0
   fors_pmos_calib.param.endwavelength = 0.0
   fors_pmos_calib.param.stack_method = "average"
   fors_pmos_calib.param.minrejection = 1
   fors_pmos_calib.param.maxrejection = 1
   fors_pmos_calib.param.klow = 3.0
   fors_pmos_calib.param.khigh = 3.0
   fors_pmos_calib.param.kiter = 999
   fors_pmos_calib.param.ddegree = -1
   fors_pmos_calib.param.dradius = 10
   fors_pmos_calib.param.qc = True
   fors_pmos_calib.param.check = False


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

::

   import cpl
   fors_pmos_calib = cpl.Recipe("fors_pmos_calib")
   [...]
   res = fors_pmos_calib( ..., param = {"dispersion":0.0, "peakdetection":0.0})


.. 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 `Carlo Izzo <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 FORS Instrument Pipeline
Copyright (C) 2002-2010 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:: Carlo Izzo <usd-help@eso.org>
