Provided by: cpl-plugin-kmos-doc_1.4.3+dfsg-1_all bug

NAME

       kmos_combine - Combine reconstructed cubes

SYNOPSIS

       esorex kmos_combine [OPTIONS] FILE.sof

DESCRIPTION

       This  recipe  shifts several exposures of an object and combines them. Diffe- rent methods
       to match the exposures are described here (--method parameter).

       The output cube is larger than the input cubes, according to the  shifts  to  be  applied.
       Additionally  a  border  of  NaN  values  is  added.  The WCS is the same as for the first
       exposure.

       For each spatial/spectral pixel  a  new  value  is  calculated  (according  the  --cmethod
       parameter) and written into the output cube.

       Only  exposures  with  the  same WCS orientation can be combined (except -–method=”none”),
       north must point to the same direction. It is recommended to apply any  rotation  possibly
       after combining.

       The  behavior  of  the  selection of IFUs to combine differs for some templates and can be
       controlled with the parameters --name and --ifus.

       If   the   input   data   cubes   stem   from    templates    KMOS_spec_obs_mapping8    or
       KMOS_spec_obs_mapping24  all  extensions  from all input frames are combined into a single
       map by default (like in recipe kmo_sci_red). If just the area of a specific IFU should  be
       combined, the parameter --ifus can be specified, or more easily --name.

       If the input data cubes stem from other templates like e.g.

       KMOS_spec_obs_freedither  all  extensions  of  all  input frames are combined into several
       output frames by default. The input IFUs are grouped according to  their  targeted  object
       name  stored  in  the  keywords  ESO  OCS  ARMx  NAME. If just a specific object should be
       combined, its name can be specified with --name. If arbitrary IFUs shoukd be comined,  one
       can specify these with the parameter --ifus.

       The  default  mapping  mode is done via the --name parameter, where the name of the object
       has to be provided. The recipe searches in input data cubes IFUs pointing to that object.

         Input files:

          DO                  KMOS
          category            Type   Explanation                  Required #Frames
          --------            -----  -----------                  -------- -------
          CUBE_OBJECT         F3I    data frame                       Y      2-n

         Output files:

          DO                      KMOS
          category                Type    Explanation
          --------                -----   -----------
          COMBINE_                F3I     Combined data cube
          EXP_MASK                F3I     Exposure time mask
          SCI_COMBINED_COLL               (optional) Collapsed combined cube
                                          (set --collapse_combined)

OPTIONS

       --name <str>
              Name of the object to combine. (str; default: ´´). The full name of this option for
              the EsoRex configuration file is kmos.kmos_combine.name [default = ].

       --ifus <str>
              The  indices  of  the IFUs to combine. "ifu1;ifu2;..." (str; default: ´´). The full
              name of this option for the EsoRex  configuration  file  is  kmos.kmos_combine.ifus
              [default = ].

       --method <str>
              The  shifting  method:    ´none´:  no  shifting, combined directly, ´header´: shift
              according to WCS (default), ´center´: centering algorithm, ´user´: read shifts from
              file  (str;  default:  ´none´).  The  full  name  of  this  option  for  the EsoRex
              configuration file is kmos.kmos_combine.method [default = none].

       --fmethod <str>
              The fitting method (applies only when  method=´center´):    ´gauss´:  fit  a  gauss
              function to collapsed image (default), ´moffat´: fit a moffat function to collapsed
              image (str; default: ´gauss´).  The  full  name  of  this  option  for  the  EsoRex
              configuration file is kmos.kmos_combine.fmethod [default = gauss].

       --filename <str>
              The path to the file with the shift vectors (method=´user´) (str; default: ´´). The
              full   name   of   this   option   for   the   EsoRex   configuration    file    is
              kmos.kmos_combine.filename [default = ].

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

       --edge_nan <bool>
              Set  borders  of  cubes  to NaN before combining them.(TRUE (apply) or FALSE (don´t
              apply) (bool; default: False).  The  full  name  of  this  option  for  the  EsoRex
              configuration file is kmos.kmos_combine.edge_nan [default = False].

       --skipped_frames <str>
              Comma  separated List of IFUs to skip for the combination. An IFU is specified with
              R:I.R is the index (start 1) of the recons. frame, I the IFU nb (str; default: ´´).
              The   full   name   of   this   option   for   the  EsoRex  configuration  file  is
              kmos.kmos_combine.skipped_frames [default = ].

       --suppress_extension <bool>
              Suppress arbitrary filename extension. (bool; default: False).  The  full  name  of
              this      option      for      the      EsoRex      configuration      file      is
              kmos.kmos_combine.suppress_extension [default = False].

       --collapse_combined <bool>
              Flag to collapse the combined images (bool; default: False). The full name of  this
              option  for  the  EsoRex  configuration file is kmos.kmos_combine.collapse_combined
              [default = False].

       --cmethod <str>
              Apply "average", "median", "sum", "min_max." or "ksigma". (str; default: ´ksigma´).
              The   full   name   of   this   option   for   the  EsoRex  configuration  file  is
              kmos.kmos_combine.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.kmos_combine.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.kmos_combine.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.kmos_combine.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.kmos_combine.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.kmos_combine.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_arithmetic(7),  kmo_copy(7),
       kmo_fit_profile(7), kmo_fits_strip(7), kmo_make_image(7), kmo_noise_map(7), kmo_rotate(7),
       kmo_shift(7),    kmo_sky_mask(7),    kmo_stats(7),   kmos_dark(7),   kmos_extract_spec(7),
       kmos_flat(7),    kmos_gen_reflines(7),     kmos_gen_telluric(7),     kmos_illumination(7),
       kmos_reconstruct(7),  kmos_sci_red(7),  kmos_sky_tweak(7), kmos_std_star(7), kmos_test(7),
       kmos_wave_cal(7)

VERSION

       kmos_combine 1.4.3

AUTHOR

       Alex Agudo Berbel, Y. Jung <usd-help@eso.org>

BUG REPORTS

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

LICENSE

       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