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. (long; default:  2144337919) [default=2144337919].
.. py:attribute:: xsh_mflat.param.pre_overscan_corr

    pre-overscan correction.0: no correction1: mean overscan correction2:  mean prescan correction3: (mean pre+mean overscan)/2 correction (long;  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

    Half window size in pixels for the search for order edges (long;  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] (long; default: -1) [default=-1].
.. py:attribute:: xsh_mflat.param.detectorder_chunk_half_size

    Half size in pixels of the chunks in Y direction (long; 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 (long;  default: 1) [default=1].
.. py:attribute:: xsh_mflat.param.background_poly_deg_y

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

    Poly mode fit deg along X. (long; 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 <http://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>
