The xsh_mflat recipe
===============================================================

.. data:: xsh_mflat

Synopsis
--------

Create the master flat and the orders edges traces table frames

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

This recipe creates the master flat and the orders edges traces table frames.

  Input Frames :
    - [UVB] A set of n RAW frames (Format = RAW, n>=3, Tag = FLAT_D2_mode_UVB, mode=SLIT/IFU)
    - [UVB] A set of n RAW frames (Format = RAW, n>=3, Tag = FLAT_QTH_mode_UVB)
    - [VIS] A set of n RAW frames (Format = RAW, n>=3, Tag = FLAT_mode_VIS)
    - [NIR] A set of n x n RAW frames ((Format = RAW, n>=3, Tag = FLAT_mode_NIR_ON, FLAT_mode_NIR_OFF)
    - A spectral format table (Format = PRE, Tag = SPECTRAL_FORMAT_TAB_arm)
    - An order table (Format = TABLE, Tag = ORDER_TAB_CENTR_arm)
    - [UVB,VIS] A master bias (Format = PRE, Tag = MASTER_BIAS_arm)
    - [OPTIONAL] A map of reference bad pixel (Format = QUP,RAW, Tag = BP_MAP_RP_arm)
    - [OPTIONAL] A map of non linear pixel (Format = QUP,RAW, Tag = BP_MAP_NL_arm)
    - [OPTIONAL,UVB,VIS] A master dark (Format = PRE, Tag = MASTER_DARK_arm)
  Products : 
    - An updated order table with edge UP and edge LOW (Format = TABLE, TAG = ORDER_TAB_EDGES_mode_arm)
    - A master flat (Format = PRE, PRO.CATG = MASTER_FLAT_mode_arm)
    - The inter-order background frame (Format = PRE, PRO.CATG = MFLAT_BACK_mode_arm)
    - The inter-order background sampling points grid table
      (Format = PRE, PRO.CATG = MFLAT_GRID_BACK_mode_arm)
  Prepare the flat frames.

  Stack and sigma clip all the flat frames.

  Subtract master bias.

  Subtract master dark.

  Detect order edge.

  Subtract background.

  Create the Master Flat.


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

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

   Create an object for the recipe xsh_mflat.

::

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

Parameters
----------

.. py:attribute:: xsh_mflat.param.keep_temp

    If 'no', temporary files are deleted. (str; default: 'no') [default="no"].
.. py:attribute:: xsh_mflat.param.debug_level

    Additional xshooter debug level. One of 'none', 'low', 'medium',  'high' (str; default: 'none') [default="none"].
.. py:attribute:: xsh_mflat.param.time_stamp

    Add timestamp to product file name. (bool; default: False) [default=False].
.. py:attribute:: xsh_mflat.param.decode_bp

    Integer representation of the bits to be considered bad when decoding  the bad pixel mask pixel values.   Most frequent codes relevant for  the user:   0: good pixel,   8: pick-up noise,   16: cosmic-ray  removed,   32: cosmic-ray unremoved,   128: calibration file defect,  256: hot pixel,   512: dark pixel,   4096: A/D converted saturation,  32768: non linear pixel,   1048576: extrapolated flux in NIR,  4194304: Interpolated flux during extraction. (int; default:  2144337919) [default=2144337919].
.. py:attribute:: xsh_mflat.param.pre_overscan_corr

    pre-overscan correction. 0: no correction 1: mean overscan correction  2: mean prescan correction 3: (mean pre+mean overscan)/2 correction  (int; default: 1) [default=1].
.. py:attribute:: xsh_mflat.param.stack_method

    Method used to build master frame. (str; default: 'median') [default="median"].
.. py:attribute:: xsh_mflat.param.klow

    Kappa used to clip low level values, when method is set to 'mean'  (float; default: 5.0) [default=5.0].
.. py:attribute:: xsh_mflat.param.khigh

    Kappa used to clip high level values, when method is set to 'mean'  (float; default: 5.0) [default=5.0].
.. py:attribute:: xsh_mflat.param.detectorder_edges_search_win_hsize

    During extraction the local spatial profile (=cross-order) of the  spectrum is determined by collapsing the 2-dimensional spectrum along  the dispersion axis. This parameter defines the half size of the  region across which the spectrum is collapsed. This parameter affects  flagged pixels interpolation. In case of spectrum gaps the recommended  optimal value is: (size_of_gap [nm]/(2*size_of_pixel [nm])+1) (int;  default: 50) [default=50].
.. py:attribute:: xsh_mflat.param.detectorder_edges_flux_thresh

    Threshold in relative flux (compared to the central flux) below which  the order edges are defined (float; default: 0.4) [default=0.4].
.. py:attribute:: xsh_mflat.param.detectorder_min_sn

    Minimum signal-to-noise ratio at the centroid of the orders (60 for  SLIT-UVB,VIS,NIR, 20 for IFU-UVB,VIS, 4 for IFU-NIR (float; default:  -1.0) [default=-1.0].
.. py:attribute:: xsh_mflat.param.detectorder_min_order_size_x

    Minimum order size in pixels along X direction [60 for UVB,VIS, 40 for  NIR] (int; default: -1) [default=-1].
.. py:attribute:: xsh_mflat.param.detectorder_chunk_half_size

    Half size in pixels of the chunks in Y direction (int; default: 1) [default=1].
.. py:attribute:: xsh_mflat.param.detectorder_slitlet_low_factor

    Factor for slitlet on lower edge slitlet (IFU) (float; default: 1.0) [default=1.0].
.. py:attribute:: xsh_mflat.param.detectorder_slitlet_up_factor

    Factor for slitlet on upper edge (IFU) (float; default: 1.0) [default=1.0].
.. py:attribute:: xsh_mflat.param.detectorder_fixed_slice

    If true the size of slitlet is fixed (IFU) (bool; default: True) [default=True].
.. py:attribute:: xsh_mflat.param.detectorder_slice_trace_method

    method adopted for IFU slice tracing ('fixed' for SLIT and 'sobel' for  IFU): (str; default: 'auto') [default="auto"].
.. py:attribute:: xsh_mflat.param.detectorder_qc_mode

    If true allows one to skip edge detection on orders below detectorder-  min-sn (oly for QC mode, not to be set by normal users) (bool;  default: False) [default=False].
.. py:attribute:: xsh_mflat.param.detectorder_d2_min_sn

    minimum signal noise ratio in D2 lamp frame in order (float; default:  60.0) [default=60.0].
.. py:attribute:: xsh_mflat.param.background_edges_margin

    X margin to order edge to define background sampling points (int;  default: 1) [default=1].
.. py:attribute:: xsh_mflat.param.background_poly_deg_y

    Poly mode fit deg along Y. (int; default: 9) [default=9].
.. py:attribute:: xsh_mflat.param.background_poly_deg_x

    Poly mode fit deg along X. (int; default: 9) [default=9].
.. py:attribute:: xsh_mflat.param.background_poly_kappa

    Poly mode kappa value of kappa-sigma-clip outliers removal. (float;  default: 10.0) [default=10.0].


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

::

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

   xsh_mflat.param.keep_temp = "no"
   xsh_mflat.param.debug_level = "none"
   xsh_mflat.param.time_stamp = False
   xsh_mflat.param.decode_bp = 2144337919
   xsh_mflat.param.pre_overscan_corr = 1
   xsh_mflat.param.stack_method = "median"
   xsh_mflat.param.klow = 5.0
   xsh_mflat.param.khigh = 5.0
   xsh_mflat.param.detectorder_edges_search_win_hsize = 50
   xsh_mflat.param.detectorder_edges_flux_thresh = 0.4
   xsh_mflat.param.detectorder_min_sn = -1.0
   xsh_mflat.param.detectorder_min_order_size_x = -1
   xsh_mflat.param.detectorder_chunk_half_size = 1
   xsh_mflat.param.detectorder_slitlet_low_factor = 1.0
   xsh_mflat.param.detectorder_slitlet_up_factor = 1.0
   xsh_mflat.param.detectorder_fixed_slice = True
   xsh_mflat.param.detectorder_slice_trace_method = "auto"
   xsh_mflat.param.detectorder_qc_mode = False
   xsh_mflat.param.detectorder_d2_min_sn = 60.0
   xsh_mflat.param.background_edges_margin = 1
   xsh_mflat.param.background_poly_deg_y = 9
   xsh_mflat.param.background_poly_deg_x = 9
   xsh_mflat.param.background_poly_kappa = 10.0


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

::

   import cpl
   xsh_mflat = cpl.Recipe("xsh_mflat")
   [...]
   res = xsh_mflat( ..., param = {"keep_temp":"no", "debug_level":"none"})


.. 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 `P.Goldoni, L.Guglielmi, R. Haigron, F. Royer, D. Bramich, A. Modigliani <amodigli@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 X-shooter Instrument Pipeline
Copyright (C) 2006 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., 59 Temple Place, Suite 330, Boston, 
MA  02111-1307  USA

.. codeauthor:: P.Goldoni, L.Guglielmi, R. Haigron, F. Royer, D. Bramich, A. Modigliani <amodigli@eso.org>
