Provided by: cpl-plugin-kmos-doc_1.2.8+dfsg-2_all bug

NAME

       kmo_illumination_flat - Alternative to kmo_illumination based on flatfield frames.

SYNOPSIS

       esorex kmo_illumination_flat [OPTIONS] FILE.sof

DESCRIPTION

       This  recipe  creates  the  spatial  non-uniformity calibration frame needed for all three
       detectors. It must be called after the kmo_wave_cal-recipe, which generates  the  spectral
       calibration frame needed in this recipe. As input at least a flatfield frame is required.

       Contrary  to  kmo_illumination  it  doesn´t  use  flat sky frames but rather the flatfield
       frames from the internal flat lamp. This recipe can be used  if  no  acceptable  flat  sky
       frames are available.

       The  created  product,  the illumination correction, can be used as input for kmo_std_star
       and kmo_sci_red.

   BASIC PARAMETERS
       --imethod The interpolation method used for reconstruction.

   ADVANCED PARAMETERS
       --flux Specify if flux conservation should be applied.

       --neighborhoodRange Defines the range to search for neighbors during reconstruction

       --b_samples The number of samples in spectral direction for the reconstructed cube.

       Ideally this number should be greater than 2048, the detector size.

       --b_start  --b_end  Used  to  define  manually  the  start  and  end  wavelength  for  the
       reconstructed cube. By default the internally defined values are used.

       --cmethod Following methods of frame combination are available:
          * ´ksigma´ (Default)
          An iterative sigma clipping. For each position all pixels in the spectrum
          are examined. If they deviate significantly, they will be rejected according
          to the conditions:
              val > mean + stdev * cpos_rej
          and
              val < mean - stdev * cneg_rej
          where --cpos_rej, --cneg_rej and --citer are the corresponding configuration
          parameters. In the first iteration median and percentile level are used.

          * ´median´
          At each pixel position the median is calculated.

          * ´average´
          At each pixel position the average is calculated.

          * ´sum´
          At each pixel position the sum is calculated.

          * ´min_max´
          The specified number of minimum and maximum pixel values will be rejected.

          --cmax and --cmin apply to this method.

       --cpos_rej --cneg_rej --citer see --cmethod=´ksigma´

       --cmax --cmin see --cmethod=´min_max´

       --pix_scale  Change  the  pixel  scale  [arcsec].  Default  of  0.2" results into cubes of
       14x14pix, a scale of 0.1" results into cubes of 28x28pix, etc.

       --suppress_extension If set to TRUE, the arbitrary filename extensions are  supressed.  If
       multiple  products with the same category are produced, they will be numered consecutively
       starting from 0.

         Input files:

          DO                    KMOS
          category              Type   Explanation                    Required #Frames
          --------              -----  -----------                    -------- -------
          FLAT_SKY_FLAT          F2D   Flatlamp-on exposures             Y      1-n
                                       (at least 3 frames recommended)
          XCAL                   F2D   x calibration frame               Y       1
          YCAL                   F2D   y calibration frame               Y       1
          LCAL                   F2D   Wavelength calib. frame           Y       1
          WAVE_BAND              F2L   Table with start-/end-wavelengths Y       1

         Output files:

          DO                    KMOS
          category              Type   Explanation
          --------              -----  -----------
          ILLUM_CORR             F2I    Illumination calibration frame

