The gimasterflat recipe
===============================================================

.. data:: gimasterflat

Synopsis
--------

Create the fiber master flat field and the localization mask.

Description
-----------

For detailed information please refer to the GIRAFFE pipeline user manual.

It is available at http://www.eso.org/pipelines.


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

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

   Create an object for the recipe gimasterflat.

::

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

Parameters
----------

.. py:attribute:: gimasterflat.param.fiber_splist

    Index list of spectra to use for localization (e.g. 2,10,30-40,55).  (str; default: '') [default=""].
.. py:attribute:: gimasterflat.param.fiber_nspec

    Number of spectra to localize. (int; default: 0) [default=0].
.. py:attribute:: gimasterflat.param.remove_bias

    Enable bias removal (bool; default: True) [default=True].
.. py:attribute:: gimasterflat.param.bsremove_method

    Bias removal method (str; default: 'PROFILE') [default="PROFILE"].
.. py:attribute:: gimasterflat.param.bsremove_areas

    Bias areas to use (Xl0:Xr0:Yl0:Yr0, ... ,Xln:Xrn:Yln:Yrn) (str;  default: '5:40:0:4095') [default="5:40:0:4095"].
.. py:attribute:: gimasterflat.param.bsremove_sigma

    Sigma Clipping: sigma threshold factor (float; default: 2.5) [default=2.5].
.. py:attribute:: gimasterflat.param.bsremove_niter

    Sigma Clipping: maximum number of iterations (int; default: 5) [default=5].
.. py:attribute:: gimasterflat.param.bsremove_mfrac

    Sigma Clipping: minimum fraction of points accepted/total [0.0..1.0]  (float; default: 0.8) [default=0.8].
.. py:attribute:: gimasterflat.param.bsremove_xorder

    Order of X polynomial fit (CURVE method only) (int; default: 1) [default=1].
.. py:attribute:: gimasterflat.param.bsremove_yorder

    Order of Y polynomial fit (CURVE method only) (int; default: 1) [default=1].
.. py:attribute:: gimasterflat.param.bsremove_xstep

    Sampling step along X (CURVE method only) (int; default: 1) [default=1].
.. py:attribute:: gimasterflat.param.bsremove_ystep

    Sampling step along Y (CURVE method only) (int; default: 1) [default=1].
.. py:attribute:: gimasterflat.param.sloc_mode

    Localization mode: Use all spectra or the 5 SIWC spectra (str;  default: 'all') [default="all"].
.. py:attribute:: gimasterflat.param.sloc_start

    Bin along x-axis (int; default: -1) [default=-1].
.. py:attribute:: gimasterflat.param.sloc_retries

    Initial localization detection xbin retries. (int; default: 10) [default=10].
.. py:attribute:: gimasterflat.param.sloc_binsize

    Initial localization detection xbin size. (int; default: -1) [default=-1].
.. py:attribute:: gimasterflat.param.sloc_ewidth

    Localization detection extra width. (float; default: 1.0) [default=1.0].
.. py:attribute:: gimasterflat.param.sloc_ywidth

    Full width [pxl] of the equilizing filter (distance between two  adjacent fibers). (int; default: -1) [default=-1].
.. py:attribute:: gimasterflat.param.sloc_center

    Method used for mask center computation. (str; default: 'centroid') [default="centroid"].
.. py:attribute:: gimasterflat.param.sloc_norm

    Enable spectrum normalization along the dispersion axis. (bool;  default: False) [default=False].
.. py:attribute:: gimasterflat.param.sloc_noise

    Threshold multiplier. (float; default: 7.0) [default=7.0].
.. py:attribute:: gimasterflat.param.sloc_threshold

    Selects thresholding algorithm: local, row or global (str; default:  'local') [default="local"].
.. py:attribute:: gimasterflat.param.sloc_ron

    New bias sigma (RON) value for dark subtraction (float; default: -1.0) [default=-1.0].
.. py:attribute:: gimasterflat.param.sloc_yorder

    Order of Chebyshev polynomial fit. (int; default: 4) [default=4].
.. py:attribute:: gimasterflat.param.sloc_worder

    Order of Chebyshev 2D polynomial fit. (int; default: 2) [default=2].
.. py:attribute:: gimasterflat.param.sloc_sigma

    Localization clipping: sigma threshold factor (float; default: 2.5) [default=2.5].
.. py:attribute:: gimasterflat.param.sloc_niter

    Localization clipping: number of iterations (int; default: 5) [default=5].
.. py:attribute:: gimasterflat.param.sloc_mfrac

    Localization clipping: minimum fraction of points accepted/total.  (float; default: 0.9) [default=0.9].
.. py:attribute:: gimasterflat.param.psf_model

    PSF profile model: `psfexp', `psfexp2' (str; default: 'psfexp2') [default="psfexp2"].
.. py:attribute:: gimasterflat.param.psf_norm

    Use normalized pixel values. (bool; default: False) [default=False].
