The fors_detect_spectra recipe
===============================================================

.. data:: fors_detect_spectra

Synopsis
--------

Detect MOS/MXU spectra on CCD

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

This recipe is used to detect and locate MOS/MXU slit spectra on the CCD,
applying a pattern-matching algorithm. The input spectral exposure must
contain spectra with the dispersion direction approximately horizontal,
with blue on the left and red on the right. Use recipe fors_wave_calib_lss
for LSS data, or for MOS/MXU data where all slits have the same offset.


The rows of the input spectral exposure are processed separately, one
by one. First, the background continuum is removed. Second, a list of
positions of reference lines candidates is created. Only peaks above a
given threshold (specified by the parameter --peakdetection) are selected.

Third, the pattern-matching task selects from the found peaks the ones
corresponding to the reference lines, listed in the input line catalog,
associating them to the appropriate wavelengths. The ensuing polynomial
fit is used to locate the central wavelength of the applied grism along
each image row. The contributions from all rows form an image of the
location of all spectra, that can be used as a starting point for the
proper modeling of the optical and spectral distortions. For more details
on this 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.

Again, see the pipeline manual for more details.


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


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

  DO category:               Type:       Explanation:         Required:
  LAMP_UNBIAS_MXU            Calib       Bias subtracted arc     Y
  MASTER_LINECAT             Calib       Line catalog            Y
  GRISM_TABLE                Calib       Grism table             .


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

  DO category:               Data type:  Explanation:
  SLIT_MAP_MXU               FITS image  Map of central wavelength on CCD
  SLIT_LOCATION_DETECT_MXU   FITS table  Slits positions on CCD
  SPECTRA_DETECTION_MXU      FITS image  Check of preliminary detection


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

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

   Create an object for the recipe fors_detect_spectra.

::

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

Parameters
----------

.. py:attribute:: fors_detect_spectra.param.dispersion

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

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

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

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

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

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

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

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

    Attempt slit identification for MOS or MXU (bool; default: True) [default=True].


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

::

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

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


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

::

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