The kmos_std_star recipe
===============================================================

.. data:: kmos_std_star

Synopsis
--------

Create the telluric correction frame.

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

This recipe creates a telluric frame and a PSF frames.

Since there cannot be 1 std star per IFU in one exposure, we use several
exposures in order to have at least one standard star and one sky
in each IFU. The frames are organised following this logic:
1. For each IFU the first standard star in the list of frames is
   taken. All subsequent standard star exposures for this IFU are ignored
2. A closest in time sky exposure is uѕed
3. IFUs not containing a standard star and a sky will be empty in the result

NOISE_SPEC contains the shot noise [sqrt(counts*gain)/gain]
If the exposures have been taken with KMOS_spec_cal_stdstarscipatt, an
additional noise component is added: All existing sky exposures for an IFU
are subtracted pairwise, spectra are extracted and the std deviation is 
computed

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

   DO                      KMOS                                             
   category                Type  Explanation                Required #Frames
   --------                ----- -----------                -------- -------
   STD                     RAW   Std. star & sky exposures      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 frame              Y      1    
   WAVE_BAND               F2L   Table with start-/end-wl       Y      1    
   ILLUM_CORR              F2I   Illumination correction        N     0,1   
   SOLAR_SPEC              F1S   Solar spectrum                 N     0,1   
                                 (only for G stars)                         
   ATMOS_MODEL             F1S   Model atmospheric transmisson  N     0,1   
                                 (only for OBAF stars in K band)            
   SPEC_TYPE_LOOKUP        F2L   LUT  eff. stellar temperature  N     0,1   

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

   DO                      KMOS                                            
   category                Type   Explanation                              
   --------                -----  -----------                              
   TELLURIC                F1I    The normalised telluric spectrum         
                                  (including errors)                       
   STAR_SPEC               F1I    The extracted star spectrum              
                                  (including errors)                       
   STD_IMAGE               F2I    The standard star PSF images             
   STD_MASK                F2I    The mask used to extract the star spec   
   NOISE_SPEC              F1I    The extracted noise spectrum             


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

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

   Create an object for the recipe kmos_std_star.

::

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

Parameters
----------

.. py:attribute:: kmos_std_star.param.startype

    The spectral type of the star (O, B, A, F, G) e.g. G4V (str; default:  '') [default=""].
.. py:attribute:: kmos_std_star.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:: kmos_std_star.param.fmethod

    Fitting method (gauss, moffat, profile (str; default: 'gauss') [default="gauss"].
.. py:attribute:: kmos_std_star.param.neighborhoodRange

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

    Star magnitude (2 values in HK, eg. 12.1,13.2) (str; default: '') [default=""].
.. py:attribute:: kmos_std_star.param.flux

    TRUE: Apply flux conservation. FALSE: otherwise (bool; default: True) [default=True].
.. py:attribute:: kmos_std_star.param.save_cubes

    Flag to save reconstructed cubes (bool; default: False) [default=False].
.. py:attribute:: kmos_std_star.param.no_noise

    Skip the noise computation on sky exposures (bool; default: False) [default=False].
.. py:attribute:: kmos_std_star.param.xcal_interpolation

    Flag to Interpolate xcal between rotator angles (bool; default: True) [default=True].
.. py:attribute:: kmos_std_star.param.suppress_extension

    Flag to Suppress filename extension (bool; default: False) [default=False].
.. py:attribute:: kmos_std_star.param.b_samples

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

    Method used : mask, integrated or optimal (str; default: 'optimal') [default="optimal"].
.. py:attribute:: kmos_std_star.param.centre

    The centre of the circular mask (pixel) (str; default: '7.5,7.5') [default="7.5,7.5"].
.. py:attribute:: kmos_std_star.param.radius

    The radius of the circular mask (pixel) (float; default: 3.0) [default=3.0].
.. py:attribute:: kmos_std_star.param.cmethod

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

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

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

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

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

   kmos_std_star.param.startype = ""
   kmos_std_star.param.imethod = "CS"
   kmos_std_star.param.fmethod = "gauss"
   kmos_std_star.param.neighborhoodRange = 1.001
   kmos_std_star.param.magnitude = ""
   kmos_std_star.param.flux = True
   kmos_std_star.param.save_cubes = False
   kmos_std_star.param.no_noise = False
   kmos_std_star.param.xcal_interpolation = True
   kmos_std_star.param.suppress_extension = False
   kmos_std_star.param.b_samples = 2048
   kmos_std_star.param.b_start = -1.0
   kmos_std_star.param.b_end = -1.0
   kmos_std_star.param.mask_method = "optimal"
   kmos_std_star.param.centre = "7.5,7.5"
   kmos_std_star.param.radius = 3.0
   kmos_std_star.param.cmethod = "ksigma"
   kmos_std_star.param.cpos_rej = 3.0
   kmos_std_star.param.cneg_rej = 3.0
   kmos_std_star.param.citer = 3
   kmos_std_star.param.cmax = 1
   kmos_std_star.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_std_star = cpl.Recipe("kmos_std_star")
   [...]
   res = kmos_std_star( ..., param = {"startype":"", "imethod":"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, Y. 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, Y. Jung <usd-help@eso.org>
