Provided by: cpl-plugin-visir-doc_4.4.2+dfsg-1_all bug

NAME

       visir_old_spc_obs_ech - Old DRS detector: Spectroscopic Observation recipe in Echelle mode

SYNOPSIS

       esorex visir_old_spc_obs_ech [OPTIONS] FILE.sof

DESCRIPTION

       This  recipe  estimates  the dispersion relation using the atmospheric spectrum in a grism
       spectroscopy half-cycle frame.

       It also extracts the spectrum of an observed object using a combined frame.

       The   files   listed   in   the   Set   Of   Frames    (sof-file)    must    be    tagged:
       VISIR-Echelle-Spectroscopy-file.fits                                          SPEC_OBS_HRG
       VISIR-Quantum-Efficiency-Calibration-file.fits                               SPEC_CAL_QEFF
       VISIR-Atmospheric-Emission-Lines-Calibration-file.fits SPEC_CAL_LINES

       Additionally,  a  bad  pixel  map  with  a PRO.CATG of SPEC_BPM may be added to the Set Of
       Frames with tag: BPM.

OPTIONS

       --nod <str>
              An optional ASCII specification of the nodding positions (in case they are  missing
              from the FITS-file). The file must consist of one line per input FITS-file and each
              line must consist of an integer (which is  ignored)  followed  by  a  0  or  1  (to
              indicate  object or sky).  (str; default: ´NONE´). The full name of this option for
              the EsoRex configuration file  is  visir.visir_old_spc_obs_ech.nodding  [default  =
              NONE].

       --auto_bpm <bool>
              Automatic  detection  and  correction of bad pixels (bool; default: True). The full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              visir.visir_old_spc_obs_ech.auto_bpm [default = True].

       --g <bool>
              Automatic  filtering  of  glitches  (bool;  default:  False). The full name of this
              option for the EsoRex configuration file is  visir.visir_old_spc_obs_ech.rem_glitch
              [default = False].

       --p <bool>
              Automatic  purging  of  half-cycle  images whose median deviates more than a factor
              three from the mean of the medians of half-cycle images or whose standard deviation
              deviates more than a factor three from the mean of their standard deviations (bool;
              default: False). The full name of this option for the EsoRex configuration file  is
              visir.visir_old_spc_obs_ech.purge_bad [default = False].

       --union <bool>
              Combine  images using their union, as opposed to their intersection (deprecated and
              ignored, see --combine_method) (bool; default: True). The full name of this  option
              for  the  EsoRex configuration file is visir.visir_old_spc_obs_ech.union [default =
              True].

       --rej <str>
              Each resulting pixel is the average of the corresponding (interpolated) pixel value
              in  each  jittered  image.  A positive value, n1, for the first of the two integers
              specifies that for each pixel the smallest n1 pixel values shall be ignored in  the
              averaging.   Similarly,  a  positive  value, n2, for the second of the two integers
              specifies that for each pixel the largest n2 pixel values shall be ignored  in  the
              averaging.  (str;  default:  ´0-0´).  The  full  name of this option for the EsoRex
              configuration file is visir.visir_old_spc_obs_ech.rej [default = 0-0].

       --bkgcorrect <bool>
              Subtract the median from the spectral column before extracting the wavelength. This
              is  required when the skylines do not correctly cancel due to gratting oscillations
              (bool; default: True). The full name of this option for  the  EsoRex  configuration
              file is visir.visir_old_spc_obs_ech.bkgcorrect [default = True].

       --plot <int>
              The  recipe  can  produce a number of predefined plots. Zero means that none of the
              plots are produced, while increasing values (e.g. 1 or 2) increases the  number  of
              plots  produced.  If  the  plotting  fails  a  warning  is produced, and the recipe
              continues. The default behaviour of the plotting is to  use  gnuplot  (with  option
              -persist).  The  recipe  currently  produces  1D-plots  using gnuplot commands. The
              recipe user can control the actual plotting-command used by the  recipe  to  create
              the plot by setting the environment variable CPL_PLOTTER. Currently, if CPL_PLOTTER
              is  set  it  must  contain  the  string   ´gnuplot´.   Setting   it   to   ´cat   >
              my_gnuplot_$$.txt´ causes a number of ASCII-files to be created, which each produce
              a plot when given as standard input to  gnuplot  (e.g.  later  or  on  a  different
              computer).  A  finer  control of the plotting options can be obtained by writing an
              executable script, e.g. my_gnuplot.pl, that  executes  gnuplot  after  setting  the
              desired  gnuplot  options  (e.g.  set  terminal  pslatex  color)  and  then setting
              CPL_PLOTTER to my_gnuplot.pl. The predefined  plots  include  plotting  of  images.
              Images can be plotted not only with gnuplot, but also using the pnm format. This is
              controlled with the environment variable CPL_IMAGER. If  CPL_IMAGER  is  set  to  a
              string that does not contain the word gnuplot, the recipe will generate the plot in
              pnm format. E.g.  setting CPL_IMAGER to ´display - &´  will  produce  a  gray-scale
              image  using  the  image  viewer  display. (int; default: 0). The full name of this
              option  for  the  EsoRex  configuration  file  is  visir.visir_old_spc_obs_ech.plot
              [default = 0].

       --slit_skew <float>
              Distortion  correction:  Skew  of slit (degrees) (clockwise) (float; default: 0.0).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              visir.visir_old_spc_obs_ech.phi [default = 0.0].

       --spectrum_skew <float>
              Distortion  correction:  LMR  Skew  of spectrum (degrees) (counter- clockwise). Not
              used in High Resolution (float; default: 0.0). The full name of this option for the
              EsoRex configuration file is visir.visir_old_spc_obs_ech.ksi [default = 0.0].

       --vert_arc <float>
              Distortion  correction: LR Detector vertical curvature (pixel). Reduced by a factor
              4 in MR. Not used in HR A-side. Increased by a factor 115/52 in HR  B-side  (float;
              default:  0.0).  The  full name of this option for the EsoRex configuration file is
              visir.visir_old_spc_obs_ech.eps [default = 0.0].

       --hori_arc <float>
              Distortion correction: LMR Detector horizontal curvature (pixel).  Increased  by  a
              factor  1.5 in HR A-side. Reduced by a factor 2 in HR B-side (float; default: 0.0).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              visir.visir_old_spc_obs_ech.delta [default = 0.0].

       --orderoffset <int>
              Echelle  order  offset. The offset is relative to the main order. The allowed range
              of offsets depend on the selected grism. The offset can never exceed +/-4.  If  the
              main  order  is e.g. 8 an order offset of +1 will cause the recipe to base the data
              reduction on order 9. With a positive order offset the central  wavelength  becomes
              smaller  while  for  a negative order offset the central wavelength becomes larger.
              (int; default: 0). The full name of this option for the EsoRex  configuration  file
              is visir.visir_old_spc_obs_ech.orderoffset [default = 0].

       --off <str>
              An  optional  ASCII specification of the offsets in case those in FITS- headers are
              missing or wrong. The file must consist of one line per input pair  of  FITS-files,
              and  each  line  must consist of two numbers which represent the shift in pixels of
              that image relative to the first image. The first line  should  thus  comprise  two
              zeros.  Correct  FITS-header offsets mean that the i´th X offset can be gotten from
              Xoffset_0 - Xoffset_i, where Xoffset_i is the  value  of  ESO  SEQ  CUMOFFSETX  and
              likewise for Y. (str; default: ´NONE´). The full name of this option for the EsoRex
              configuration file is visir.visir_old_spc_obs_ech.offsets [default = NONE].

       --ref <bool>
              User-defined refining of the image offsets.  See  options  objs  and  xcorr  (bool;
              default:  False). The full name of this option for the EsoRex configuration file is
              visir.visir_old_spc_obs_ech.refine [default = False].

       --objs <str>
              The shift and add of images needs anchor points that typically are bright  objects.
              These are normally detected automatically but with user-defined refining of offsets
              enabled, they must be provided by the user through an  ASCII  file  containing  one
              line  per  anchor  point  with  each  line consisting of its x and y coordinate (in
              pixels). This file is ignored with user-defined refining of offsets disabled. (str;
              default: ´NONE´). The full name of this option for the EsoRex configuration file is
              visir.visir_old_spc_obs_ech.objects [default = NONE].

       --xcorr <str>
              If user-defined refining of offsets is enabled a cross-correlation of the images is
              performed.  In  order to speed up this process, this cross-correlation is performed
              only on smaller rectangles around the anchor points. The first  two  parameters  is
              the  half-size of this rectangle in pixels. The second pair is the maximum shift in
              x and y (pixels) evaluated by the cross-correlation on the rectangle. Used only  if
              user-defined  refining  of  offsets  is enabled. (str; default: ´10-10-25-25´). The
              full   name   of   this   option   for   the   EsoRex   configuration    file    is
              visir.visir_old_spc_obs_ech.xcorr [default = 10-10-25-25].

       --fixcombi <bool>
              Perform  the  distortion  correction  on the combined image, and not on each of the
              jittered images. This will reduce excution time and  degrade  the  quality  of  the
              combined  image (bool; default: False). The full name of this option for the EsoRex
              configuration file is visir.visir_old_spc_obs_ech.fixcombi [default = False].

       --emis_tol <float>
              The computation of the mean and standard deviation of the sensitivity is  done  for
              wavelengths  with  an  atmospheric  emissivity  of  at  most  emis_min + emis_tol *
              (emis_max - emis_min), where emis_min is the minimum  emissivity  in  the  observed
              wavelength  range  and  emis_max is the ditto maximum. Thus emis_tol = 1 means that
              all wavelengths are included. (float; default: 1.0). The full name of  this  option
              for  the EsoRex configuration file is visir.visir_old_spc_obs_ech.emis_tol [default
              = 1.0].

       --destripe_iterations <int>
              Max  number  of  destriping  iterations  (0  to  disable  destriping).   Horizontal
              destriping  is  done  first  and  if  no  horizontal striping is detected, vertical
              destriping is performed (int; default: 15). The full name of this  option  for  the
              EsoRex configuration file is visir.visir_old_spc_obs_ech.nstripe [default = 15].

       --destripe_morpho <bool>
              Destripe  with morphological cleaning (bool; default: False). The full name of this
              option for the EsoRex  configuration  file  is  visir.visir_old_spc_obs_ech.mstripe
              [default = False].

       --rl <int>
              Reject  leftmost columns in spectrum extraction, zero means all columns on the left
              are used. In cross-dispersion mode a (small) negative number may  be  used  (pixel)
              (int;  default:  0). The full name of this option for the EsoRex configuration file
              is visir.visir_old_spc_obs_ech.reject_left [default = 0].

       --rr <int>
              Reject rightmost columns in spectrum extraction, zero  means  all  columns  on  the
              right  are  used.  In  cross-dispersion  mode a (small) negative number may be used
              (pixel)  (int;  default:  0).  The  full  name  of  this  option  for  the   EsoRex
              configuration file is visir.visir_old_spc_obs_ech.reject_right [default = 0].

       --ro_noise <float>
              Readout  noise of the detector (float; default: 14.5). The full name of this option
              for the EsoRex configuration file  is  visir.visir_old_spc_obs_ech.ron  [default  =
              14.5].

       --ox_sigma <float>
              Sigma  to  use  for  clipping in optimal extraction (float; default: 5.0). The full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              visir.visir_old_spc_obs_ech.optex_sigma [default = 5.0].

       --ox_niters <int>
              Number of optimal extraction iterations to perform (int; default: 2). The full name
              of     this     option     for     the     EsoRex     configuration     file     is
              visir.visir_old_spc_obs_ech.optex_niters [default = 2].

       --ox_smooth <int>
              Width   of  smoothing  window  to  use  along  spectral  dimension  during  optimal
              extraction. A median filter is used. (int; default: 31).  The  full  name  of  this
              option        for        the        EsoRex        configuration       file       is
              visir.visir_old_spc_obs_ech.optex_smooth [default = 31].

       --gain <float>
              Detector gain (float; default: 0.75). The full name of this option for  the  EsoRex
              configuration file is visir.visir_old_spc_obs_ech.gain [default = 0.75].

       --ox_kernel <int>
              Size  of  square  smoothing  kernel,  in  pixels,  to apply to science frame before
              optimal extraction (ignored during aperture extraction). A median filter  is  used.
              (int;  default:  3). The full name of this option for the EsoRex configuration file
              is visir.visir_old_spc_obs_ech.optex_kernel [default = 3].

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

              ftp://ftp.eso.org/pub/dfs/pipelines/visir/visir-pipeline-manual-1.4.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  visir  pipeline  are  visir_img_dark(7),  visir_img_ff(7),
       visir_img_reduce(7), visir_img_trans(7), visir_old_img_combine(7),  visir_old_img_phot(7),
       visir_old_spc_obs(7),           visir_old_spc_phot(7),          visir_old_spc_phot_ech(7),
       visir_old_spc_wcal(7),       visir_old_spc_wcal_ech(7),        visir_old_util_destripe(7),
       visir_spc_reduce(7),             visir_util_apply_calib(7),            visir_util_clip(7),
       visir_util_convert_weight(7),    visir_util_detect_shift(7),    visir_util_img_std_cat(7),
       visir_util_join(7),   visir_util_qc(7),   visir_util_repack(7),   visir_util_run_swarp(7),
       visir_util_spc_std_cat(7), visir_util_spc_txt2fits(7), visir_util_undistort(7)

VERSION

       visir_old_spc_obs_ech 4.4.2

AUTHOR

       Lars Lundin <https://support.eso.org>

BUG REPORTS

       Please report any problems to  https://support.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  VISIR Instrument Pipeline Copyright (C) 2004, 2005 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