Name
       deadpix - bad pixel map handling

Synopsis
       deadpix [parameters]

Description
       deadpix  is  a tool to generate bad pixel maps from images
       of the sky background in infrared. It can also be used  to
       remove  bad  pixel  contributions in a frame by applying a
       bad pixel map on it.

       Methods offered by this tool for bad pixel  detection  are
       not  the best ones, statistical studies of a twilight data
       set usually brings a more reliable information about pixel
       quality  (see  flat  command).  However, these methods are
       still of some use when no other  data  are  available  for
       calibration.

       The  skyvar method needs a sky cube, preferrably with many
       planes (>20) to observe meaningful statistical behaviours.

       The  median method detects spikes in an image, it needs in
       input a small number (<10) of flat frames.

       The cleaning algorithm only requires a valid pixel map and
       a cube to clean out.

Detection Algorithms
       Two  methods are implemented for bad pixel detection. They
       both make use of sky images.

       First method : sky variations statistics (skyvar method)

       Let's compute for each pixel its standard deviation  along
       time.   If  we  plot  a histogram of these standard devia-
       tions, we see a gaussian-shaped function  that  represents
       the  response  to  the sky signal. We decide to throw away
       all pixels which response is too low (dead)  or  too  high
       (noisy)  by  rejecting  all  pixels  out  of a central +/-
       sigma_width/2  interval   on   the   histogram.    Default
       sigma_width is 3, it can be changed by feeding a new sigma
       width through the -s option.

       example:
       > deadpix -d --skyvar --sigma 4 --sky skycube.fits

       Second method : median filter detection (median method)

       This method does not make use of temporal information,  by
       merely  observes  each  image  independently. If we assume
       that the signal is smooth enough, bad  pixels  are  spikes
       easily found by computing the difference between the image
       and its median filtered version, and thresholding it.  All
       spikes  are  then detected. This is not as strong as using
       the temporal information, but this is the  only  way  when
       not enough images are present.  Default threshold is fixed
       to 10.0, it can be changed by using the  -m  option.  This
       threshold is given directly in pixel values.

       example:
       > deadpix -d --median --threshold 15 --sky skyplanes.fits

Cleaning Algorithm
       The algorithm used to clean out a plane from bad pixels is
       simple. It just replaces bad pixel positions by an average
       of the valid pixels out of the 8 closest neighbours. If no
       value is available, the pixel is set to null.

       example:
       > deadpix --clean --in toclean.fits --pixmap badpixmap

Parameters
       First, choose between dead pixel detection and dead  pixel
       cleaning   mode.    This  is  done  by  activating  either
       --detect/-d or --clean/-c command-line options.

       Detection mode: --detect or -d

       --skyvar or -m skyvar
              This forces the use of the sky variation method for
              bad pixel detection.  An expected parameter is then
              --sigma.

       --sigma value or -s value
              This specifies the  sigma  threshold  for  the  sky
              variation method. Default value is 3.0.

       --median or -m median
              This  forces  the  use of the median method for bad
              pixel detection.  An  expected  parameter  is  then
              --threshold.

       --threshold thr or -t thr
              This  specifies the median threshold for the median
              method. Default value is thr=10.

       --sky name or -S name
              Specifies the name of the file which  contains  the
              sky  planes  to  work  with.  This  is used by both
              detection methods.

       Cleaning mode: --clean or -c

       --in name or -i name
              Specifies the name of the input file to clean  out.

       --out name or -o name
              Specifies  the  name  of the output file to create.
              This is optional, default naming scheme  for  input
              files named *.fits is *.cln.fits.

       Parameters common to both modes

       --pixmap name or -p name
              This  specifies  the name of a pixel map. In detec-
              tion mode, this is an output since the goal of  the
              detection  is to produce a bad pixel map. In clean-
              ing mode, this is an input which is used  to  clean
              out other files.

Files
       Input files shall all comply with FITS format.  Pixel maps
       are in 8 bit FITS format.

       In a bad pixel map, good pixels are set to 1,  bad  pixels
       are set to 0. This can also be found in bad pixel map FITS
       headers, where the following keywords are written:

       GOODPIX = 1
       BADPIX  = 0

Notice
       Pixel maps are in 8 bits signed FITS format. They  can  be
       easily viewed that way.

See Also
       flat

Author
       Nicolas Devillard, European Southern Observatory.
       Part of eclipse Library