Provided by: cpl-plugin-muse-doc_2.6.2+dfsg-1_all bug

NAME

       muse_scipost - Prepare reduced and combined science products.

SYNOPSIS

       esorex muse_scipost [OPTIONS] FILE.sof

DESCRIPTION

       Sort input pixel tables into lists of files per exposure, merge pixel tables from all IFUs
       of each exposure. Correct each exposure for differential  atmospheric  refraction  (unless
       --lambdaref  is  far  outside  the  MUSE  wavelength  range). Then the flux calibration is
       carried out, if a response curve was given in the  input;  it  includes  a  correction  of
       telluric  absorption,  if a telluric absorption correction file was given. Next, the slice
       autocalibration is computed and the flux correction factors are applied to the pixel table
       (if    --autocalib="deepfield").    If    user-provided   autocalibration   is   requested
       (--autocalib="user"), then the autocalibration is not computed on the input  exposure  but
       the  autocalibration  factors are read from the AUTOCAL_FACTORS table and applied directly
       to the data. If observations were done with  AO  and  a  RAMAN_LINES  file  was  given,  a
       procedure  is run to clean the Raman scattering emission lines from the data. Then the sky
       subtraction is carried out (unless --skymethod="none"),  either  directly  subtracting  an
       input sky continuum and an input sky emission lines (for --skymethod="subtract-model"), or
       (--skymethod="model")   create   a   sky    spectrum    from    the    darkest    fraction
       (--skymodel_fraction,  after  ignoring  the  lowest --skymodel_ignore as artifacts) of the
       field of view, then fitting and subtracting sky emission lines using an  initial  estimate
       of the input sky lines; then the continuum (residuals after subtracting the sky lines from
       the sky spectrum) is subtracted as well. If --save contains  "skymodel",  all  sky-related
       products  are  saved  for  each  exposure. Afterwards the data is corrected for the radial
       velocity of the observer (--rvcorr), before the input (or a default) astrometric  solution
       is  applied. Now each individual exposure is fully reduced; the pixel tables at this stage
       can be saved by setting "individual" in --save. If multiple exposures were given, they are
       then  combined.  If  --save  contains  "combined", this final merged pixel table is saved.
       Finally (if --save contains "cube"), the data is resampled  into  a  datacube,  using  all
       parameters  given  to  the  recipe.  The  extent  and  orientation of the cube is normally
       computed from the data itself, but this can be overridden  by  passing  a  file  with  the
       output  world  coordinate  system  (OUTPUT_WCS), for example a MUSE cube. This can also be
       used to sample the wavelength axis logarithmically (in that file set "CTYPE3=´AWAV-LOG´").
       As a last step, the computed cube is integrated over all filter functions given (--filter)
       that are also present in the input filter list table.