.. py:attribute:: gimasterflat.param.psf_binsize

    Size of bin along dispersion axis (int; default: 64) [default=64].
.. py:attribute:: gimasterflat.param.psf_maxwidth

    Maximum width of the PSF profile. (float; default: 16.0) [default=16.0].
.. py:attribute:: gimasterflat.param.psf_width

    Initial width of the PSF profile. (float; default: 0.0) [default=0.0].
.. py:attribute:: gimasterflat.param.psf_exponent

    Exponent of the exponential PSF profile (will not be fitted if > 0).  (float; default: -3.0) [default=-3.0].
.. py:attribute:: gimasterflat.param.psf_pfniter

    Maximum number of iterations used for the fit of the fiber PSF  profile. (int; default: 120) [default=120].
.. py:attribute:: gimasterflat.param.psf_pfntest

    Maximum number of tests used for the fit of the fiber PSF profile  (int; default: 7) [default=7].
.. py:attribute:: gimasterflat.param.psf_pfdchisq

    Minimum chi-square difference used for the fit of the fiber PSF  profile. (float; default: 0.001) [default=0.001].
.. py:attribute:: gimasterflat.param.psf_prmfit

    2D fit of the PSF profile parameters using a Chebyshev polynomial  model. (bool; default: False) [default=False].
.. py:attribute:: gimasterflat.param.psf_yorder

    Order of Chebyshev polynomial fit. (int; default: 4) [default=4].
.. py:attribute:: gimasterflat.param.psf_worder

    Order of Chebyshev 2D polynomial fit. (int; default: 4) [default=4].
.. py:attribute:: gimasterflat.param.psf_sigma

    PSF parameter fitting: sigma threshold factor (float; default: 3.5) [default=3.5].
.. py:attribute:: gimasterflat.param.psf_niter

    PSF parameter fitting: number of iterations (int; default: 10) [default=10].
.. py:attribute:: gimasterflat.param.psf_mfrac

    PSF parameter fitting: minimum fraction of points accepted/total.  (float; default: 0.8) [default=0.8].
.. py:attribute:: gimasterflat.param.extr_method

    Extraction method: 'SUM', 'HORNE' or 'OPTIMAL' (str; default: 'SUM') [default="SUM"].
.. py:attribute:: gimasterflat.param.extr_ron

    New bias sigma (RON) value for bias and dark corrected image (float;  default: -1.0) [default=-1.0].
.. py:attribute:: gimasterflat.param.extr_psfmodel

    PSF profile model: `psfexp', `psfexp2' (str; default: 'psfexp2') [default="psfexp2"].
