The kmo_sky_mask recipe
===============================================================

.. data:: kmo_sky_mask

Synopsis
--------

Create a mask of spatial pixels that indicates which pixels can be considered as sky.

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

This recipes calculates masks of the skies surrounding the objects in the diff-
erent IFUs of a reconstructed F3I frame. In the resulting mask pixels belonging
to objects have value 1 and sky pixels have value 0.

The noise and the background level of the input data cube are estimated using
the mode calculated in kmo_stats. If the results aren't satisfactory, try chan-
ging --cpos_rej and --cneg_rej. Then pixels are flagged in the data cube which
have a value less than the mode plus twice the noise (val < mode + 2*sigma).

For each spatial pixel the fraction of flagged pixels in its spectral channel
is determined.

Spatial pixels are selected where the fraction of flagged spectral pixels is
greater than 0.95 (corresponding to the 2*sigma above).

The input cube can contain noise extensions, but they will be ignored. The out-
put doesn’t contain noise extensions.


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

   DO                    KMOS                                                  
   category              Type   Explanation                    Required #Frames
   --------              -----  -----------                    -------- -------
   <none or any>         F3I    The datacube frame                 Y       1   

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

   DO                    KMOS
   category              Type   Explanation
   --------              -----  -----------
   SKY_MASK              F2I    The mask frame


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

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

   Create an object for the recipe kmo_sky_mask.

::

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

Parameters
----------

.. py:attribute:: kmo_sky_mask.param.range

    Min & max wavelengths to use in sky pixel determination, e.g.  [x1_start,x1_end] (microns). (str; default: '') [default=""].
.. py:attribute:: kmo_sky_mask.param.fraction

    Minimum fraction of spatial pixels to select as sky (value between 0  and 1). (float; default: 0.95) [default=0.95].
.. py:attribute:: kmo_sky_mask.param.cpos_rej

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

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

    The number of iterations for kappa-sigma-clipping. (int; default: 3) [default=3].


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

::

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

   kmo_sky_mask.param.range = ""
   kmo_sky_mask.param.fraction = 0.95
   kmo_sky_mask.param.cpos_rej = 3.0
   kmo_sky_mask.param.cneg_rej = 3.0
   kmo_sky_mask.param.citer = 3


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

::

   import cpl
   kmo_sky_mask = cpl.Recipe("kmo_sky_mask")
   [...]
   res = kmo_sky_mask( ..., param = {"range":"", "fraction":0.95})


.. seealso:: `cpl.Recipe <https://packages.python.org/python-cpl/recipe.html>`_
   for more information about the recipe object.

Bug reports
-----------

Please report any problems to `Alex Agudo Berbel <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 <usd-help@eso.org>