.. highlight:: rest

.. _configobj: http://configobj.readthedocs.io/en/latest/

.. _pypeitpar:

=================
PypeIt Parameters
=================

PypeIt allows you to customize its execution without having to change the
code directly.

Although not ubiquitous, most optional arguments of PypeIt's algorithms
are contained within the :class:`pypeit.par.pypeitpar.PypeItPar`
superset.  PypeIt uses the `configobj`_ class to parse the user-supplied
arguments  in the :ref:`pypeit_file` into an instance of
:class:`pypeit.par.pypeitpar.PypeItPar` that is passed to all of
PypeIt's main modules.  The syntax used to set parameters using the
:ref:`pypeit_file` is important and the nesting of the parameter changes
must match the `Current PypeItPar Parameter Hierarchy`_.

Importantly, each instrument served provides its own default values for
:class:`pypeit.par.pypeitpar.PypeItPar` as defined by its
``default_pypeit_par`` method; e.g.,
:func:`pypeit.spectrographs.shane_kast.ShaneKastSpectrograph.default_pypeit_par`.
Only those parameters that the user wishes to be different from the
default *as set by their specified instrument* need to be changed via
the :ref:`pypeit_file`.  The `Instrument-Specific Default
Configuration`_ are listed below.

.. warning::

 * Default values of parameters that actually point to data files
   provided by PypeIt (e.g. the ``spectrum`` parameter for
   :class:`pypeit.par.pypeitpar.FlexurePar`) in its root directory will
   point to the relevant location on disk of whoever generated the
   documentation, which will be different for your installation.

.. _change_par:

How to change a parameter
=========================

To change a parameter, set its value at the beginning of your pypeit
file.  The *syntax* of the configuration block is important, but the
indentation is not.  The indentation will just make the block easier to
read.  All PypeIt files begin with the lines that set the spectrograph::

    [rdx]
        spectrograph = keck_deimos

The nesting of the PypeIt parameters is as illustrated in the `Current
PypeItPar Parameter Hierarchy`_ section below.  Here are a few examples
of how to change various parameters; for additional examples see the
`Instrument-Specific Default Configuration`_ section.

 * To change the threshold used for detecting slit/order edges, add::

    [calibrations]
        [[slitedges]]
            edge_thresh = 100

 * To change the exposure time range used to identify an arc and
   flat-field frames and to increase the LA Cosmic sigma-clipping
   threshold for arc frames, add::

    [calibrations]
        [[arcframe]]
            exprng = None,10
            [[process]]
                sigclip = 6.
        [[pixelflatframe]]
            exprng = 11,30

How to change the image processing parameters for all frame types
=================================================================

To change the base-level image processing parameters that will be
applied to *all* frame types, you can use the ``baseprocess`` parameter
group.  This allows you to set these parameters once instead of having
to include lines in your PypeIt file for each frame type.  Any
frame-type-specific alterations can still be made and will overwrite the
base-level processing parameters.  For example, to change the
sigma-clipping level used by the LA Cosmic routine to default to 3.0 but
to use a value of 6.0 for arc frames, you can add the following to your
PypeIt file::

    [baseprocess]
        sigclip = 3.0
    [calibrations]
        [[arcframe]]
            [[[process]]]
                sigclip = 6.0

