The visir_spc_reduce recipe
===============================================================

.. data:: visir_spc_reduce

Synopsis
--------

Spectroscopic Observation recipe

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

This recipe performs a wavelength calibration followed by spectrum extraction from a combined image. It can also compute sensitivities for standard star observations.

It works for low and high resolution including echelle mode.

The files listed in the Set Of Frames (sof-file) must be tagged:
VISIR-Long-Slit-Spectroscopy-file.fits SPEC_OBS_LMR
VISIR-Quantum-Efficiency-Calibration-file.fits SPEC_CAL_QEFF
VISIR-Atmospheric-Emission-Lines-Calibration-file.fits SPEC_CAL_LINES
VISIR-Standard-Star-Flux-Catalog.fits (optional)SPEC_STD_CATALOG
VISIR-linearty-table.fits LINEARITY_TABLE (optional)
Additionally, a bad pixel map with a PRO.CATG of IMG_BPM
may be added to the Set Of Frames with tag: BPM.


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

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

   Create an object for the recipe visir_spc_reduce.

::

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

Parameters
----------

.. py:attribute:: visir_spc_reduce.param.planestart

    Plane number to start repacking from, earlier planes are skipped.  (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.ncycles

    Number of full on-off cycles to repack. <= 0 for all. (long; default:  -1) [default=-1].
.. py:attribute:: visir_spc_reduce.param.trimlow

    Burst data only. Number of additional planes to cut from before each  plane with chopper movement. (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.trimhigh

    Burst data only. Number of additional planes to cut from after each  plane with chopper movement.  A value of -1 does not skip the plane of  the movement. (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.xl

    Coordinate in spatial direction. Together with yl it defines the lower  point of a rectangle containing only skylines for the wavelength shift  detection (long; default: 117) [default=117].
.. py:attribute:: visir_spc_reduce.param.yl

    Coordinate in wavelength direction. See xl (long; default: 110) [default=110].
.. py:attribute:: visir_spc_reduce.param.xh

    Coordinate in spatial direction. Together with yl it defines the  higher point of a rectangle containing only skylines for the  wavelength shift detection (long; default: 125) [default=125].
.. py:attribute:: visir_spc_reduce.param.yh

    Coordinate in wavelength direction. See xh (long; default: 150) [default=150].
.. py:attribute:: visir_spc_reduce.param.slit_skew

    Distortion correction: Skew of slit (degrees) (clockwise) (float;  default: 0.52) [default=0.52].
.. py:attribute:: visir_spc_reduce.param.spectrum_skew

    Distortion correction: LMR Skew of spectrum (degrees) (counter-  clockwise). Not used in High Resolution (float; default: 1.73) [default=1.73].
.. py:attribute:: visir_spc_reduce.param.vert_arc

    Distortion correction: LR Detector vertical curvature (pixel). Reduced  by a factor 4 in MR. Not used in HR A-side. Increased by a factor  115/52 in HR B-side (float; default: -0.8) [default=-0.8].
.. py:attribute:: visir_spc_reduce.param.hori_arc

    Distortion correction: LMR Detector horizontal curvature (pixel).  Increased by a factor 1.5 in HR A-side. Reduced by a factor 2 in HR  B-side (float; default: 0.0) [default=0.0].
.. py:attribute:: visir_spc_reduce.param.destripe_iterations

    Max number of destriping iterations (0 to disable destriping).  Horizontal destriping is done first and if no horizontal striping is  detected, vertical destriping is performed (long; default: 15) [default=15].
.. py:attribute:: visir_spc_reduce.param.destripe_morpho

    Destripe with morphological cleaning (bool; default: False) [default=False].
.. py:attribute:: visir_spc_reduce.param.rej

    Each resulting pixel is the average of the corresponding  (interpolated) pixel value in each jittered image. A positive value,  n1, for the first of the two integers specifies that for each pixel  the smallest n1 pixel values shall be ignored in the averaging.  Similarly, a positive value, n2, for the second of the two integers  specifies that for each pixel the largest n2 pixel values shall be  ignored in the averaging. (str; default: '0-0') [default="0-0"].
.. py:attribute:: visir_spc_reduce.param.bkgcorrect

    Subtract the median from the spectral column before extracting the  wavelength. This is required when the skylines do not correctly cancel  due to gratting oscillations (bool; default: False) [default=False].
.. py:attribute:: visir_spc_reduce.param.plot

    The recipe can produce a number of predefined plots. Zero means that  none of the plots are produced, while increasing values (e.g. 1 or 2)  increases the number of plots produced. If the plotting fails a  warning is produced, and the recipe continues. The default behaviour  of the plotting is to use gnuplot (with option -persist). The recipe  currently produces 1D-plots using gnuplot commands. The recipe user  can control the actual plotting-command used by the recipe to create  the plot by setting the environment variable CPL_PLOTTER. Currently,  if CPL_PLOTTER is set it must contain the string 'gnuplot'. Setting it  to 'cat > my_gnuplot_$$.txt' causes a number of ASCII-files to be  created, which each produce a plot when given as standard input to  gnuplot (e.g. later or on a different computer). A finer control of  the plotting options can be obtained by writing an executable script,  e.g. my_gnuplot.pl, that executes gnuplot after setting the desired  gnuplot options (e.g. set terminal pslatex color) and then setting  CPL_PLOTTER to my_gnuplot.pl. The predefined plots include plotting of  images. Images can be plotted not only with gnuplot, but also using  the pnm format. This is controlled with the environment variable  CPL_IMAGER. If CPL_IMAGER is set to a string that does not contain the  word gnuplot, the recipe will generate the plot in pnm format. E.g.  setting CPL_IMAGER to 'display - &' will produce a gray-scale image  using the image viewer display. (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.slit_skew

    Distortion correction: Skew of slit (degrees) (clockwise) (float;  default: 0.52) [default=0.52].
.. py:attribute:: visir_spc_reduce.param.spectrum_skew

    Distortion correction: LMR Skew of spectrum (degrees) (counter-  clockwise). Not used in High Resolution (float; default: 1.73) [default=1.73].
.. py:attribute:: visir_spc_reduce.param.vert_arc

    Distortion correction: LR Detector vertical curvature (pixel). Reduced  by a factor 4 in MR. Not used in HR A-side. Increased by a factor  115/52 in HR B-side (float; default: -0.8) [default=-0.8].
.. py:attribute:: visir_spc_reduce.param.hori_arc

    Distortion correction: LMR Detector horizontal curvature (pixel).  Increased by a factor 1.5 in HR A-side. Reduced by a factor 2 in HR  B-side (float; default: 0.0) [default=0.0].
.. py:attribute:: visir_spc_reduce.param.orderoffset

    Echelle order offset. The offset is relative to the main order. The  allowed range of offsets depend on the selected grism. The offset can  never exceed +/-4. If the main order is e.g. 8 an order offset of +1  will cause the recipe to base the data reduction on order 9. With a  positive order offset the central wavelength becomes smaller while for  a negative order offset the central wavelength becomes larger. (long;  default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.fixcombi

    Perform the distortion correction on the combined image, and not on  each of the jittered images. This will reduce excution time and  degrade the quality of the combined image (bool; default: False) [default=False].
.. py:attribute:: visir_spc_reduce.param.emis_tol

    The computation of the mean and standard deviation of the sensitivity  is done for wavelengths with an atmospheric emissivity of at most  emis_min + emis_tol * (emis_max - emis_min), where emis_min is the  minimum emissivity in the observed wavelength range and emis_max is  the ditto maximum. Thus emis_tol = 1 means that all wavelengths are  included. (float; default: 1.0) [default=1.0].
.. py:attribute:: visir_spc_reduce.param.destripe_iterations

    Max number of destriping iterations (0 to disable destriping).  Horizontal destriping is done first and if no horizontal striping is  detected, vertical destriping is performed (long; default: 15) [default=15].
.. py:attribute:: visir_spc_reduce.param.destripe_morpho

    Destripe with morphological cleaning (bool; default: False) [default=False].
.. py:attribute:: visir_spc_reduce.param.rl

    Reject leftmost columns in spectrum extraction, zero means all columns  on the left are used. In cross-dispersion mode a (small) negative  number may be used (pixel) (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.rr

    Reject rightmost columns in spectrum extraction, zero means all  columns on the right are used. In cross-dispersion mode a (small)  negative number may be used (pixel) (long; default: 0) [default=0].
.. py:attribute:: visir_spc_reduce.param.delete_temp

    Delete temporary files created during processing (bool; default: True) [default=True].
.. py:attribute:: visir_spc_reduce.param.destripe

    Attempt to remove stripes (bool; default: False) [default=False].


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

::

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

   visir_spc_reduce.param.planestart = 0
   visir_spc_reduce.param.ncycles = -1
   visir_spc_reduce.param.trimlow = 0
   visir_spc_reduce.param.trimhigh = 0
   visir_spc_reduce.param.xl = 117
   visir_spc_reduce.param.yl = 110
   visir_spc_reduce.param.xh = 125
   visir_spc_reduce.param.yh = 150
   visir_spc_reduce.param.slit_skew = 0.52
   visir_spc_reduce.param.spectrum_skew = 1.73
   visir_spc_reduce.param.vert_arc = -0.8
   visir_spc_reduce.param.hori_arc = 0.0
   visir_spc_reduce.param.destripe_iterations = 15
   visir_spc_reduce.param.destripe_morpho = False
   visir_spc_reduce.param.rej = "0-0"
   visir_spc_reduce.param.bkgcorrect = False
   visir_spc_reduce.param.plot = 0
   visir_spc_reduce.param.slit_skew = 0.52
   visir_spc_reduce.param.spectrum_skew = 1.73
   visir_spc_reduce.param.vert_arc = -0.8
   visir_spc_reduce.param.hori_arc = 0.0
   visir_spc_reduce.param.orderoffset = 0
   visir_spc_reduce.param.fixcombi = False
   visir_spc_reduce.param.emis_tol = 1.0
   visir_spc_reduce.param.destripe_iterations = 15
   visir_spc_reduce.param.destripe_morpho = False
   visir_spc_reduce.param.rl = 0
   visir_spc_reduce.param.rr = 0
   visir_spc_reduce.param.delete_temp = True
   visir_spc_reduce.param.destripe = False


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

::

   import cpl
   visir_spc_reduce = cpl.Recipe("visir_spc_reduce")
   [...]
   res = visir_spc_reduce( ..., param = {"planestart":0, "ncycles":-1})


.. 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 `Julian Taylor <jtaylor@partner.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 VISIR Instrument Pipeline
Copyright (C) 2015 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  02111-1307  USA

.. codeauthor:: Julian Taylor <jtaylor@partner.eso.org>
