The visir_util_clip recipe
===============================================================

.. data:: visir_util_clip

Synopsis
--------

Kappa-sigma clipping of outliers for each pixel

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

The files listed in the Set Of Frames (sof-file) must be tagged pair-wise:
VISIR-raw-file.fits RAW
VISIR-bpm-file.fits BPM

The product(s) will have a FITS card
'HIERARCH ESO PRO CATG' with a value of:
BPM
The outliers are marked as rejected in the matching
bad pixel map.


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

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

   Create an object for the recipe visir_util_clip.

::

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

Parameters
----------

.. py:attribute:: visir_util_clip.param.keepfrac

    The fraction of pixels to keep for the initialmedian (float; default:  0.9) [default=0.9].
.. py:attribute:: visir_util_clip.param.kappa

    Clip outside + or - kappa * sigma (the standard deviation) (float;  default: 5.0) [default=5.0].
.. py:attribute:: visir_util_clip.param.maxite

    Max number of kappa-sigma clipping iterations (long; default: 3) [default=3].
.. py:attribute:: visir_util_clip.param.shift_beams

    Account for movements of the object defined in CRPIX[12] (bool;  default: True) [default=True].
.. py:attribute:: visir_util_clip.param.error_source

    Defines the way errors are generated:  img-stdev: stdev of image  timeseries: stdev of each pixel over the time axis of the cube  none:  no error generation (str; default: 'img-stdev') [default="img-stdev"].
.. py:attribute:: visir_util_clip.param.error_out_type

    Output clipped error as error, variance, weight or none (str; default:  'error') [default="error"].
.. py:attribute:: visir_util_clip.param.badimage

    If percentage of clipped pixels above this value the whole image is  considered bad (float; default: 0.2) [default=0.2].


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

::

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

   visir_util_clip.param.keepfrac = 0.9
   visir_util_clip.param.kappa = 5.0
   visir_util_clip.param.maxite = 3
   visir_util_clip.param.shift_beams = True
   visir_util_clip.param.error_source = "img-stdev"
   visir_util_clip.param.error_out_type = "error"
   visir_util_clip.param.badimage = 0.2


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

::

   import cpl
   visir_util_clip = cpl.Recipe("visir_util_clip")
   [...]
   res = visir_util_clip( ..., param = {"keepfrac":0.9, "kappa":5.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 `Lars Lundin <llundin@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 VISIR Instrument Pipeline
Copyright (C) 2011 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., 51 Franklin St, Fifth Floor, Boston, 
MA  02111-1307  USA

.. codeauthor:: Lars Lundin <llundin@eso.org>