OPTIONS

       --save <str>
              Select output product(s) to save. Can contain one or  more  of  "cube",  "autocal",
              "skymodel",  "individual",  "positioned",  "combined",  and  "stacked".  If several
              options are given, they have to be  comma-  separated.  ("cube":  output  cube  and
              associated  images,  if  this  is  not given, no final resampling is done at all --
              "autocal":  up  to  two  additional  output   products   related   to   the   slice
              autocalibration  --  "raman": up to four additional output products about the Raman
              light distribution for AO observations -- "skymodel": up to four additional  output
              products about the effectively used sky that was subtracted with the "model" method
              -- "individual":  fully  reduced  pixel  table  for  each  individual  exposure  --
              "positioned":  fully  reduced  and  positioned  pixel  table  for  each  individual
              exposure, the difference to "individual" is that here, the output pixel tables have
              coordinates  in  RA  and  DEC;  this  is only useful, if both the relative exposure
              weighting and the final resampling are to be done externally --  "combined":  fully
              reduced  and  combined pixel table for the full set of exposures, the difference to
              "positioned" is that all pixel tables are combined into one, with an  added  weight
              column;  this is useful, if only the final resampling step is to be done separately
              -- "stacked": an additional output file in form of a 2D column-stacked image,  i.e.
              x   direction  is  pseudo-spatial,  y  direction  is  wavelength.)  (str;  default:
              ´cube,skymodel´). The full name of this option for the EsoRex configuration file is
              muse.muse_scipost.save [default = cube,skymodel].

       --resample <str>
              The  resampling  technique  to  use  for  the  final  output  cube.  (str; default:
              ´drizzle´). The full name of this option  for  the  EsoRex  configuration  file  is
              muse.muse_scipost.resample [default = drizzle].

       --dx <float>
              Horizontal  step  size  for resampling (in arcsec or pixel). The following defaults
              are taken when this value is set to 0.0: 0.2´´ for WFM, 0.025´´  for  NFM,  1.0  if
              data is in pixel units. (float; default: 0.0). The full name of this option for the
              EsoRex configuration file is muse.muse_scipost.dx [default = 0.0].

       --dy <float>
              Vertical step size for resampling (in arcsec or pixel). The following defaults  are
              taken when this value is set to 0.0: 0.2´´ for WFM, 0.025´´ for NFM, 1.0 if data is
              in pixel units. (float; default: 0.0). The full name of this option for the  EsoRex
              configuration file is muse.muse_scipost.dy [default = 0.0].

       --dlambda <float>
              Wavelength step size (in Angstrom). Natural instrument sampling is used, if this is
              0.0  (float;  default:  0.0).  The  full  name  of  this  option  for  the   EsoRex
              configuration file is muse.muse_scipost.dlambda [default = 0.0].

       --crtype <str>
              Type  of  statistics  used  for  detection  of cosmic rays during final resampling.
              "iraf" uses the variance information, "mean" uses standard (mean/stdev) statistics,
              "median"  uses median and the median median of the absolute median deviation. (str;
              default: ´median´). The full name of this option for the EsoRex configuration  file
              is muse.muse_scipost.crtype [default = median].

       --crsigma <float>
              Sigma  rejection  factor to use for cosmic ray rejection during final resampling. A
              zero or negative value switches cosmic ray rejection off. (float;  default:  15.0).
              The   full   name   of   this   option   for   the  EsoRex  configuration  file  is
              muse.muse_scipost.crsigma [default = 15.0].

       --rc <float>
              Critical radius for the "renka" resampling method. (float; default: 1.25). The full
              name  of  this  option  for  the  EsoRex configuration file is muse.muse_scipost.rc
              [default = 1.25].

       --pixfrac <str>
              Pixel down-scaling factor  for  the  "drizzle"  resampling  method.  Up  to  three,
              comma-separated, floating-point values can be given. If only one value is given, it
              applies to all dimensions, two values  are  interpreted  as  spatial  and  spectral
              direction,  respectively,  while  three  are  taken  as  horizontal,  vertical, and
              spectral. (str; default: ´0.8,0.8´). The full name of this option  for  the  EsoRex
              configuration file is muse.muse_scipost.pixfrac [default = 0.8,0.8].

       --ld <int>
              Number  of  adjacent  pixels  to  take  into account during resampling in all three
              directions (loop distance); this affects all resampling methods  except  "nearest".
              (int;  default:  1). The full name of this option for the EsoRex configuration file
              is muse.muse_scipost.ld [default = 1].

       --format <str>
              Type of output file format, "Cube"  is  a  standard  FITS  cube  with  NAXIS=3  and
              multiple  extensions  (for data and variance). The extended "x" formats include the
              reconstructed image(s) in FITS image extensions within  the  same  file.  "sdpCube"
              does  some  extra  calculations  to  create  FITS keywords for the ESO Science Data
              Products. (str; default: ´Cube´). The full name  of  this  option  for  the  EsoRex
              configuration file is muse.muse_scipost.format [default = Cube].

       --weight <str>
              Type  of weighting scheme to use when combining multiple exposures.  "exptime" just
              uses the exposure time to weight the exposures,  "fwhm"  uses  the  best  available
              seeing  information  from  the headers as well, "none" preserves an existing weight
              column in the input pixel tables without changes. (str;  default:  ´exptime´).  The
              full    name    of   this   option   for   the   EsoRex   configuration   file   is
              muse.muse_scipost.weight [default = exptime].

       --filter <str>
              The filter name(s) to be used for the output field-of-view image. Each name has  to
              correspond to an EXTNAME in an extension of the FILTER_LIST file. If an unsupported
              filter name is given, creation of the respective  image  is  omitted.  If  multiple
              filter  names  are given, they have to be comma separated. (str; default: ´white´).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              muse.muse_scipost.filter [default = white].

       --autocalib <str>
              The  type  of  autocalibration to use. "none" switches it off, "deepfield" uses the
              revised MPDAF method that can be used for  the  reduction  of  mostly  empty  "Deep
              Fields",  "user"  searches for a user- provided table with autocalibration factors.
              (str; default: ´none´). The full name of this option for the  EsoRex  configuration
              file is muse.muse_scipost.autocalib [default = none].

       --raman_width <float>
              Wavelength  range  around  Raman lines [Angstrom]. (float; default: 20.0). The full
              name    of    this    option    for    the    EsoRex    configuration    file    is
              muse.muse_scipost.raman_width [default = 20.0].

       --skymethod <str>
              The  method  used  to subtract the sky background (spectrum). Option "model" should
              work in all kinds of science fields: it uses a global sky  spectrum  model  with  a
              local  LSF.  "model"  uses  fluxes  indicated  in  the  SKY_LINES  file as starting
              estimates, but re-fits them on the global sky spectrum  created  from  the  science
              exposure.  If  SKY_CONTINUUM  is  given, it is directly subtracted, otherwise it is
              created from the sky region of the science exposure. Option "subtract- model"  uses
              the input SKY_LINES and SKY_CONTINUUM, subtracting them directly without re-fitting
              the fluxes, but still makes use of the local LSF, hence  LSF_PROFILE  is  required.
              The  inputs  LSF_PROFILE  and  SKY_LINES  are  necessary  for these two model-based
              methods; SKY_CONTINUUM is required for "subtract-model" and optional  for  "model";
              SKY_MASK  is  optional for "model". Finally, option "simple" creates a sky spectrum
              from the science data, and directly subtracts  it,  without  taking  the  LSF  into
              account  (LSF_PROFILE  and  input SKY files are ignored). It works on data that was
              not flux calibrated.  (str; default: ´model´). The full name of this option for the
              EsoRex configuration file is muse.muse_scipost.skymethod [default = model].

       --lambdamin <float>
              Cut  off  the  data below this wavelength after loading the pixel table(s). (float;
              default: 4000.0). The full name of this option for the EsoRex configuration file is
              muse.muse_scipost.lambdamin [default = 4000.0].

       --lambdamax <float>
              Cut  off  the  data above this wavelength after loading the pixel table(s). (float;
              default: 10000.0). The full name of this option for the EsoRex  configuration  file
              is muse.muse_scipost.lambdamax [default = 10000.0].

       --lambdaref <float>
              Reference  wavelength  used  for correction of differential atmospheric refraction.
              The R-band (peak wavelength ~7000 Angstrom) that is usually used  for  guiding,  is
              close  to  the  central wavelength of MUSE, so a value of 7000.0 Angstrom should be
              used if nothing else is known.  A value less than zero switches DAR correction off.
              (float; default: 7000.0). The full name of this option for the EsoRex configuration
              file is muse.muse_scipost.lambdaref [default = 7000.0].

       --darcheck <str>
              Carry out a check of the theoretical DAR correction using  source  centroiding.  If
              "correct"  it will also apply an empirical correction.  (str; default: ´none´). The
              full   name   of   this   option   for   the   EsoRex   configuration    file    is
              muse.muse_scipost.darcheck [default = none].

       --skymodel_fraction <float>
              Fraction  of  the  image  (without the ignored part) to be considered as sky. If an
              input sky mask is provided, the fraction is applied to the regions within the mask.
              If  the  whole  sky  mask should be used, set this parameter to 1. (float; default:
              0.1).  The  full  name  of  this  option  for  the  EsoRex  configuration  file  is
              muse.muse_scipost.skymodel_fraction [default = 0.1].

       --skymodel_ignore <float>
              Fraction of the image to be ignored. If an input sky mask is provided, the fraction
              is applied to the regions within the mask. If the whole sky mask  should  be  used,
              set  this  parameter to 0. (float; default: 0.05). The full name of this option for
              the EsoRex  configuration  file  is  muse.muse_scipost.skymodel_ignore  [default  =
              0.05].

       --skymodel_sampling <float>
              Spectral  sampling  of  the  sky spectrum [Angstrom]. (float; default: 0.3125). The
              full   name   of   this   option   for   the   EsoRex   configuration    file    is
              muse.muse_scipost.skymodel_sampling [default = 0.3125].

       --skymodel_csampling <float>
              Spectral  sampling  of the continuum spectrum [Angstrom]. (float; default: 0.3125).
              The  full  name  of  this   option   for   the   EsoRex   configuration   file   is
              muse.muse_scipost.skymodel_csampling [default = 0.3125].

       --sky_crsigma <str>
              Sigma  level  clipping for cube-based and spectrum-based CR rejection when creating
              the sky spectrum. This has to be a string of two  comma-  separated  floating-point
              numbers.  The  first  value  gives  the  sigma-  level  rejection for cube-based CR
              rejection (using "median"), the second value the sigma-level for spectrum-based  CR
              cleaning.  Both  can  be  switched  off, by passing zero or a negative value. (str;
              default: ´15.,15.´). The full name of this option for the EsoRex configuration file
              is muse.muse_scipost.sky_crsigma [default = 15.,15.].

       --rvcorr <str>
              Correct  the  radial  velocity  of  the  telescope  with  reference  to  either the
              barycenter of the Solar System (bary), the center of the Sun  (helio),  or  to  the
              center of the Earth (geo). (str; default: ´bary´). The full name of this option for
              the EsoRex configuration file is muse.muse_scipost.rvcorr [default = bary].

       --astrometry <bool>
              If false, skip any astrometric calibration, even if one was passed in the input set
              of  files.  This causes creation of an output cube with a linear WCS and may result
              in errors. If you want to use a sensible default, leave this true but do  not  pass
              an  ASTROMETRY_WCS.  (bool;  default:  True).  The full name of this option for the
              EsoRex configuration file is muse.muse_scipost.astrometry [default = True].

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

              ftp://ftp.eso.org/pub/dfs/pipelines/muse/muse-pipeline-cookbook-2.6.2.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 muse pipeline are muse_ampl(7), muse_astrometry(7), muse_bias(7),
       muse_create_sky(7), muse_dark(7),  muse_exp_align(7),  muse_exp_combine(7),  muse_flat(7),
       muse_geometry(7),    muse_illum(7),    muse_lingain(7),    muse_lsf(7),   muse_qi_mask(7),
       muse_scibasic(7),    muse_scipost_apply_astrometry(7),     muse_scipost_calibrate_flux(7),
       muse_scipost_combine_pixtables(7),                            muse_scipost_correct_dar(7),
       muse_scipost_correct_rv(7),       muse_scipost_make_cube(7),        muse_scipost_raman(7),
       muse_scipost_subtract_sky(7),    muse_scipost_subtract_sky_simple(7),    muse_standard(7),
       muse_twilight(7), muse_wavecal(7)

VERSION

       muse_scipost 2.6.2

AUTHOR

       Peter Weilbacher <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  MUSE  Instrument Pipeline Copyright (C) 2005, 2018 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