Provided by: cpl-plugin-vimos-doc_3.2.3+dfsg-2build3_all bug

NAME

       vmmosscience - Extraction of scientific spectra

SYNOPSIS

       esorex vmmosscience [OPTIONS] FILE.sof

DESCRIPTION

       This  recipe  is  used  to  reduce  scientific  spectra  using the extraction mask and the
       products created by the recipe vimos_calib. The spectra are bias subtracted, flat  fielded
       (if   a  normalised  flat  field  is  specified)  and  remapped  eliminating  the  optical
       distortions. The wavelength calibration can be optionally upgraded using a number  of  sky
       lines:  if  no  sky  lines  catalog  of  wavelengths is specified, an internal one is used
       instead.

       If the alignment to the sky lines is performed, the input dispersion coefficients table is
       upgraded  and  saved  to  disk,  and a new CCD wavelengths map is created. A configuration
       table (typically depending on the grism in use) may also be specified: this table contains
       a default recipe parameter setting to control the way spectra are extracted for a specific
       instrument mode, as it is used for automatic  run  of  the  pipeline  on  Paranal  and  in
       Garching. If this table is specified, it will modify the default recipe parameter setting,
       with the exception of those parameters which have been explicitly modifyed on the  command
       line.  If  a configuration table is not specified, the input recipe parameters values will
       always be read from the command line, or from an esorex configuration file if present,  or
       from their generic default values (which are rarely meaningful).

       Either a scientific or a standard star exposure can be specified in input.

       Only  in  case  of  a standard star exposure input, the atmospheric extinction table and a
       table with the physical fluxes of the observed standard star must be specified  in  input,
       and  a  spectro-photometric table is created in output. This table can then be input again
       to this recipe, always  with  an  atmospheric  extinction  table,  and  if  a  photometric
       calibration  is  requested then flux calibrated spectra (in units of erg/cm/cm/s/Angstrom)
       are also written in output.

       Input files:

         DO category:                Type:       Explanation:         Required:
         MOS_SCIENCE                 Raw         Scientific exposure     Y
         or MOS_STANDARD             Raw         Standard star exposure  Y

         MASTER_BIAS                 Calib       Master bias             Y
         SKY_LINE_CATALOG            Calib       Sky lines catalog       .

         MOS_MASTER_SCREEN_FLAT      Calib       Normalised flat field   .

         MOS_DISP_COEFF              Calib       Inverse dispersion      Y
         MOS_CURV_COEFF              Calib       Spectral curvature      Y
         MOS_SLIT_LOCATION           Calib       Slits positions table   Y
         CONFIG_TABLE                Calib       Configuration table     .

         In case MOS_STANDARD is specified in input,

         EXTINCT_TABLE               Calib       Atmospheric extinction  Y
         STD_FLUX_TABLE              Calib       Standard star flux      Y
         TELLURIC_CONTAMINATION      Calib       Telluric regions list    .

         In case a photometric calibration is requested for scientific
         data, the following inputs are mandatory:

         EXTINCT_TABLE              Calib       Atmospheric extinction  Y
         MOS_SPECPHOT_TABLE         Calib       Response curves         Y

         If requested for standard star data, the SPECPHOT_TABLE can be dropped:
         in this case the correction is applied using the SPECPHOT_TABLE produced
         in the same run.

       Output files (acronym _STD_ replaces _SCI_ and _STANDARD_ replaces _SCIENCE_ in case input
       is MOS_STANDARD rather than MOS_SCIENCE):

         DO category:                Data type:  Explanation:
         MOS_SCIENCE_REDUCED           Image  Extracted scientific spectra
         MOS_SCI_SKY_REDUCED           Image  Extracted sky spectra
         MOS_SCI_ERROR_REDUCED         Image  Errors on extracted spectra
         MOS_UNMAPPED_SCIENCE          Image  Sky subtracted scientific spectra
         MOS_SCIENCE_EXTRACTED         Image  Rectified scientific spectra
         MOS_SCIENCE_SKY_EXTRACTED     Image  Rectified science spectra with sky
         MOS_SCIENCE_SKY               Image  Rectified sky spectra
         MOS_SCI_UNMAPPED_SKY          Image  Sky on CCD
         MOS_SCI_GLOBAL_SKY_SPECTRUM   Table  Global sky spectrum
         OBJECT_SCI_TABLE              Table  Positions of detected objects

         Only if fringing correction is requested (dithered exposures):
         MOS_SCI_FRINGES               Image  Fringe map

         Only if the sky-alignment of the wavelength solution is requested:
         MOS_SCI_SKYLINES_OFFSETS_SLIT Table  Sky lines offsets
         MOS_SCI_DISP_COEFF_SKY        Table  Upgraded dispersion coefficients
         MOS_SCI_WAVELENGTH_MAP_SKY    Image  Upgraded wavelength map

         Only if a MOS_STANDARD is specified in input:
         MOS_SPECPHOT_TABLE            Table  Efficiency and response curves

         Only if MOS_SPECPHOT_TABLE or MOS_MASTER_RESPONSE are specified in input:
         MOS_SCIENCE_FLUX_REDUCED      Image  Flux calibrated scientific spectra
         MOS_SCI_ERROR_FLUX_REDUCED    Image  Errors on flux calibrated spectra
         MOS_SCIENCE_FLUX_EXTRACTED    Image  Flux calibrated slit spectra

