The xsh_cfg_recover recipe
===============================================================

.. data:: xsh_cfg_recover

Synopsis
--------

Optimizes a model configuration to match data taken after a major format change

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

This recipe creates a wavelength solution and an order table.

  Input Frames :
    - [UVB, VIS] A RAW frame (Format = RAW, Tag = FMTCHK_arm)
    - [NIR] Two RAW frames (Format = RAW, Tag = FMTCHK_arm_ON,FMTCHK_arm_OFF)
    - The old model cfg table (Format = TABLE, Tag = XSH_MOD_CFG_TAB_arm)
    - A ref. line list. The model computes corresponding positions 
      (Format = TABLE, Tag = ARC_LINE_LIST_arm)
    - [UVB,VIS,OPTIONAL] A master bias (Format = PRE, Tag = MASTER_BIAS_arm)
    - [UVB,VIS,OPTIONAL] A master dark (Format = PRE, Tag = MASTER_DARK_arm)
    - [OPTIONAL-Required if method=pm,peaks] 
     An order table (Format = TABLE, Tag = ORDER_TAB_CENTR_arm)
    - [OPTIONAL-Required if first-anneal=TRUE] 
      A table with measured line positions (Format = TABLE, Tag = XSH_MEASCOORD_arm)
  Products : 
    - if first-anneal=FALSE & last-step=FALSE
      nothing
    - if first-anneal=TRUE & last-step=FALSE
      an optimized model configuration, PRO.CATG=XSH_MOD_CFG_arm
    - if last-step=TRUE
      an optimized model configuration, PRO.CATG=XSH_MOD_FAN_arm
      an optimized model configuration, PRO.CATG=XSH_MOD_CFG_OPT_arm
      an quality control table, PRO.CATG=MODEL_GUESS_XY_arm
      the model theoretical map corresponding to the optimized model config,
      PRO.CATG=THEO_TAB_MULT_arm, THEO_TAB_IFU_arm, and THEO_TAB_SING_arm
      

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

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

   Create an object for the recipe xsh_cfg_recover.

::

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

Parameters
----------

.. py:attribute:: xsh_cfg_recover.param.keep_temp

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

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

    Add timestamp to product file name. (bool; default: False) [default=False].
.. py:attribute:: xsh_cfg_recover.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_cfg_recover.param.first_anneal

    Run first annealing (TRUE) or not (FALSE)See recipe man-page % Input  frames (bool; default: False) [default=False].
.. py:attribute:: xsh_cfg_recover.param.arm

    Arm setting:  (str; default: 'vis') [default="vis"].
.. py:attribute:: xsh_cfg_recover.param.name_i

    Filename with wavelength,x,y,order:  (str; default: 'line_xy_ord.txt') [default="line_xy_ord.txt"].
.. py:attribute:: xsh_cfg_recover.param.niter

    No of iterations for first anneal (int; default: 100000) [default=100000].
.. py:attribute:: xsh_cfg_recover.param.coord_frame

    Co-ordinate frame for centroids (0=raw,1=pre) (int; default: 1) [default=1].
.. py:attribute:: xsh_cfg_recover.param.last_step

    Run last step (TRUE) or not (FALSE)See recipe man-page % Input frames  (bool; default: False) [default=False].
.. py:attribute:: xsh_cfg_recover.param.plot

    Display plot (TRUE) or not (FALSE) (bool; default: False) [default=False].
.. py:attribute:: xsh_cfg_recover.param.ima_tresh_min

    Min thresh raw image. (float; default: 40.0) [default=40.0].
.. py:attribute:: xsh_cfg_recover.param.cor_prescan

    Correct for prescan (bool; default: False) [default=False].
.. py:attribute:: xsh_cfg_recover.param.method

    Model predictions correction method. safefit: safe fitgfit: 2D  Gaussian line fitpeaks: line peaks detectionpm: line peaks detection &  pattern match (str; default: 'safefit') [default="safefit"].
