The kmo_multi_reconstruct recipe
===============================================================

.. data:: kmo_multi_reconstruct

Synopsis
--------

Reconstruct and combine obj/sky-pairs in one step.

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

Ideally at least two data frames have to be provided since we need for each IFU
pointing to an object as well a sky frame for the same IFU.

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

All IFUs with the same object name will be reconstructed and combined in one step
Telluric correction is only supported if the objects have been observed with
the same IFU on all exposures (dithering).

The number of created files depends on the number of objects of different name.

If the user just wants to combine a certain object, the parameters --name or
--ifus can be used.


Exposures taken with the templates KMOS_spec_obs_mapping8 and
KMOS_spec_obs_mapping24 can't be processed with this recipe! Use kmo_sci_red
instead.


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

   DO                    KMOS                                                  
   category              Type   Explanation                   Required #Frames
   --------              -----  -----------                   -------- -------
   SCIENCE               RAW    The science frames                Y      >=1  
   XCAL                  F2D    x calibration frame               Y       1   
   YCAL                  F2D    y calibration frame               Y       1   
   LCAL                  F2D    Wavelength calib. frame           Y       1   
   MASTER_FLAT           F2D    Master flat                       Y      0,1  
   WAVE_BAND             F2L    Table with start-/end-wavelengths Y       1   
   TELLURIC              F1I    normalised telluric spectrum      N      0,1  
   OH_SPEC               F1S    Vector holding OH lines           N      0,1  

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

   DO                    KMOS
   category              Type   Explanation
   --------              -----  -----------
   CUBE_MULTI            F3I    Combined cubes with noise


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

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

   Create an object for the recipe kmo_multi_reconstruct.

::

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

Parameters
----------

.. py:attribute:: kmo_multi_reconstruct.param.imethod

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

    The shifting method:   'none': no shifting, combined directly,  'header': shift according to WCS (default), 'center': centering  algorithm, 'user': read shifts from file (str; default: 'header') [default="header"].
.. py:attribute:: kmo_multi_reconstruct.param.fmethod

    The fitting method (applies only when method='center'):   'gauss': fit  a gauss function to collapsed image (default), 'moffat': fit a moffat  function to collapsed image (str; default: 'gauss') [default="gauss"].
.. py:attribute:: kmo_multi_reconstruct.param.name

    Name of the object to combine. (str; default: '') [default=""].
.. py:attribute:: kmo_multi_reconstruct.param.ifus

    The indices of the IFUs to combine. "ifu1;ifu2;..." (str; default: '') [default=""].
.. py:attribute:: kmo_multi_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_multi_reconstruct.param.suppress_extension

    Suppress arbitrary filename extension.(TRUE (apply) or FALSE (don't  apply) (bool; default: False) [default=False].
.. py:attribute:: kmo_multi_reconstruct.param.neighborhoodRange

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

    The path to the file with the shift vectors.(Applies only to  method='user') (str; default: '') [default=""].
.. py:attribute:: kmo_multi_reconstruct.param.flux

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

    TRUE: Apply background removal. FALSE: otherwise (bool; default:  False) [default=False].
.. py:attribute:: kmo_multi_reconstruct.param.xcal_interpolation

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

    Don't sky subtract object and references.(TRUE (apply) or FALSE (don't  apply) (bool; default: False) [default=False].
.. py:attribute:: kmo_multi_reconstruct.param.dev_cal

    Development only: If calibration data is to be reconstructed the  ALPHA/DELTA keywords are missing. Setting this parameter to TRUE  prevents according data check (bool; default: False) [default=False].
.. py:attribute:: kmo_multi_reconstruct.param.obj_sky_table

    The path to the file with the modified obj/sky associations. (str;  default: '') [default=""].
.. py:attribute:: kmo_multi_reconstruct.param.b_samples

    The number of samples in wavelength for the reconstructed cube (long;  default: 2048) [default=2048].
.. py:attribute:: kmo_multi_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_multi_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].
.. py:attribute:: kmo_multi_reconstruct.param.cmethod

    Either apply "average", "median", "sum", "min_max." or "ksigma". (str;  default: 'ksigma') [default="ksigma"].
.. py:attribute:: kmo_multi_reconstruct.param.cpos_rej

    The positive rejection threshold for kappa-sigma-clipping (sigma).  (float; default: 3.0) [default=3.0].
.. py:attribute:: kmo_multi_reconstruct.param.cneg_rej

    The negative rejection threshold for kappa-sigma-clipping (sigma).  (float; default: 3.0) [default=3.0].
.. py:attribute:: kmo_multi_reconstruct.param.citer

    The number of iterations for kappa-sigma-clipping. (long; default: 3) [default=3].
.. py:attribute:: kmo_multi_reconstruct.param.cmax

    The number of maximum pixel values to clip with min/max-clipping.  (long; default: 1) [default=1].
.. py:attribute:: kmo_multi_reconstruct.param.cmin

    The number of minimum pixel values to clip with min/max-clipping.  (long; default: 1) [default=1].


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

::

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

   kmo_multi_reconstruct.param.imethod = "MS"
   kmo_multi_reconstruct.param.method = "header"
   kmo_multi_reconstruct.param.fmethod = "gauss"
   kmo_multi_reconstruct.param.name = ""
   kmo_multi_reconstruct.param.ifus = ""
   kmo_multi_reconstruct.param.pix_scale = 0.2
   kmo_multi_reconstruct.param.suppress_extension = False
   kmo_multi_reconstruct.param.neighborhoodRange = 1.001
   kmo_multi_reconstruct.param.filename = ""
   kmo_multi_reconstruct.param.flux = False
   kmo_multi_reconstruct.param.background = False
   kmo_multi_reconstruct.param.xcal_interpolation = True
   kmo_multi_reconstruct.param.no_subtract = False
   kmo_multi_reconstruct.param.dev_cal = False
   kmo_multi_reconstruct.param.obj_sky_table = ""
   kmo_multi_reconstruct.param.b_samples = 2048
   kmo_multi_reconstruct.param.b_start = -1.0
   kmo_multi_reconstruct.param.b_end = -1.0
   kmo_multi_reconstruct.param.cmethod = "ksigma"
   kmo_multi_reconstruct.param.cpos_rej = 3.0
   kmo_multi_reconstruct.param.cneg_rej = 3.0
   kmo_multi_reconstruct.param.citer = 3
   kmo_multi_reconstruct.param.cmax = 1
   kmo_multi_reconstruct.param.cmin = 1


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

::

   import cpl
   kmo_multi_reconstruct = cpl.Recipe("kmo_multi_reconstruct")
   [...]
   res = kmo_multi_reconstruct( ..., param = {"imethod":"MS", "method":"header"})


.. 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>
