The kmos_sci_red recipe
===============================================================

.. data:: kmos_sci_red

Synopsis
--------

Reconstruct obj/sky-pairs individually and combine them afterwards

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

Two data frames are expected in order to have a sky IFU for the IFU Objects.

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

Every IFU containing an object will be reconstructed and divided by telluric
and illumination correction. By default these intermediate cubes are saved
to disk. The reconstructed objects with the same object name are combined.

In order to combine a specific object, the parameters --name or --ifus can
be used.

For exposures taken with the templates KMOS_spec_obs_mapping8 and
KMOS_spec_obs_mapping24, all active IFUs are combined.


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   
   WAVE_BAND         F2L    Table with start-/end-wavelengths Y       1   
   MASTER_FLAT       F2D    Master flat                       Y      0,1  
   ILLUM_CORR        F2I    Illumination correction           N      0,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
   --------              -----  -----------
   SCI_COMBINED      F3I    Combined cubes with noise
   SCI_RECONSTRUCTED F3I    Reconstructed cube with noise
   EXP_MASK          F3I    Exposure time mask (not for mapping-templates!)
   SCI_INTERIM_OBJECT F3I    (optional) Intermediate reconstructed object 
                            cubes used for sky tweaking, no noise 
                            (set --sky_tweak and --save_interims)
   SCI_INTERIM_SKY   F3I    (optional) Intermediate reconstructed sky 
                            cubes used for sky tweaking, no noise
                            (set --sky_tweak and --save_interims)
   SCI_COMBINED_COLL        (optional) Collapsed combined cube
                            (set --collapse_combined)
   SCI_RECONSTRUCTED_COLL   (optional) Collapsed reconstructed cube
                            (set --collapse_reconstructed)


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

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

   Create an object for the recipe kmos_sci_red.

::

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

Parameters
----------

.. py:attribute:: kmos_sci_red.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)"CS"  (Cubic spline)] (str; default: 'CS') [default="CS"].
.. py:attribute:: kmos_sci_red.param.smethod

    Method to use for interpolation during shifting. ["NN" (nearest  neighbour), "CS" (Cubic spline)] (str; default: 'CS') [default="CS"].
.. py:attribute:: kmos_sci_red.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:: kmos_sci_red.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:: kmos_sci_red.param.name

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

    The indices of the IFUs to combine. "ifu1;ifu2;..." (str; default: '') [default=""].
.. py:attribute:: kmos_sci_red.param.oscan

    Apply Overscan Correction (bool; default: True) [default=True].
.. py:attribute:: kmos_sci_red.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:: kmos_sci_red.param.suppress_extension

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

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

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

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

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

    FALSE: cubes are shifted and combined,TRUE: cubes are collapsed and  then shifted and combined (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.extrapolate

    Applies only to 'smethod=CS' when doing sub-pixel shifts: FALSE:  shifted IFU will be filled with NaN's at the borders,TRUE: shifted IFU  will be extrapolated at the borders (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.xcal_interpolation

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

    Set borders of cubes to NaN before combining them.(TRUE (apply) or  FALSE (don't apply) (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.no_combine

    Don't combine cubes after reconstruction.(TRUE (apply) or FALSE (don't  apply) (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.no_subtract

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

    Use modified sky cube for sky subtraction.(TRUE (apply) or FALSE  (don't apply) (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.skip_sky_oh_align

    Skip the OH alignment for the SKY (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.discard_subband

    Ignore last sub-band in the sky tweaking (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.stretch

    Stretch sky in the sky tweaking (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.stretch_degree

    Stretch polynomial degree (long; default: 8) [default=8].
.. py:attribute:: kmos_sci_red.param.stretch_resampling

    Stretch resampling method (linear/spline) (str; default: 'spline') [default="spline"].
.. py:attribute:: kmos_sci_red.param.tbsub

    Subtract thermal background from input cube.(TRUE (apply) or FALSE  (don't apply) (bool; default: True) [default=True].
.. py:attribute:: kmos_sci_red.param.b_samples

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

    The lowest wavelength [um] to use when reconstructing. Derived by  default, depending on the band (float; default: -1.0) [default=-1.0].
.. py:attribute:: kmos_sci_red.param.b_end

    The highest wavelength [um] to use when reconstructing. Derived by  default, depending on the band (float; default: -1.0) [default=-1.0].
.. py:attribute:: kmos_sci_red.param.obj_sky_table

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

    Specify velocity offset correction in km/s for lambda scale (float;  default: 0.0) [default=0.0].
.. py:attribute:: kmos_sci_red.param.save_interims

    Save interim object and sky cubes. Can only be used together with  --sky_tweak (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.collapse_reconstructed

    Flag to collapse the reconstructed images (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.collapse_combined

    Flag to collapse the combined images (bool; default: False) [default=False].
.. py:attribute:: kmos_sci_red.param.cmethod

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

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

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

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

    The number of maximum pixel values to clip with min/max-clipping.  (long; default: 1) [default=1].
.. py:attribute:: kmos_sci_red.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
   kmos_sci_red = cpl.Recipe("kmos_sci_red")

   kmos_sci_red.param.imethod = "CS"
   kmos_sci_red.param.smethod = "CS"
   kmos_sci_red.param.method = "header"
   kmos_sci_red.param.fmethod = "gauss"
   kmos_sci_red.param.name = ""
   kmos_sci_red.param.ifus = ""
   kmos_sci_red.param.oscan = True
   kmos_sci_red.param.pix_scale = 0.2
   kmos_sci_red.param.suppress_extension = False
   kmos_sci_red.param.neighborhoodRange = 1.001
   kmos_sci_red.param.filename = ""
   kmos_sci_red.param.flux = False
   kmos_sci_red.param.background = False
   kmos_sci_red.param.fast_mode = False
   kmos_sci_red.param.extrapolate = False
   kmos_sci_red.param.xcal_interpolation = True
   kmos_sci_red.param.edge_nan = False
   kmos_sci_red.param.no_combine = False
   kmos_sci_red.param.no_subtract = False
   kmos_sci_red.param.sky_tweak = False
   kmos_sci_red.param.skip_sky_oh_align = False
   kmos_sci_red.param.discard_subband = False
   kmos_sci_red.param.stretch = False
   kmos_sci_red.param.stretch_degree = 8
   kmos_sci_red.param.stretch_resampling = "spline"
   kmos_sci_red.param.tbsub = True
   kmos_sci_red.param.b_samples = 2048
   kmos_sci_red.param.b_start = -1.0
   kmos_sci_red.param.b_end = -1.0
   kmos_sci_red.param.obj_sky_table = ""
   kmos_sci_red.param.velocity_offset = 0.0
   kmos_sci_red.param.save_interims = False
   kmos_sci_red.param.collapse_reconstructed = False
   kmos_sci_red.param.collapse_combined = False
   kmos_sci_red.param.cmethod = "ksigma"
   kmos_sci_red.param.cpos_rej = 3.0
   kmos_sci_red.param.cneg_rej = 3.0
   kmos_sci_red.param.citer = 3
   kmos_sci_red.param.cmax = 1
   kmos_sci_red.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
   kmos_sci_red = cpl.Recipe("kmos_sci_red")
   [...]
   res = kmos_sci_red( ..., param = {"imethod":"CS", "smethod":"CS"})


.. 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, Yves Jung <usd-help@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 CRIRES 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, Inc., 59 Temple Place, Suite 330, Boston, 
MA  02111-1307  USA

.. codeauthor:: Alex Agudo Berbel, Yves Jung <usd-help@eso.org>
