The muse_scipost recipe
===============================================================

.. data:: muse_scipost

Synopsis
--------

Prepare reduced and combined science products.

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.


Constructor
-----------

.. method:: cpl.Recipe("muse_scipost")
   :noindex:

   Create an object for the recipe muse_scipost.

::

   import cpl
   muse_scipost = cpl.Recipe("muse_scipost")

Parameters
----------

.. py:attribute:: muse_scipost.param.save

    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') [default="cube,skymodel"].
.. py:attribute:: muse_scipost.param.resample

    The resampling technique to use for the final output cube. (str;  default: 'drizzle') [default="drizzle"].
.. py:attribute:: muse_scipost.param.dx

    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) [default=0.0].
.. py:attribute:: muse_scipost.param.dy

    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) [default=0.0].
.. py:attribute:: muse_scipost.param.dlambda

    Wavelength step size (in Angstrom). Natural instrument sampling is  used, if this is 0.0 (float; default: 0.0) [default=0.0].
.. py:attribute:: muse_scipost.param.crtype

    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') [default="median"].
.. py:attribute:: muse_scipost.param.crsigma

    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) [default=15.0].
.. py:attribute:: muse_scipost.param.rc

    Critical radius for the "renka" resampling method. (float; default:  1.25) [default=1.25].
.. py:attribute:: muse_scipost.param.pixfrac

    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') [default="0.8,0.8"].
.. py:attribute:: muse_scipost.param.ld

    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) [default=1].
.. py:attribute:: muse_scipost.param.format

    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') [default="Cube"].
.. py:attribute:: muse_scipost.param.weight

    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') [default="exptime"].
.. py:attribute:: muse_scipost.param.filter

    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') [default="white"].
.. py:attribute:: muse_scipost.param.autocalib

    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') [default="none"].
.. py:attribute:: muse_scipost.param.raman_width

    Wavelength range around Raman lines [Angstrom]. (float; default: 20.0) [default=20.0].
.. py:attribute:: muse_scipost.param.skymethod

    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') [default="model"].
.. py:attribute:: muse_scipost.param.lambdamin

    Cut off the data below this wavelength after loading the pixel  table(s). (float; default: 4000.0) [default=4000.0].
.. py:attribute:: muse_scipost.param.lambdamax

    Cut off the data above this wavelength after loading the pixel  table(s). (float; default: 10000.0) [default=10000.0].
.. py:attribute:: muse_scipost.param.lambdaref

    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) [default=7000.0].
.. py:attribute:: muse_scipost.param.darcheck

    Carry out a check of the theoretical DAR correction using source  centroiding. If "correct" it will also apply an empirical correction.  (str; default: 'none') [default="none"].
.. py:attribute:: muse_scipost.param.skymodel_fraction

    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) [default=0.1].
.. py:attribute:: muse_scipost.param.skymodel_ignore

    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) [default=0.05].
.. py:attribute:: muse_scipost.param.skymodel_sampling

    Spectral sampling of the sky spectrum [Angstrom]. (float; default:  0.3125) [default=0.3125].
.. py:attribute:: muse_scipost.param.skymodel_csampling

    Spectral sampling of the continuum spectrum [Angstrom]. (float;  default: 0.3125) [default=0.3125].
.. py:attribute:: muse_scipost.param.sky_crsigma

    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.') [default="15.,15."].
.. py:attribute:: muse_scipost.param.rvcorr

    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') [default="bary"].
.. py:attribute:: muse_scipost.param.astrometry

    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) [default=True].


The following code snippet shows the default settings for the available 
parameters.

::

   import cpl
   muse_scipost = cpl.Recipe("muse_scipost")

   muse_scipost.param.save = "cube,skymodel"
   muse_scipost.param.resample = "drizzle"
   muse_scipost.param.dx = 0.0
   muse_scipost.param.dy = 0.0
   muse_scipost.param.dlambda = 0.0
   muse_scipost.param.crtype = "median"
   muse_scipost.param.crsigma = 15.0
   muse_scipost.param.rc = 1.25
   muse_scipost.param.pixfrac = "0.8,0.8"
   muse_scipost.param.ld = 1
   muse_scipost.param.format = "Cube"
   muse_scipost.param.weight = "exptime"
   muse_scipost.param.filter = "white"
   muse_scipost.param.autocalib = "none"
   muse_scipost.param.raman_width = 20.0
   muse_scipost.param.skymethod = "model"
   muse_scipost.param.lambdamin = 4000.0
   muse_scipost.param.lambdamax = 10000.0
   muse_scipost.param.lambdaref = 7000.0
   muse_scipost.param.darcheck = "none"
   muse_scipost.param.skymodel_fraction = 0.1
   muse_scipost.param.skymodel_ignore = 0.05
   muse_scipost.param.skymodel_sampling = 0.3125
   muse_scipost.param.skymodel_csampling = 0.3125
   muse_scipost.param.sky_crsigma = "15.,15."
   muse_scipost.param.rvcorr = "bary"
   muse_scipost.param.astrometry = True


You may also set or overwrite some or all parameters by the recipe 
parameter `param`, as shown in the following example:

::

   import cpl
   muse_scipost = cpl.Recipe("muse_scipost")
   [...]
   res = muse_scipost( ..., param = {"save":"cube,skymodel", "resample":"drizzle"})


.. seealso:: `cpl.Recipe <https://packages.python.org/python-cpl/recipe.html>`_
   for more information about the recipe object.

Bug reports
-----------

Please report any problems to `Peter Weilbacher <https://support.eso.org>`_. Alternatively, you may 
send a report to the `ESO User Support Department <usd-help@eso.org>`_.

Copyright
---------

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

.. codeauthor:: Peter Weilbacher <https://support.eso.org>
