The kmo_stats recipe
===============================================================

.. data:: kmo_stats

Synopsis
--------

Perform basic statistics on a KMOS-conform fits-file

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

This recipe performs basic statistics on KMOS-conform data-frames of type F2D,
F1I, F2I and F3I either with or without noise and RAW. Optionally a 2D mask
can be provided to define a region on which the statistics should be calculated
on (mask 0: exclude pixel, mask 1: include pixel). A mask can’t be provided for
statistics on F1I frames.

The output is stored in a vector of length 11. The vector represents following
values:
   1.  Number of pixels
   2.  Number of finite pixels
   3.  Mean
   4.  Standard Deviation
   5.  Mean with iterative rejection (i.e. mean & sigma are calculated iterati-
       vely, each time rejecting pixels more than +/-N sigma from the mean)
   6.  Standard Deviation with iterative rejection
   7.  Median
   8.  Mode (i.e. the peak in a histogram of pixel values)
   9.  Noise (a robust estimate given by the standard deviation from the nega-
       tive side of the histogram of pixel values)
   10. Minimum
   11. Maximum

The same numerical operations are applied to the noise as with the data itself.


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

   DO            DO      KMOS                                                  
   category      group   Type   Explanation                    Required #Frames
   --------      -----   -----  -----------                    -------- -------
   <none or any>   -     F3I or The datacubes                      Y       1   
                         F2I or                                                
                         F1I or                                                
                         F2D or                                                
                         B2D or                                                
                         RAW                                                   
   <none or any>   -     F2I or The mask                           N      0,1  
                         F2D or                                                
                         B2D or                                                
                         RAW                                                   

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

   DO                    KMOS
   category              Type   Explanation
   --------              -----  -----------
   STATS                 F1I    Calculated statistics parameters 


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

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

   Create an object for the recipe kmo_stats.

::

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

Parameters
----------

.. py:attribute:: kmo_stats.param.ext

    The extension the stats should be calculated of. Zero is default and  calculates the stats of all extensions (long; default: 0) [default=0].
.. py:attribute:: kmo_stats.param.cpos_rej

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

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

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


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

::

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

   kmo_stats.param.ext = 0
   kmo_stats.param.cpos_rej = 3.0
   kmo_stats.param.cneg_rej = 3.0
   kmo_stats.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_stats = cpl.Recipe("kmo_stats")
   [...]
   res = kmo_stats( ..., param = {"ext":0, "cpos_rej":3.0})


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