The fors_wave_calib_lss recipe
===============================================================

.. data:: fors_wave_calib_lss

Synopsis
--------

Derive dispersion relation from long-slit arc lamp frame

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

This recipe is used to wavelength calibrate one long slit spectrum, i.e.,
a FORS spectral obtained either in LSS mode or in MOS/MXU mode with all
slits at the same offset. A pattern-matching algorithm is applied as in
recipe fors_detect_spectra. 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 LSS acronym can be alternatively read as MOS or
MXU.


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

  DO category:               Type:       Explanation:         Required:
  LAMP_UNBIAS_LSS            Calib       Arc lamp exposure       Y
  MASTER_LINECAT             Calib       Line catalog            Y
  GRISM_TABLE                Calib       Grism table             .


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

  DO category:               Data type:  Explanation:
  REDUCED_LAMP_LSS           FITS image  Calibrated arc lamp exposure
  DISP_COEFF_LSS             FITS table  Inverse dispersion coefficients
  DISP_RESIDUALS_LSS         FITS image  Image of modeling residuals
  WAVELENGTH_MAP_LSS         FITS image  Wavelengths mapped on CCD
  SLIT_LOCATION_LSS          FITS image  Background subtracted arc frame
  SPECTRAL_RESOLUTION_LSS    FITS table  Spectral resolution table


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

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

   Create an object for the recipe fors_wave_calib_lss.

::

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

Parameters
----------

.. py:attribute:: fors_wave_calib_lss.param.dispersion

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

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

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

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

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

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

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

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

    Interpolation mode of wavelength solution (0 = no interpolation, 1 =  fill gaps, 2 = global model) (int; default: 2) [default=2].


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

::

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

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


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_lss = cpl.Recipe("fors_wave_calib_lss")
   [...]
   res = fors_wave_calib_lss( ..., 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>
