The uves_cal_orderpos recipe
===============================================================

.. data:: uves_cal_orderpos

Synopsis
--------

Defines echelle order positions

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

The recipe defines the order positions in an echelle image. The orders are
initially detected by means of a Hough transformation, the orders are then 
traced, and the positions are finally fitted with a global polynomial.


Expected input frames are narrow flat fields, ORDER_FLAT_xxx, or standard 
stars, STANDARD_xxx, where xxx is 'BLUE' or 'RED', and optionally for each 
chip a DRS setup table (DRS_TABLE_BLUE, DRS_TABLE_REDL, DRS_TABLE_REDU) or 
guess order table (ORDER_GUESS_TAB_BLUE, ORDER_GUESS_TAB_REDL, 
ORDER_GUESS_TAB_REDU, 
or, for backward compatibility, ORDER_TABLE_BLUE, ORDER_TABLE_REDL, 
ORDER_TABLE_REDU). The recipe processes only the first raw frame found.


Output is one (or two if input is a red frame) order table(s) 
(UVES: ORDER_TABLE_(BLUE|REDL|REDU); FLAMES: FIB_ORDEF_(REDL|REDU) contaning
the columns:

::

  X                : Position along x
  Order            : Relative order number
  Y                : Order line centroid location
  Yfit             : The fitted order location
  dY               : Uncertainty of Y
  dYfit_Square     : Variance of Yfit
  Residual         : Y - Yfit
  Residual_Square  : Residual^2
  OrderRMS         : Root mean squared residual of initial
                     one-dimensional linear fit of order

The bivariate fit polynomial itself is stored in table extension no. 2.
The 3rd table extension contains a table that defines the active fibre traces
and their positions (for support of FLAMES/UVES)

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

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

   Create an object for the recipe uves_cal_orderpos.

::

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

Parameters
----------

.. py:attribute:: uves_cal_orderpos.param.debug

    Whether or not to save intermediate results to local directory (bool;  default: False) [default=False].
.. py:attribute:: uves_cal_orderpos.param.plotter

    Any plots produced by the recipe are redirected to the command  specified by this parameter. The plotting command must contain the  substring 'gnuplot' and must be able to parse gnuplot syntax on its  standard input. Valid examples of such a command may include 'gnuplot  -persist' and 'cat > mygnuplot$$.gp'. A finer control of the plotting  options can be obtained by writing an executable script, e.g.  my_gnuplot.pl, that executes gnuplot after setting the desired gnuplot  options (e.g. set terminal pslatex color). To turn off plotting, set  this parameter to 'no' (str; default: 'no') [default="no"].
.. py:attribute:: uves_cal_orderpos.param.process_chip

    For RED arm data process the redl, redu, or both chip(s) (str;  default: 'both') [default="both"].
.. py:attribute:: uves_cal_orderpos.param.use_guess_tab

    If a Guess order table is provided this parameter set how it is  used:0: No usage, 1: use it to set lower/upper Y raws where order are  searched 2: the order table try to fully match the guess (long;  default: 1) [default=1].
.. py:attribute:: uves_cal_orderpos.param.radx

    Half X size of median filtering window (long; default: 2) [default=2].
.. py:attribute:: uves_cal_orderpos.param.rady

    Half Y size of median filtering window (long; default: 1) [default=1].
.. py:attribute:: uves_cal_orderpos.param.mmethod

    Background subtraction method. If equal to 'median' the background is  sampled using the median of a sub-window. If 'minimum', the minimum  sub-window value is used. If 'no', no background subtraction is done.  (str; default: 'median') [default="median"].
.. py:attribute:: uves_cal_orderpos.param.backsubgrid

    Number of grid points (in x- and y-direction) used to estimate the  background (mode=poly). (long; default: 50) [default=50].
.. py:attribute:: uves_cal_orderpos.param.backsubradiusy

    The height (in pixels) of the background sampling window is (2*radiusy  + 1). This parameter is not corrected for binning. (long; default: 2) [default=2].
.. py:attribute:: uves_cal_orderpos.param.backsubkappa

    The value of kappa in the one-sided kappa-sigma clipping used to  estimate the background (mode=poly). (float; default: 4.0) [default=4.0].
.. py:attribute:: uves_cal_orderpos.param.backsubdegx

    Degree (in x) of polynomial used to estimate the background  (mode=poly). (long; default: 2) [default=2].
.. py:attribute:: uves_cal_orderpos.param.backsubdegy

    Degree (in y) of polynomial used to estimate the background  (mode=poly). (long; default: 2) [default=2].
.. py:attribute:: uves_cal_orderpos.param.samplewidth

    Separation of sample traces (used by Hough transform) in input image  (long; default: 50) [default=50].
.. py:attribute:: uves_cal_orderpos.param.minslope

    Minimum possible line slope. This should be the 'physical' slope on  the chip, i.e. not taking binning factors into account, which is  handled by the recipe (float; default: 0.0) [default=0.0].
.. py:attribute:: uves_cal_orderpos.param.maxslope

    Maximum possible line slope (float; default: 0.2) [default=0.2].
.. py:attribute:: uves_cal_orderpos.param.sloperes

    Resolution (width in pixels) of Hough space (long; default: 120) [default=120].
.. py:attribute:: uves_cal_orderpos.param.pthres

    In automatic mode, or if the number of orders to detect is read from a  guess table, the detection of new lines stops when the intensity of a  candidate line drops to less than 'pthres' times the intensity of the  previous detection.  (float; default: 0.2) [default=0.2].
.. py:attribute:: uves_cal_orderpos.param.tracestep

    The step size used when tracing the orders (long; default: 10) [default=10].
.. py:attribute:: uves_cal_orderpos.param.minthresh

    The minimum threshold value is (min + minthres*(max - min)). Here  'min' and 'max' are the lowest and highest pixel values in the central  bin of the order (float; default: 0.2) [default=0.2].
.. py:attribute:: uves_cal_orderpos.param.maxgap

    If the order line drops below detection threshold, the order tracing  algorithm will try to jump a gap of maximum size 'maxgap' multiplied  by the image width (float; default: 0.2) [default=0.2].
.. py:attribute:: uves_cal_orderpos.param.maxrms

    When fitting the orders with straight lines, this is the maximum  allowed RMS relative to the median RMS of all orders (float; default:  100.0) [default=100.0].
.. py:attribute:: uves_cal_orderpos.param.defpol1

    The degree of the bivarite fit (cross dispersion direction). If  negative, the degree is optimized to give the best fit (long; default:  -1) [default=-1].
.. py:attribute:: uves_cal_orderpos.param.defpol2

    The degree of the bivarite fit (order number). If negative, the degree  is optimized to give the best fit (long; default: -1) [default=-1].
.. py:attribute:: uves_cal_orderpos.param.kappa

    Used for kappa-sigma clipping of the final polynomial fit. If  negative, no clipping is done (float; default: 4.0) [default=4.0].


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

::

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

   uves_cal_orderpos.param.debug = False
   uves_cal_orderpos.param.plotter = "no"
   uves_cal_orderpos.param.process_chip = "both"
   uves_cal_orderpos.param.use_guess_tab = 1
   uves_cal_orderpos.param.radx = 2
   uves_cal_orderpos.param.rady = 1
   uves_cal_orderpos.param.mmethod = "median"
   uves_cal_orderpos.param.backsubgrid = 50
   uves_cal_orderpos.param.backsubradiusy = 2
   uves_cal_orderpos.param.backsubkappa = 4.0
   uves_cal_orderpos.param.backsubdegx = 2
   uves_cal_orderpos.param.backsubdegy = 2
   uves_cal_orderpos.param.samplewidth = 50
   uves_cal_orderpos.param.minslope = 0.0
   uves_cal_orderpos.param.maxslope = 0.2
   uves_cal_orderpos.param.sloperes = 120
   uves_cal_orderpos.param.pthres = 0.2
   uves_cal_orderpos.param.tracestep = 10
   uves_cal_orderpos.param.minthresh = 0.2
   uves_cal_orderpos.param.maxgap = 0.2
   uves_cal_orderpos.param.maxrms = 100.0
   uves_cal_orderpos.param.defpol1 = -1
   uves_cal_orderpos.param.defpol2 = -1
   uves_cal_orderpos.param.kappa = 4.0


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

::

   import cpl
   uves_cal_orderpos = cpl.Recipe("uves_cal_orderpos")
   [...]
   res = uves_cal_orderpos( ..., param = {"debug":False, "plotter":"no"})


.. 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 `Jonas M. Larsen <cpl@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 FLAMES/UVES Pipeline
Copyright (C) 2004, 2005, 2006, 2007 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:: Jonas M. Larsen <cpl@eso.org>