OPTIONS

       --imethod <str>
              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´). The full name of this
              option  for  the  EsoRex  configuration  file is kmos.kmo_illumination_flat.imethod
              [default = CS].

       --neighborhoodRange <float>
              Defines the range to search for neighbors. in pixels (float; default:  1.001).  The
              full    name    of   this   option   for   the   EsoRex   configuration   file   is
              kmos.kmo_illumination_flat.neighborhoodRange [default = 1.001].

       --flux <bool>
              TRUE: Apply flux conservation. FALSE: otherwise (bool; default:  False).  The  full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              kmos.kmo_illumination_flat.flux [default = False].

       --pix_scale <float>
              Change the pixel scale [arcsec]. Default of 0.2" results into cubes of 14x14pix,  a
              scale  of 0.1" results into cubes of 28x28pix, etc. (float; default: 0.2). The full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              kmos.kmo_illumination_flat.pix_scale [default = 0.2].

       --suppress_extension <bool>
              Suppress  arbitrary filename extension. (TRUE (apply) or FALSE (don´t apply) (bool;
              default: False). The full name of this option for the EsoRex configuration file  is
              kmos.kmo_illumination_flat.suppress_extension [default = False].

       --b_samples <long>
              The  number  of  samples  in  wavelength for the reconstructed cube (long; default:
              2048). The  full  name  of  this  option  for  the  EsoRex  configuration  file  is
              kmos.kmo_illumination_flat.b_samples [default = 2048].

       --b_start <float>
              The  lowest wavelength [um] to take into account when reconstructing (default of -1
              sets the proper value for the actual band automatically)  (float;  default:  -1.0).
              The   full   name   of   this   option   for   the  EsoRex  configuration  file  is
              kmos.kmo_illumination_flat.b_start [default = -1.0].

       --b_end <float>
              The highest wavelength [um] to take into account when reconstructing (default of -1
              sets  the  proper  value for the actual band automatically) (float; default: -1.0).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              kmos.kmo_illumination_flat.b_end [default = -1.0].

       --cmethod <str>
              Either  apply  "average",  "median",  "sum", "min_max." or "ksigma". (str; default:
              ´ksigma´). The full name of this  option  for  the  EsoRex  configuration  file  is
              kmos.kmo_illumination_flat.cmethod [default = ksigma].

       --cpos_rej <float>
              The   positive  rejection  threshold  for  kappa-sigma-clipping  (sigma).   (float;
              default: 3.0). The full name of this option for the EsoRex  configuration  file  is
              kmos.kmo_illumination_flat.cpos_rej [default = 3.0].

       --cneg_rej <float>
              The   negative  rejection  threshold  for  kappa-sigma-clipping  (sigma).   (float;
              default: 3.0). The full name of this option for the EsoRex  configuration  file  is
              kmos.kmo_illumination_flat.cneg_rej [default = 3.0].

       --citer <long>
              The  number  of  iterations  for kappa-sigma-clipping. (long; default: 3). The full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              kmos.kmo_illumination_flat.citer [default = 3].

       --cmax <long>
              The  number of maximum pixel values to clip with min/max-clipping.  (long; default:
              1).  The  full  name  of  this  option  for  the  EsoRex  configuration   file   is
              kmos.kmo_illumination_flat.cmax [default = 1].

       --cmin <long>
              The  number of minimum pixel values to clip with min/max-clipping.  (long; default:
              1).  The  full  name  of  this  option  for  the  EsoRex  configuration   file   is
              kmos.kmo_illumination_flat.cmin [default = 1].

       Note  that  it  is possible to create a configuration file containing these options, along
       with suitable default values. Please refer to the details provided by the 'esorex  --help'
       command.

SEE ALSO

       The  full  documentation  for  the kmos pipeline can be downloaded as a PDF file using the
       following URL:

              ftp://ftp.eso.org/pub/dfs/pipelines/kmos/kmos-pipeline-manual-2.9.pdf

       An  overview  over  the  existing  ESO  pipelines  can  be   found   on   the   web   page
       http://www.eso.org/sci/software/pipelines/.

       Basic documentation about the EsoRex program can be found at the esorex (1) man page.

       It  is  possible  to  call  the  pipelines  from python using the python-cpl package.  See
       http://packages.python.org/python-cpl/index.html for further information.

       The other recipes of the kmos pipeline  are  kmo_dev_setup(7),  kmo_copy(7),  kmo_flat(7),
       kmo_fits_check(7),       kmo_sci_red(7),      kmo_illumination(7),      kmo_fits_stack(7),
       kmo_noise_map(7),    kmo_rotate(7),     kmo_extract_spec(7),     kmo_multi_reconstruct(7),
       kmo_stats(7),     kmo_shift(7),     kmo_wave_cal(7),    kmo_dark(7),    kmo_arithmetic(7),
       kmo_std_star(7), kmo_fits_strip(7), kmo_combine(7),  kmo_make_image(7),  kmo_sky_tweak(7),
       kmo_fit_profile(7), kmo_sky_mask(7), kmo_reconstruct(7)

VERSION

       kmo_illumination_flat 1.2.8

AUTHOR

       Alex Agudo Berbel <kmos-spark@mpe.mpg.de>

BUG REPORTS

       Please  report any problems to kmos-spark@mpe.mpg.de. Alternatively, you may send a report
       to the ESO User Support Department <usd-help@eso.org>.

LICENSE

       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