OPTIONS

       --skyalign <int>
              Polynomial  order  for sky lines alignment, or -1 to avoid alignment (int; default:
              -1).  The  full  name  of  this  option  for  the  EsoRex  configuration  file   is
              vimos.vmmosscience.skyalign [default = -1].

       --flatfield <bool>
              Apply flat field (bool; default: True). The full name of this option for the EsoRex
              configuration file is vimos.vmmosscience.flatfield [default = True].

       --skyglobal <bool>
              Subtract global sky spectrum from CCD (bool; default: False). The full name of this
              option for the EsoRex configuration file is vimos.vmmosscience.skyglobal [default =
              False].

       --skymedian <bool>
              Sky subtraction from extracted slit spectra (bool; default: False). The  full  name
              of  this  option  for the EsoRex configuration file is vimos.vmmosscience.skymedian
              [default = False].

       --skylocal <bool>
              Sky subtraction from CCD slit spectra (bool; default: True). The full name of  this
              option  for the EsoRex configuration file is vimos.vmmosscience.skylocal [default =
              True].

       --cosmics <bool>
              Eliminate cosmic rays hits (only  if  global  or  local  sky  subtraction  is  also
              requested)  (bool;  default:  True).  The  full  name of this option for the EsoRex
              configuration file is vimos.vmmosscience.cosmics [default = True].

       --slit_margin <int>
              Number of pixels to exclude at each slit in object detection and  extraction  (int;
              default:  3).  The  full  name  of this option for the EsoRex configuration file is
              vimos.vmmosscience.slit_margin [default = 3].

       --ext_radius <int>
              Maximum extraction radius for detected objects (pixel) (int; default: 6). The  full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              vimos.vmmosscience.ext_radius [default = 6].

       --cont_radius <int>
              Minimum distance at which two objects of equal luminosity do not  contaminate  each
              other  (pixel)  (int;  default:  0).  The  full  name of this option for the EsoRex
              configuration file is vimos.vmmosscience.cont_radius [default = 0].

       --ext_mode <int>
              Object extraction method: 0 = aperture, 1 = Horne optimal extraction (int; default:
              1).   The   full  name  of  this  option  for  the  EsoRex  configuration  file  is
              vimos.vmmosscience.ext_mode [default = 1].

       --detection <float>
              Object detection threshold (ADU) (float; default:  2.0).  The  full  name  of  this
              option for the EsoRex configuration file is vimos.vmmosscience.detection [default =
              2.0].

       --resp_fit_nknots <int>
              Number of knots in spline fitting of the instrument response. (-1: No fitting.  -2:
              Read  from  grism  table)  (int; default: -2). The full name of this option for the
              EsoRex configuration file is vimos.vmmosscience.resp_fit_nknots [default = -2].

       --resp_fit_degree <int>
              Degree of polynomial in fitting of the instrument response. (-1:  No  fitting.  -2:
              Read  from  grism  table)  (int; default: -2). The full name of this option for the
              EsoRex configuration file is vimos.vmmosscience.resp_fit_degree [default = -2].

       --resp_ignore_mode <str>
              Types of lines/regions to ignore in response. Valid ones are  ´stellar_absorption´,
              ´telluric´  and  ´command_line´  (from  parameter resp_ignore_lines) (str; default:
              ´stellar_absorption,telluric,command_line´). The full name of this option  for  the
              EsoRex   configuration   file  is  vimos.vmmosscience.resp_ignore_mode  [default  =
              stellar_absorption,telluric,command_line].

       --resp_ignore_points <str>
              Extra lines/regions to ignore in response. Use a comma separated list of values.  A
              range can be specified like 4500.0-4600.0 (str; default: ´´). The full name of this
              option for the EsoRex configuration file  is  vimos.vmmosscience.resp_ignore_points
              [default = ].

       --resp_use_flat_sed <str>
              Use  the  flat  SED  to  normalise  the  observed  spectra.  Value are true, false,
              grism_table. (str; default: ´grism_table´). The full name of this  option  for  the
              EsoRex   configuration  file  is  vimos.vmmosscience.resp_use_flat_sed  [default  =
              grism_table].

       --resp_shift <float>
              The extracted standard star will be shifted these many angstroms before using it to
              compute  the  response.  This  is useful for observed std stars not centered in the
              slits. Positive values will shift the spectrum  to  the  red.  Shift  is  given  in
              Angstroms  but  no  fraction  of pixels will be shifted. (float; default: 0.0). The
              full   name   of   this   option   for   the   EsoRex   configuration    file    is
              vimos.vmmosscience.resp_shift [default = 0.0].

       --time_normalise <bool>
              Normalise  output spectra by the exposure time (bool; default: True). The full name
              of     this     option     for     the     EsoRex     configuration     file     is
              vimos.vmmosscience.time_normalise [default = True].

       --anyframe <bool>
              Look  for  a  standard star in any frame classified as MOS_STANDARD (bool; default:
              False). The full  name  of  this  option  for  the  EsoRex  configuration  file  is
              vimos.vmmosscience.anyframe [default = False].

       --alignment <str>
              Type  of  alignment of dithered frames, either to the nearest neighbour pixel or to
              fractions of pixel (str; default: ´integer´). The full name of this option for  the
              EsoRex configuration file is vimos.vmmosscience.alignment [default = integer].

       --stack_method <str>
              Frames  combination  method (str; default: ´average´). The full name of this option
              for the EsoRex configuration file  is  vimos.vmmosscience.stack_method  [default  =
              average].

       --minrejection <int>
              Number  of  lowest  values  to be rejected (int; default: 1). The full name of this
              option  for  the  EsoRex  configuration  file  is   vimos.vmmosscience.minrejection
              [default = 1].

       --maxrejection <int>
              Number  of  highest  values to be rejected (int; default: 1). The full name of this
              option  for  the  EsoRex  configuration  file  is   vimos.vmmosscience.maxrejection
              [default = 1].

       --klow <float>
              Low  threshold in ksigma method (float; default: 3.0). The full name of this option
              for the EsoRex configuration file is vimos.vmmosscience.klow [default = 3.0].

       --khigh <float>
              High threshold in ksigma method (float; default: 3.0). The full name of this option
              for the EsoRex configuration file is vimos.vmmosscience.khigh [default = 3.0].

       --kiter <int>
              Max  number  of  iterations  in ksigma method (int; default: 999). The full name of
              this option for the EsoRex configuration file is vimos.vmmosscience.kiter  [default
              = 999].

       --dither <bool>
              Align  dithered  frames  before stacking(for multiple input frames) (bool; default:
              True). The  full  name  of  this  option  for  the  EsoRex  configuration  file  is
              vimos.vmmosscience.dither [default = True].

       --compute <bool>
              Compute  offsets  of  dithered images from detected objects (true), or read offsets
              from header (false) (bool; default: False). The full name of this  option  for  the
              EsoRex configuration file is vimos.vmmosscience.dither.compute [default = False].

       --fringing <bool>
              Apply  fringing  correction (only for dithered observations) (bool; default: True).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              vimos.vmmosscience.fringing [default = True].

       --offset <float>
              Minimum required offset between exposures for applying the sky fringing correction.
              (float; default: 3.0). The full name of this option for  the  EsoRex  configuration
              file is vimos.vmmosscience.fringing.offset [default = 3.0].

       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 vimos pipeline can be downloaded as a PDF file using the
       following URL:

              ftp://ftp.eso.org/pub/dfs/pipelines/vimos/vimos-pipeline-manual-6.9.pdf

       An  overview  over  the  existing  ESO  pipelines  can  be   found   on   the   web   page
       https://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
       https://packages.python.org/python-cpl/index.html for further information.

       The other recipes of the vimos pipeline are vmbias(7), vmdark(7), vmdet(7), vmifucalib(7),
       vmifucombine(7),  vmifucombinecube(7),  vmifuscience(7), vmifustandard(7), vmimcalphot(7),
       vmimflatscreen(7), vmimflatsky(7), vmimobsjitter(7),  vmimobsstare(7),  vmimpreimaging(7),
       vmimstandard(7),   vmmoscalib(7),  vmmoscombine(7),  vmmosobsjitter(7),  vmmosobsstare(7),
       vmmosstandard(7), vmspcaldisp(7), vmspflat(7), vmspphot(7)

VERSION

       vmmosscience 3.2.3

AUTHOR

       Carlo Izzo <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  currently  part  of  the VIMOS Instrument Pipeline Copyright (C) 2002-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  02110-1301  USA