.. py:attribute:: xsh_cfg_recover.param.offx

    X offset to model predictions (float; default: 0.0) [default=0.0].
.. py:attribute:: xsh_cfg_recover.param.offy

    Y offset to model predictions (float; default: 0.0) [default=0.0].
.. py:attribute:: xsh_cfg_recover.param.slit

    Extraction slit (int; default: 5) [default=5].
.. py:attribute:: xsh_cfg_recover.param.gfit_box_sy

    Gauss fit Y search box size for lines on actual frame (int; default:  20) [default=20].
.. py:attribute:: xsh_cfg_recover.param.peak_line_fwhm

    The FWHM used in line convolution, in pixel units (int; default: 4) [default=4].
.. py:attribute:: xsh_cfg_recover.param.peak_kappa

    The kappa value, used to identify line peaks if  max>kappa*stdev+median, max is a valid peak where max, stdev,median  are computed on the extracted spectrum (float; default: 5.0) [default=5.0].
.. py:attribute:: xsh_cfg_recover.param.peak_factor

    Relative Intensity threshold factor for line peaks detection (float;  default: 10.0) [default=10.0].
.. py:attribute:: xsh_cfg_recover.param.peak_match_x

    Radii for line peaks matches (int; default: 10) [default=10].
.. py:attribute:: xsh_cfg_recover.param.peak_match_y

    Radii for line peaks matches (int; default: 20) [default=20].
.. py:attribute:: xsh_cfg_recover.param.pm_ord_sel

    From guess line and peaks positions are extracted the ones in the  range [ord_min,ord_min+pm_ord_sel]  (int; default: 1) [default=1].
.. py:attribute:: xsh_cfg_recover.param.pm_radius

    Search radius applied in final pattern matching (data units). (float;  default: 20.0) [default=20.0].
.. py:attribute:: xsh_cfg_recover.param.pm_tolerance

    Max relative difference of angles and scales from their median value  for match acceptance. (float; default: 0.1) [default=0.1].
.. py:attribute:: xsh_cfg_recover.param.anneal_niter

    Simulated annealing iterations (int; default: 1000) [default=1000].


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

::

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

   xsh_cfg_recover.param.keep_temp = "no"
   xsh_cfg_recover.param.debug_level = "none"
   xsh_cfg_recover.param.time_stamp = False
   xsh_cfg_recover.param.decode_bp = 2144337919
   xsh_cfg_recover.param.first_anneal = False
   xsh_cfg_recover.param.arm = "vis"
   xsh_cfg_recover.param.name_i = "line_xy_ord.txt"
   xsh_cfg_recover.param.niter = 100000
   xsh_cfg_recover.param.coord_frame = 1
   xsh_cfg_recover.param.last_step = False
   xsh_cfg_recover.param.plot = False
   xsh_cfg_recover.param.ima_tresh_min = 40.0
   xsh_cfg_recover.param.cor_prescan = False
   xsh_cfg_recover.param.method = "safefit"
   xsh_cfg_recover.param.offx = 0.0
   xsh_cfg_recover.param.offy = 0.0
   xsh_cfg_recover.param.slit = 5
   xsh_cfg_recover.param.gfit_box_sy = 20
   xsh_cfg_recover.param.peak_line_fwhm = 4
   xsh_cfg_recover.param.peak_kappa = 5.0
   xsh_cfg_recover.param.peak_factor = 10.0
   xsh_cfg_recover.param.peak_match_x = 10
   xsh_cfg_recover.param.peak_match_y = 20
   xsh_cfg_recover.param.pm_ord_sel = 1
   xsh_cfg_recover.param.pm_radius = 20.0
   xsh_cfg_recover.param.pm_tolerance = 0.1
   xsh_cfg_recover.param.anneal_niter = 1000


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

::

   import cpl
   xsh_cfg_recover = cpl.Recipe("xsh_cfg_recover")
   [...]
   res = xsh_cfg_recover( ..., 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 `A. Modigliani, P. Bristow <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:: A. Modigliani, P. Bristow <amodigli@eso.org>
