The fors_wave_calib recipe
===============================================================

.. data:: fors_wave_calib

Synopsis
--------

Derive dispersion relation from rectified arc lamp frame

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

This recipe is used to wavelength calibrate MOS/MXU slit spectra contained
in the rectified arc lamp exposure produced with recipe fors_extract_slits.

A pattern-matching algorithm is applied as in recipe fors_detect_spectra.

The input spatial map is used in the production of the wavelength map.


Use recipe fors_wave_calib_lss for LSS data, or for MOS/MXU data where all
slits have the same offset. For more details on this data reduction strategy
please refer to the FORS Pipeline User's Manual.


Note that specifying an input GRISM_TABLE will set some of the recipe
configuration parameters to default values valid for a particular grism.


In the table below the MXU acronym can be alternatively read as MOS.


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

  DO category:               Type:       Explanation:         Required:
  SPATIAL_MAP_MXU            Calib       Spatial map             Y
  RECTIFIED_LAMP_MXU         Calib       Rectified arc exposure  Y
  SLIT_LOCATION_MXU          Calib       Slit location table     Y
  CURV_COEFF_MXU             Calib       Spectral curvature      Y
  MASTER_LINECAT             Calib       Line catalog            Y
  GRISM_TABLE                Calib       Grism table             .


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

  DO category:               Data type:  Explanation:
  REDUCED_LAMP_MXU           FITS image  Calibrated arc lamp exposure
  DISP_COEFF_MXU             FITS table  Inverse dispersion coefficients
  DISP_RESIDUALS_MXU         FITS image  Image of modeling residuals
  WAVELENGTH_MAP_MXU         FITS image  Wavelengths mapped on CCD
  SPECTRAL_RESOLUTION_MXU    FITS table  Spectral resolution table


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

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

   Create an object for the recipe fors_wave_calib.

::

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

Parameters
----------

.. py:attribute:: fors_wave_calib.param.dispersion

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

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

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

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

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

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

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

    End wavelength in spectral extraction (float; default: 0.0) [default=0.0].


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

::

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

   fors_wave_calib.param.dispersion = 0.0
   fors_wave_calib.param.peakdetection = 0.0
   fors_wave_calib.param.wdegree = 0
   fors_wave_calib.param.wradius = 4
   fors_wave_calib.param.wreject = 0.7
   fors_wave_calib.param.wcolumn = "WLEN"
   fors_wave_calib.param.startwavelength = 0.0
   fors_wave_calib.param.endwavelength = 0.0


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

::

   import cpl
   fors_wave_calib = cpl.Recipe("fors_wave_calib")
   [...]
   res = fors_wave_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>