Provided by: cpl-plugin-muse-doc_2.8.5+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, or NFM is used which has a built-in
       corrector). 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. 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.
       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.  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, and the optional offsets  were  applied;  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.8.5.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.8.5

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,  2019  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