The kmo_reconstruct recipe
===============================================================

.. data:: kmo_reconstruct

Synopsis
--------

Performs the cube reconstruction using different interpolation methods.

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

Data with or without noise is reconstructed into a cube using the calibration
frames XCAL, YCAL and LCAL. XCAL and YCAL are generated using recipe kmo_flat,
LCAL is generated using recipe kmo_wave_cal.

The input data can contain noise extensions and will be reconstructed into
additional extensions.

If an OH spectrum is given in the SOF file the lambda axis will be corrected
using the OH lines as reference.


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

   DO                  KMOS                                                    
   category            Type     Explanation                    Required #Frames
   --------            -----    -----------                    -------- -------
   DARK    or          RAW/F2D  data with                          Y       1   
   FLAT_ON or          RAW/F2D  or without noise                               
   ARC_ON  or          RAW/F2D                                                 
   OBJECT  or          RAW                                                     
   STD     or          RAW                                                     
   SCIENCE             RAW                                                     
   XCAL                F2D      x-direction calib. frame           Y       1   
   YCAL                F2D      y-direction calib. frame           Y       1   
   LCAL                F2D      Wavelength calib. frame            Y       1   
   WAVE_BAND           F2L      Table with start-/end-wavelengths  Y       1   
   OH_SPEC             F1S      Vector holding OH lines            N       1   

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

   DO                    KMOS
   category              Type     Explanation
   --------              -----    -----------
   CUBE_DARK   or        F3I      Reconstructed cube   
   CUBE_FLAT   or        RAW/F2D  with or without noise
   CUBE_ARC    or                                      
   CUBE_OBJECT or                                      
   CUBE_STD    or                                      
   CUBE_SCIENCE                                        


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

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

   Create an object for the recipe kmo_reconstruct.

::

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

Parameters
----------

.. py:attribute:: kmo_reconstruct.param.imethod

    Method to use for interpolation. ["NN" (nearest neighbour), "lwNN"  (linear weighted nearest neighbor), "swNN" (square weighted nearest  neighbor), "MS" (Modified Shepard's method)"CS" (Cubic spline)] (str;  default: 'CS') [default="CS"].
.. py:attribute:: kmo_reconstruct.param.neighborhoodRange

    Defines the range to search for neighbors. in pixels (float; default:  1.001) [default=1.001].
.. py:attribute:: kmo_reconstruct.param.flux

    TRUE: Apply flux conservation. FALSE: otherwise (bool; default: False) [default=False].
.. py:attribute:: kmo_reconstruct.param.detimg

    TRUE: if resampled detector frame should be created, FALSE: otherwise  (bool; default: False) [default=False].
.. py:attribute:: kmo_reconstruct.param.file_extension

    TRUE: if OBS_ID keyword should be appended to output frames, FALSE:  otherwise (bool; default: False) [default=False].
.. py:attribute:: kmo_reconstruct.param.pix_scale

    Change the pixel scale [arcsec]. Default of 0.2" results into cubes of  14x14pix, a scale of 0.1" results into cubes of 28x28pix, etc. (float;  default: 0.2) [default=0.2].
.. py:attribute:: kmo_reconstruct.param.dev_flip

    INTENDED FOR PIPELINE DEVELOPERS ONLY: Set this parameter to TRUE if  the wavelengths are ascending on the detector from bottom to top (only  for old simulation data). (bool; default: False) [default=False].
.. py:attribute:: kmo_reconstruct.param.xcal_interpolation

    TRUE: Interpolate xcal between rotator angles. FALSE: otherwise (bool;  default: True) [default=True].
.. py:attribute:: kmo_reconstruct.param.b_samples

    The number of samples in wavelength for the reconstructed cube (long;  default: 2048) [default=2048].
.. py:attribute:: kmo_reconstruct.param.b_start

    The lowest wavelength [um] to take into account when reconstructing  (default of -1 sets the proper value for the actual band  automatically) (float; default: -1.0) [default=-1.0].
.. py:attribute:: kmo_reconstruct.param.b_end

    The highest wavelength [um] to take into account when reconstructing  (default of -1 sets the proper value for the actual band  automatically) (float; default: -1.0) [default=-1.0].


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

::

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

   kmo_reconstruct.param.imethod = "CS"
   kmo_reconstruct.param.neighborhoodRange = 1.001
   kmo_reconstruct.param.flux = False
   kmo_reconstruct.param.detimg = False
   kmo_reconstruct.param.file_extension = False
   kmo_reconstruct.param.pix_scale = 0.2
   kmo_reconstruct.param.dev_flip = False
   kmo_reconstruct.param.xcal_interpolation = True
   kmo_reconstruct.param.b_samples = 2048
   kmo_reconstruct.param.b_start = -1.0
   kmo_reconstruct.param.b_end = -1.0


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

::

   import cpl
   kmo_reconstruct = cpl.Recipe("kmo_reconstruct")
   [...]
   res = kmo_reconstruct( ..., param = {"imethod":"CS", "neighborhoodRange":1.001})


.. 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 `Alex Agudo Berbel <kmos-spark@mpe.mpg.de>`_. Alternatively, you may 
send a report to the `ESO User Support Department <usd-help@eso.org>`_.

Copyright
---------

This file is part of the KMOS Instrument Pipeline
Copyright (C) 2002,2003 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, 51 Franklin Street, Suite 500, Boston, MA  02110-1335  USA

.. codeauthor:: Alex Agudo Berbel <kmos-spark@mpe.mpg.de>