.. py:attribute:: gimasterflat.param.extr_psfsigma

    Sigma clippging threshold used for rejecting data points during PSF  fitting (Horne's sigma). It is used to reject bad pixels and cosmics.  (float; default: 7.0) [default=7.0].
.. py:attribute:: gimasterflat.param.extr_psfniter

    Maximum number of iterations used for fitting the PSF profile. (int;  default: 2) [default=2].
.. py:attribute:: gimasterflat.param.extr_hewidth

    Horne extraction method: Number of extra pixels added to the fiber  half-width. (int; default: 2) [default=2].
.. py:attribute:: gimasterflat.param.extr_hmingood

    Horne extraction method: Minimum number of points used for the profile  fit. It sets the lower limit of data points for the pixel rejection.  (int; default: 3) [default=3].
.. py:attribute:: gimasterflat.param.extr_omfrac

    Optimal extraction method: Minimum fraction of the data points used  for fitting the fiber profiles. It sets the lower limit for the pixel  rejection. (float; default: 0.9) [default=0.9].
.. py:attribute:: gimasterflat.param.extr_owfactor

    Optimal extraction method: Factor by which the fiber PSF half width is  multiplied. Adjacent spectra within this area are assumed to affect  the spectrum being extracted. (float; default: 3.0) [default=3.0].
.. py:attribute:: gimasterflat.param.extr_obkgorder

    Optimal extraction method: Order of the polynomial background model,  which is fitted for each wavelength bin along the spatial direction.  (int; default: 2) [default=2].
.. py:attribute:: gimasterflat.param.transmission

    Controls the relative fiber transmission computation. (bool; default:  True) [default=True].
.. py:attribute:: gimasterflat.param.slight

    Controls the scattered light model computation. (bool; default: False) [default=False].
.. py:attribute:: gimasterflat.param.slight_model

    Name of the scattered light model to use. (str; default: 'polynom') [default="polynom"].
.. py:attribute:: gimasterflat.param.slight_order

    Scattered light model fit X and Y order. (str; default: '4,2') [default="4,2"].
.. py:attribute:: gimasterflat.param.slight_xstep

    Interspectrum region sampling step along the dispersion direction.  (int; default: 10) [default=10].
.. py:attribute:: gimasterflat.param.slight_ystep

    Interspectrum region sampling step along the spatial direction. (int;  default: 1) [default=1].
.. py:attribute:: gimasterflat.param.slight_xslice

    Interspectrum region sampling step along the dispersion direction for  a specific region. This overrides 'xstep' for the given region. (str;  default: 'none') [default="none"].
.. py:attribute:: gimasterflat.param.slight_ewidth

    Extra width [pixels] added to both sides of a spectrum trace. (float;  default: 0.5) [default=0.5].
.. py:attribute:: gimasterflat.param.slight_iswidth

    Minimum width [pixels] required for interspectrum regions. (int;  default: 2) [default=2].
.. py:attribute:: gimasterflat.param.slight_istrim

    Turn off using the first and last interspectrum region. (bool;  default: True) [default=True].
.. py:attribute:: gimasterflat.param.slight_phff

    Use photometric flat field correction. (bool; default: False) [default=False].
.. py:attribute:: gimasterflat.param.slight_remove

    Remove scattered light from the input frame. (bool; default: False) [default=False].


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

::

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

   gimasterflat.param.fiber_splist = ""
   gimasterflat.param.fiber_nspec = 0
   gimasterflat.param.remove_bias = True
   gimasterflat.param.bsremove_method = "PROFILE"
   gimasterflat.param.bsremove_areas = "5:40:0:4095"
   gimasterflat.param.bsremove_sigma = 2.5
   gimasterflat.param.bsremove_niter = 5
   gimasterflat.param.bsremove_mfrac = 0.8
   gimasterflat.param.bsremove_xorder = 1
   gimasterflat.param.bsremove_yorder = 1
   gimasterflat.param.bsremove_xstep = 1
   gimasterflat.param.bsremove_ystep = 1
   gimasterflat.param.sloc_mode = "all"
   gimasterflat.param.sloc_start = -1
   gimasterflat.param.sloc_retries = 10
   gimasterflat.param.sloc_binsize = -1
   gimasterflat.param.sloc_ewidth = 1.0
   gimasterflat.param.sloc_ywidth = -1
   gimasterflat.param.sloc_center = "centroid"
   gimasterflat.param.sloc_norm = False
   gimasterflat.param.sloc_noise = 7.0
   gimasterflat.param.sloc_threshold = "local"
   gimasterflat.param.sloc_ron = -1.0
   gimasterflat.param.sloc_yorder = 4
   gimasterflat.param.sloc_worder = 2
   gimasterflat.param.sloc_sigma = 2.5
   gimasterflat.param.sloc_niter = 5
   gimasterflat.param.sloc_mfrac = 0.9
   gimasterflat.param.psf_model = "psfexp2"
   gimasterflat.param.psf_norm = False
   gimasterflat.param.psf_binsize = 64
   gimasterflat.param.psf_maxwidth = 16.0
   gimasterflat.param.psf_width = 0.0
   gimasterflat.param.psf_exponent = -3.0
   gimasterflat.param.psf_pfniter = 120
   gimasterflat.param.psf_pfntest = 7
   gimasterflat.param.psf_pfdchisq = 0.001
   gimasterflat.param.psf_prmfit = False
   gimasterflat.param.psf_yorder = 4
   gimasterflat.param.psf_worder = 4
   gimasterflat.param.psf_sigma = 3.5
   gimasterflat.param.psf_niter = 10
   gimasterflat.param.psf_mfrac = 0.8
   gimasterflat.param.extr_method = "SUM"
   gimasterflat.param.extr_ron = -1.0
   gimasterflat.param.extr_psfmodel = "psfexp2"
   gimasterflat.param.extr_psfsigma = 7.0
   gimasterflat.param.extr_psfniter = 2
   gimasterflat.param.extr_hewidth = 2
   gimasterflat.param.extr_hmingood = 3
   gimasterflat.param.extr_omfrac = 0.9
   gimasterflat.param.extr_owfactor = 3.0
   gimasterflat.param.extr_obkgorder = 2
   gimasterflat.param.transmission = True
   gimasterflat.param.slight = False
   gimasterflat.param.slight_model = "polynom"
   gimasterflat.param.slight_order = "4,2"
   gimasterflat.param.slight_xstep = 10
   gimasterflat.param.slight_ystep = 1
   gimasterflat.param.slight_xslice = "none"
   gimasterflat.param.slight_ewidth = 0.5
   gimasterflat.param.slight_iswidth = 2
   gimasterflat.param.slight_istrim = True
   gimasterflat.param.slight_phff = False
   gimasterflat.param.slight_remove = False


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

::

   import cpl
   gimasterflat = cpl.Recipe("gimasterflat")
   [...]
   res = gimasterflat( ..., param = {"fiber_splist":"", "fiber_nspec":0})


.. 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 `Giraffe Pipeline <usd-help@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 GIRAFFE Instrument Pipeline
 Copyright (C) 2002-2014 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

.. codeauthor:: Giraffe Pipeline <usd-help@eso.org>
