API
===




.. _api-myxclass:

myXCLASS
--------


.. code:: python

    # import myXCLASS function
    from xclass import task_myXCLASS

    myXCLASSCore(MolfitsFileName = "",
                 MolfitFileName = None,
                 ObsXMLFileName = None,
                 FreqMin = 1.0,
                 FreqMax = 1.e8,
                 FreqStep = 1.0,
                 TelescopeSize = None,
                 BMIN = None,
                 BMAJ = None,
                 BPA = None,
                 Redshift = None,
                 Inter_Flag = False,
                 t_back_flag = True,
                 tBack = 0.0,
                 tSlope = 0.0,
                 N_H = 0.0,
                 beta_dust = 0.0,
                 kappa_1300 = 0.0,
                 DustFileName = "",
                 BackgroundFileName = "",
                 ContPhenFuncID = None,
                 ContPhenFuncParam1 = None,
                 ContPhenFuncParam2 = None,
                 ContPhenFuncParam3 = None,
                 ContPhenFuncParam4 = None,
                 ContPhenFuncParam5 = None,
                 NumModelPixelXX = 100,
                 NumModelPixelYY = 100,
                 LocalOverlapFlag = False,
                 NoSubBeamFlag = False,
                 dbFileName = "",
                 CheckMoleculeInDB = True,
                 RestFreq = 0.0,
                 vLSR = 0.0,
                 EmAbsFlag = False,
                 EmAbsPATH = None,
                 printFlag = None,
                 SpectrumOnlyFlag = False)


The function models a spectrum by solving the radiative transfer
equation for an isothermal object in one dimension, called detection
equation.

The files produced by a **myXCLASS** function call are copied to a
so-called "``job-directory``" located in the *XCLASS* interface working
directory ``path-of-XCLASS/run/myXCLASS/``! The name of a job
directory for a **myXCLASS** run is made up of four components: The
first part consists of the phrase “``job_``” whereas the second and
third part describe the date and the time stamp (hours, minutes,
seconds) of the function execution, respectively. The last part
indicates a so-called job ID which is composed of the so-called PID
followed by a four digit random integer number to create a really
unambiguous job number, e.g.

::

   path-of-XCLASS/run/myXCLASS/job__25-07-2013__12-02-03__189644932/


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``MolfitsFileName``: path and name of the molfit file, see
   Sect. ":ref:`myxclass-molfit`".
   |br| |br|

-  ``MolfitFileName``: (optional) alias of ``MolfitsFileName``,
   (default: ``None``).
   |br| |br|

-  ``ObsXMLFileName``: (optional) path and name of an obs. xml file,
   (default: ``None``), see Sect. ":ref:`myxclassfit-obs-xml-file`"
   for a detailed description. The obs. xml file can be used to
   create a synthetic spectrum for each frequency range.

   Note, the name of the xml file has to end with ``".xml"``.
   |br| |br|

-  ``FreqMin``: start frequency of simulated spectrum (in MHz),
   (default: 1).
   |br| |br|

-  ``FreqMax``: end frequency of simulated spectrum (in MHz),
   (default: :math:`10^8`).
   |br| |br|

-  ``FreqStep``: step frequency of simulated spectrum (in MHz),
   (default: 1).
   |br| |br|

-  ``vLSR``: velocity (local standard of rest) in km s\ :math:`^{-1}`
   (default: 0) used in the calculation of the synthetic spectra, i.e.
   all velocity offsets described in the molfit file have to be defined
   relative to the v\ :math:`_{\rm LSR}` parameter. For example, the
   user defines v\ :math:`_{\rm LSR}` = 20 km/s, and the molfit file
   describes CH\ :math:`_3`\ CN with one component and
   v\ :math:`_{\rm off}^{\rm molfit}` = 2 km/s, *XCLASS* uses
   v\ :math:`_{\rm off}` = v\ :math:`_{\rm LSR}` +
   v\ :math:`_{\rm off}^{\rm molfit}` = 20 km/s + 2 km/s = 22 km/s for
   the calculation of the spectra.

   Additionally, *XCLASS* considers the v\ :math:`_{\rm LSR}` parameter
   for the determination of the transition frequencies contained in the
   database: For each frequency range, *XCLASS* shifts the lowest and
   highest frequency by v\ :math:`_{\rm LSR}` (e.g. to describe lines in
   high-red-shifted galaxies) and expands each range by taking the
   lowest and highest velocity offset defined in the molfit file into
   account. This offers the possibility to describe lines which are
   located at the edges of the frequency ranges.
   |br| |br|

-  ``TelescopeSize``: for single dish observations
   (``Inter_Flag = False``): ``TelescopeSize`` describes the size of
   telescope (in m), (default: 1); for interferometric observations
   (``Inter_Flag = True``): ``TelescopeSize`` describes the
   interferometric beam FWHM size (in arcsec), (default: 1).
   |br| |br|

-  ``BMIN``: (optional) Beam minor axis length (in arsec)
   (default: ``None``), see Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

-  ``BMAJ``: (optional) Beam major axis length (in arsec)
   (default: ``None``), see Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

-  ``BPA``: (optional) Beam position angle (in degree)
   (default: ``None``), see Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

-  ``Redshift``: (optional) red shift (dimensionless),
   (default: ``None``) NOT YET AVAILABLE!
   |br| |br|

-  ``Inter_Flag`` (``True``/``False``): defines, if single dish
   (``False``) or interferometric observations (``True``) are described,
   (default: ``False``).
   |br| |br|

-  ``t_back_flag`` (``True``/``False``): defines, if the user defined
   background temperature :math:`T_{\rm bg}` and temperature slope
   :math:`T_{\rm slope}` given by the input parameters ``tBack`` and
   ``tSlope`` describe the continuum contribution completely
   (``t_back_flag = True``) or not (``t_back_flag = False``)
   (default: ``True``).
   |br| |br|

-  ``tBack`` background temperature (in K), (default: 0).
   |br| |br|

-  ``tSlope`` temperature slope (dimensionless), (default: 0).
   |br| |br|

-  ``BackgroundFileName`` (optional) path and name of file describing
   the background as function of frequency (in MHz),
   (default: ``None``).
   |br| |br|

-  ``N_H`` (optional) Hydrogen column density (in cm\ :math:`^{-2}`),
   (default: 0.0), see Sect. ":ref:`mxclass-contDust`".
   |br| |br|

-  ``beta_dust`` (optional) spectral index for dust (dimensionless),
   (default: 0.0), see Sect. ":ref:`mxclass-contDust`".
   |br| |br|

-  ``kappa_1300`` (optional) kappa at 1.3 mm
   (cm\ :math:`^2 \,`\ g\ :math:`^{-1}`), (default: 0.0), see
   Sect. ":ref:`mxclass-contDust`".
   |br| |br|

-  ``DustFileName`` (optional) path and name of file describing optical
   depth of dust as function of frequency (in MHz), (default: ``None``),
   see Sect. ":ref:`mxclass-contDust`".
   |br| |br|

-  ``ContPhenFuncID``: (optional) describes which phenomenological
   function is used to describe the continuum (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``ContPhenFuncParam1``: (optional) first parameter for
   phenomenological function describing the continuum
   (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``ContPhenFuncParam2``: (optional) second parameter for
   phenomenological function describing the continuum
   (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``ContPhenFuncParam3``: (optional) third parameter for
   phenomenological function describing the continuum
   (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``ContPhenFuncParam4``: (optional) fourth parameter for
   phenomenological function describing the continuum
   (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``ContPhenFuncParam5``: (optional) fifth parameter for
   phenomenological function describing the continuum
   (default: ``None``), see
   Sect. ":ref:`mxclass-contPhen`".
   |br| |br|

-  ``iso_flag``: use isotopologues (``True``/``False``). If ``iso_flag``
   is set to ``True`` isotopologues defined in the iso ratio file are
   used (default: ``False``).
   |br| |br|

-  ``IsoTableFileName``: (has to be given only if ``iso_flag`` is set to
   ``True``): path and file name of an ASCII file including the iso
   ratios between certain molecules. The so-called "iso ratio file"
   defines the iso ratios between molecules. The ASCII file consists of
   three columns, where the first two columns indicates the molecules,
   respectively. The third column defines the ratio for both molecules.
   The columns are separated by blanks or tabs. So, the names of the
   molecules must not contain blanks. Comments have to be marked with
   the "%" sign, i.e. all characters on the right side of a "%" sign are
   ignored.

   The **myXCLASSFit** function offers the possibility to optimize the
   ratios between isotopologues as well. For that purpose, the user has
   to add two additional columns on the right indicating the lower and
   the upper limit of a certain ratio, respectively. A detailed
   description of the iso ratio file is given in
   Sect. ":ref:`myxclass-iso`".
   |br| |br|

-  ``NumModelPixelXX``: (optional) used for sub-beam modeling, describes
   the number of model pixels used in x-direction (default: 100), see
   Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

-  ``NumModelPixelYY``: (optional) used for sub-beam modeling, describes
   the number of model pixels used in y-direction (default: 100), see
   Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

-  ``LocalOverlapFlag`` (``True``/``False``): (optional) take local
   overlap into account (default: ``False``), see
   Sect. ":ref:`myxclass-localoverlap`".
   |br| |br|

-  ``NoSubBeamFlag`` (``True``/``False``): (optional) do not use
   sub-beam description into (default: ``False``), see
   Sect. ":ref:`myxclass-molfit-subbeam`",
   i.e. *XCLASS* uses the old source description, see
   Sect. ":ref:`myxclass-molfit-1d`".
   |br| |br|

-  ``dbFilename``: (optional) path and name of a database file, which is
   used instead of the default file ``cdms_sqlite.db`` stored in
   directory ``Database/``, (default: ``None``).
   |br| |br|

-  ``RestFreq``: rest frequency in MHz (default: 0). (If this parameter
   is unequal zero, the intensity is also plotted against velocity (in
   km s\ :math:`^{-1}`) using parameter ``vLSR``, see above.
   |br| |br|

-  ``EmAbsFlag`` (``True``/``False``): (optional) flag indicating that
   emission and absorption as function of frequency are stored
   (default: ``False``)
   |br| |br|

-  ``EmAbsPATH``: (optional) path containing files describing functions
   emission / absorption (default: ``None``).
   |br| |br|

-  ``CheckMoleculeInDB`` (``True``/``False``): (optional) check, if
   molecules included in molfit file have transitions within given
   frequency range (default: ``True``)
   |br| |br|

-  ``printFlag`` (``True``/``False``): (optional) flag for printing
   messages to the screen (default: ``True``)
   |br| |br|

-  ``SpectrumOnlyFlag`` (``True``/``False``): (optional) flag indicating
   that only the spectra (and no optical depth etc.) are calculated
   (default: ``False``)


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``myXCLASSspectrum``: contains the calculated **myXCLASS** spectrum

   If ``RestFreq`` is unequal zero, the **myXCLASS** function adds a
   column to the output parameter ``myXCLASSspectrum`` which contains
   the velocities. So, for a rest frequency unequal zero, the parameter
   ``myXCLASSspectrum`` represents a python array with three columns,
   where the first column describes the frequencies, the second column
   describes the velocities and the third column the corresponding
   intensities.
   |br| |br|

-  ``myXCLASSlog``: contains the corresponding log file
   |br| |br|

-  ``myXCLASSTrans``: (python) list containing the transition
   frequencies (in MHz) from the last **myXCLASS** run, the
   Doppler-shifted transition frequencies (in MHz), the corresponding
   absolute and integrated intensities (in K), the energy of the lower
   level (in K and K MHz), the upper state degeneracy, the Einstein A
   coefficient (in s\ :math:`^{-1}`), and the molecule names within the
   defined range
   |br| |br|

-  ``myXCLASSIntOptical``: contains intensities and optical depths for
   each molecule and component. Depending on the local-overlap flag,
   i.e. if local-overlap is taken into account or not, the intensities
   and optical depths are given for each component or for each distance,
   see Sect. ":ref:`myxclass-localoverlap`".

   The intensities and optical depths are stored as follows:

   -  ``myXCLASSIntOptical[0]``, contains all information about the
      intensities

      -  ``myXCLASSIntOptical[0][i][0]`` contains the name of the
         :math:`i`\ th molecule

      -  ``myXCLASSIntOptical[0][i][1]`` contains the index of the
         component of the :math:`i`\ th molecule

      -  ``myXCLASSIntOptical[0][i][2]`` contains the intensities of
         the :math:`i`\ th molecule as a 2D numpy array. Please note,
         the intensities for each core component
         :math:`\left[T_{\rm mb}^{i=1}\right]^{m,c}(\nu)` and
         :math:`\left[T_{\rm mb}^{i>1}\right]^{m,c}(\nu)` are given by
         different expression, depending if local-overlap is taken
         into account or not.

         If local-overlap is not taken into account, the intensities
         :math:`\left[T_{\rm mb}^{i=1}\right]^{m,c}(\nu)` for
         components contained in the layer which is closest to the
         background is

         .. math::

            \left[T_{\rm mb}^{i=1}\right]^{m,c}(\nu) &= \Bigg[\eta \left(\theta^{m,c}\right) \left[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + I_{\rm bg} (\nu) \left(e^{-\tau_{\rm total}^{m,c}(\nu)} - 1\right)\right]\Bigg] \\
                                                      & \qquad + \frac{1}{N_{\rm all}^{i=1}} \, \left[I_{\rm bg} (\nu) - J_\mathrm{CMB} \right],

         where :math:`N_{\rm all}^{i=1}` indicates the number of all
         components of all molecules located in this layer. The
         intensities of components
         :math:`\left[T_{\rm mb}^{\rm i > 1}\right]^{m,c}` with
         smaller distances are given by

         .. math::

            \left[T_{\rm mb}^{i > 1}\right]^{m,c}(\nu) = \Big[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + \left[T_{\rm mb}^{(i - 1)}\right]^{m,c} e^{-\tau_{\rm total}^{m,c}(\nu)}\Big].

         If local-overlap is taken into account, the expression for
         :math:`\left[T_{\rm mb}^{i=1}\right]^{m,c}(\nu)` is slightly
         different

         .. math::
            :label: myXCLASS:modelEmComp

            \left[T_{\rm mb}^{i=1}\right]^{m,c}(\nu) &= \sum_{m,c \in i} \Bigg[\eta \left(\theta^{m,c}\right) \left[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + I_{\rm bg} (\nu) \left(e^{-\tau_{\rm total}^{m,c}(\nu)} - 1\right)\right]\Bigg] \\
                                                     & \qquad + \frac{1}{N_{\rm all}^{i=1}} \, \left[I_{\rm bg} (\nu) - J_\mathrm{CMB} \right].

         Additionally, the intensities for components at smaller
         distances :math:`\left[T_{\rm mb}^{\rm i > 1}\right]^{m,c}` are
         given by

         .. math::
            :label: myXCLASS:modelAbsComp

            \left[T_{\rm mb}^{i > 1}\right]^{m,c}(\nu) = \sum_{m,c \in i} \Big[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + \left[T_{\rm mb}^{(i - 1)}\right]^{m,c} e^{-\tau_{\rm total}^{m,c}(\nu)}\Big].

      -  ``myXCLASSIntOptical[0][i][3]`` contains the integrated
         intensities of the :math:`i`\ th molecule.
         |br| |br|

   -  ``myXCLASSIntOptical[1]``, contains all information about the
      optical depths.

      -  ``myXCLASSIntOptical[1][i][0]`` contains the name of the
         :math:`i`\ th molecule

      -  ``myXCLASSIntOptical[1][i][1]`` contains the index of the
         component of the :math:`i`\ th molecule

      -  ``myXCLASSIntOptical[1][i][2]`` contains the optical depth of
         the :math:`i`\ th molecule as a 2D numpy array. In general, the
         optical depths are given by

         .. math:: \tau_l^{m,c}(\nu) = \sum_t \tau_t^{m,c}(\nu),

         where the sum runs over all transition :math:`t` of a certain
         component (if local-overlap is not taken into account) or over
         all transitions of components, which belongs to the same
         distances (if local-overlap is taken into account).
         |br| |br|

-  ``myXCLASSJobDir``: absolute path of the job directory created for
   the current run
   |br| |br|

Note, the user is free to define different names for the output
parameters. In the example describe below, we use the name
``"modeldata"`` for output parameter ``myXCLASSspectrum``, ``"log"``
for output parameter ``myXCLASSlog``, ``"TransEnergies"`` for output
parameter ``myXCLASSTrans``, ``"IntOptical"`` for output parameter
``myXCLASSIntOptical``, and ``"jobDir"`` for output parameter
``myXCLASSJobDir``.
|br| |br|



.. ----------------------------------------------------------------------------------------



.. _api-myxclassfit:

myXCLASSFit
-----------


.. code:: python

    # import myXCLASSFit function
    from xclass import task_myXCLASSFit

    task_myXCLASSFit.myXCLASSFitCore(MolfitsFileName = "",
                                     MolfitFileName = None,
                                     NumberIteration = 10,
                                     AlgorithmXMLFileName = "",
                                     ObsXMLFileName = "",
                                     ObsDataFileName = None,
                                     experimentalData = None,
                                     observationalData = None,
                                     Optimizer = "magix",
                                     FastFlag = False,
                                     ChannelIntegrationFlag = True,
                                     TelescopeSize = None,
                                     BMIN = None,
                                     BMAJ = None,
                                     BPA = None,
                                     Redshift = 0.0,
                                     Inter_Flag = False,
                                     t_back_flag = True,
                                     tBack = 0.0,
                                     tSlope = 0.0,
                                     BackgroundFileName = "",
                                     N_H = 0.0,
                                     beta_dust = 0.0,
                                     kappa_1300 = 0.0,
                                     DustFileName = "",
                                     ContPhenFuncID = None,
                                     ContPhenFuncParam1 = None,
                                     ContPhenFuncParam2 = None,
                                     ContPhenFuncParam3 = None,
                                     ContPhenFuncParam4 = None,
                                     ContPhenFuncParam5 = None,
                                     iso_flag = False,
                                     IsoTableFileName = "",
                                     EmAbsPATH = None,
                                     NoSubBeamFlag = None,
                                     NumModelPixelXX = 100,
                                     NumModelPixelYY = 100,
                                     LocalOverlapFlag = None,
                                     RestFreq = 0.0,
                                     vLSR = 0.0,
                                     DictOutFlag = False)



For each run the **myXCLASSFit** function creates a so-called job
directory located in the run directory
(``path-of-XCLASS-run/myXCLASSFit/``) where all files created by the
**myXCLASSFit** function are stored in. The name of this job directory
is made up of four components: The first part consists of the phrase
“``job_``” whereas the second and third part describe the date (day,
month, year) and the time stamp (hours, minutes, seconds) of the
function execution, respectively. The last part indicates a so-called
job ID which is composed of the so-called PID followed by a four digit
random integer number to create a really unambiguous job number, e.g.
``/path-of-XCLASS-run/myXCLASSFit/job__25-07-2013__12-02-03__189644/``.

Before the fit procedure starts, the function copies the molfit, the
observational data, and xml-files to the myXCLASSFit job directory. The
path(s) defined in the observational xml-file are adjusted so that these
paths point to the current myXCLASSFit job directory.

Please note, that the original observational xml- and data files are not
modified. Only the copy of the observational xml file located in the
myXCLASSFit job directory is modified!

If no observational xml-file is defined, the **myXCLASSFit** function
creates an observational xml-file containing the settings for the
different parameters in the myXCLASSFit job directory. Additionally, the
function creates an ASCII file located in the myXCLASSFit job directory
containing the observational data given by the parameter
``"observationalData"``. If the parameter ``"observationalData"``
defines the path and the name of an observational data file, then the
data file is copied to the myXCLASSFit job directory as well. The path
and the name of this ASCII file is pasted in the created observational
xml file. Furthermore, the function creates automatically the algorithm
and i/o control xml files, need by MAGIX, so that the user does not need
to edit any xml-file.

Additionally, the **myXCLASSFit** function converts the column density
:math:`N_{\rm tot}` (and if the hydrogen column density :math:`N_H` is
given for each component) the hydrogen column density :math:`N_H` as
well to a log scale, i.e. these two densities are converted
automatically to their log10 values to get a better fit. At the end of
the fitting process, the log10 values are converted back to the
original linear values. So, the MAGIX log files contain the log10
values of these parameters, whereas the input and output molfit file
contain the linear values, respectively.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``MolfitsFileName``: path and name of the (extended) molfit file, see
   Sect. ":ref:`myxclass-molfit`"
   |br| |br|

-  ``MolfitFileName``: (optional) alias of ``MolfitsFileName``,
   (default: ``None``).
   |br| |br|

-  ``AlgorithmXMLFileName``: (optional) path and name of an algorithm
   xml-file describing settings for an algorithm or algorithm chain, see
   Sect. ":ref:`myxclassfit-alg-xml-file`".

   NOTE, if the user specify a xml file, the number of iterations given
   by the parameter ``NumberIteration`` is ignored. The number of
   iteration is then given by the xml file.
   |br| |br|

-  ``NumberIteration``: max. number of iterations (default: 10). (This
   parameter is ignored if a algorithm xml file is defined). If parameter
   ``Optimizer``, see below, is set to ``'magix'``, the Levenberg-Marquardt
   algorithm, otherwise the trf algorithm is used.
   |br| |br|

-  ``ObsXMLFileName``: (optional) path and name of an obs. xml file
   (recommended procedure), (default: ``""``), see Sect.
   ":ref:`myxclassfit-obs-xml-file`" for a detailed description.

   Note, the name of the xml file has to end with ``".xml"``.
   |br| |br|

-  ``ObsDataFileName``: (optional) describes the observational data, if
   no obs. xml file is given, (default: ``None``). There are two options
   for transferring the data to XCLASS:

   -  the parameter describes path and name of an ASCII file
      called observational data file, where the first column describe
      the frequency (in MHz) and the second column the brightness
      temperature (in Kelvin)

      Please note, without using an obs. xml file, it is not possible
      to fit more than one data cube, simultaneously.

   -  the parameter describes a 2d numpy array, where the first column
      describes the frequency (in MHz) and the second column the brightness
      temperature (in Kelvin).
      |br| |br|

-  ``experimentalData``: (optional) alias of ``ObsDataFileName``,
   (default: ``None``)
   |br| |br|

-  ``observationalData``: is deprecated.
   |br| |br|

The following parameters are needed, if parameter ``ObsDataFileName`` is
used instead of parameter ``ObsXMLFileName``:

-  ``vLSR``: source velocity (local standard of rest) in km s\ :math:`^{-1}`
   (default: 0).
   |br| |br|

-  ``TelescopeSize``: for single dish observations
   (``Inter_Flag = False``): ``TelescopeSize`` describes the size of
   telescope (in m), (default: 1); for interferometric observations
   (``Inter_Flag = True``): ``TelescopeSize`` describes the
   interferometric beam FWHM size (in arcsec), (default: 1).
   |br| |br|

-  ``BMIN``: (optional) Beam minor axis length (in arcsec)
   (default: ``None``)
   |br| |br|

-  ``BMAJ``: (optional) Beam major axis length (in arcsec)
   (default: ``None``)
   |br| |br|

-  ``BPA``: (optional) Beam position angle (in degree)
   (default: ``None``)
   |br| |br|

-  ``Redshift``: (optional) red shift (dimensionless),
   (default: ``None``)
   |br| |br|

-  ``Inter_Flag`` (``True``/``False``): defines, if single dish
   (``False``) or interferometric observations (``True``) are described,
   (default: ``False``).
   |br| |br|

-  ``t_back_flag`` (``True``/``False``): defines, if the user defined
   background temperature :math:`T_{\rm bg}` and temperature slope
   :math:`T_{\rm slope}` given by the input parameters ``tBack`` and
   ``tSlope`` describe the continuum contribution completely
   (``t_back_flag = True``) or not (``t_back_flag = False``)
   (default: ``True``).
   |br| |br|

-  ``tBack`` background temperature (in K), (default: 0).
   |br| |br|

-  ``tSlope`` temperature slope (dimensionless), (default: 0).
   |br| |br|

-  ``BackgroundFileName`` (optional) path and name of file describing
   the background as function of frequency (in MHz),
   (default: ``None``).
   |br| |br|

-  ``N_H`` (optional) Hydrogen column density (in cm\ :math:`^{-2}`),
   (default: ``None``).
   |br| |br|

-  ``beta_dust`` (optional) spectral index for dust (dimensionless),
   (default: ``None``).
   |br| |br|

-  ``kappa_1300`` (optional) kappa at 1.3 mm
   (cm\ :math:`^2 \,`\ g\ :math:`^{-1}`), (default: ``None``).
   |br| |br|

-  ``DustFileName`` (optional) path and name of file describing dust
   contribution (default: ``""``).
   |br| |br|

-  ``ContPhenFuncID``: (optional) describes which phenomenological
   function is used to describe the continuum (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam1``: (optional) first parameter for
   phenomenological function describing the continuum
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam2``: (optional) second parameter for
   phenomenological function describing the continuum
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam3``: (optional) third parameter for
   phenomenological function describing the continuum
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam4``: (optional) fourth parameter for
   phenomenological function describing the continuum
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam5``: (optional) fifth parameter for
   phenomenological function describing the continuum
   (default: ``None``).
   |br| |br|

-  ``iso_flag``: use isotopologues (``True``/``False``). If the flag is
   set to ``True`` isotopologues defined in the iso ratio file are taken
   into account, (default: ``False``).
   |br| |br|

-  ``IsoTableFileName`` (has to be given only if ``iso_flag`` is set to
   ``True``): path and name of an ASCII file including the iso ratios
   between certain molecules. A detailed description of the iso ratio
   file is given in Sect. ":ref:`myxclass-iso`". If no file
   name is given (default), the so-called iso-flag is set to ``False``.
   |br| |br|

   NOTE, if the parameter ``observationalData`` defines a relative path,
   the path has to be defined relative to the current working directory!
   |br| |br|

-  ``NumModelPixelXX``: (optional) used for sub-beam modeling, describes
   the number of pixels used in x-direction (default: 100).
   |br| |br|

-  ``NumModelPixelYY``: (optional) used for sub-beam modeling, describes
   the number of pixels used in y-direction (default: 100).
   |br| |br|

-  ``LocalOverlapFlag`` (``True``/``False``): (optional) take local
   overlap into account (default: ``False``), see
   Sect. ":ref:`myxclass-localoverlap`".
   |br| |br|

-  ``NoSubBeamFlag`` (``True``/``False``): (optional) do not use
   sub-beam description (default: ``False``), see
   Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|

The following parameter is needed to add a velocity axis to the output
array ``model_values``, see below:

-  ``RestFreq``: rest frequency in MHz (default: 0).
   |br| |br|

The **myXCLASSFit** function offers the possibility to use two different
optimization packages: ``'magix'`` or ``'scipy'``, providing different
optimization algorithms, see Sect. .

-  ``Optimizer``: package used for optimization (``'magix'`` and
   ``'scipy'``) (default: ``'magix'``).

   Note, the optimization package used different fit algorithms. A list
   of the fit algorithms for each optimization package and the
   corresponding settings in the algorithm xml file is given in
   Sect. ":ref:`myxclassfit-alg-xml-file`".
   |br| |br|

-  ``FastFlag`` is deprecated.
   |br| |br|

-  ``ChannelIntegrationFlag``: (only for optimizer ``'scipy'``)
   flag indicating usage of channel integration (default: ``False``).
   |br| |br|

Finally, the results of the **myXCLASSFit** function can be exported in
two different ways

-  ``DictOutFlag``: flag indicating, that all return parameters are
   collected in a dictionary (default: ``False``).



Output parameters:
^^^^^^^^^^^^^^^^^^

Please note, the user is free to define different names for the output
parameters.

If the input parameter ``DictOutFlag`` is set to ``False``, the
**myXCLASSFit** function returns the results to the following three
output parameters:

-  ``input_file``: the contents of the molfit file containing the
   parameters for the best fit.
   |br| |br|

-  ``model_values``: the model function values for each data point,
   which correspond to the best fit.

   If ``RestFreq`` is unequal zero, the **myXCLASSFit** function adds a
   column to the output parameter ``model_values`` which contains the
   velocities. So, for a rest frequency unequal zero, the parameter
   ``model_values`` represents a python array with three columns, where
   the first column describes the frequencies, the second column
   describes the velocities and the third column the corresponding
   intensities.
   |br| |br|

-  ``JobDir``: absolute path of the job directory created for the
   current run.
   |br| |br|

Please note, if more than one algorithm is used, the output parameters
``input_file`` and ``model_values`` contain all input files and model
function values of all results, i.e. ``input_file[0]`` contains the
molfit file and ``model_values[0]`` the model function values for the
first applied fit algorithm.

The order of the results, i.e. the name of the molfit file, which
correspond to ``input_file[0]``, is printed to the screen.

If the input parameter ``DictOutFlag`` is set to ``True``, the
**myXCLASSFit** function exports the results to a python dictionary,
e.g. ``OutDict``, containing the following items:

-  ``"JobDir"``: describes path of the current job directory,
   i.e. ``OutDict["JobDir"]`` is the path and name of the current job
   directory.
   |br| |br|

-  ``"MolfitFileNames"``: is a python list indicating all used molfit
   file names, describing the optimized fit parameters after the
   application of a certain optimization algorithm.
   |br| |br|

-  ``"MolfitFilesContent"``: list of the corresponding molfit file
   contents,
   |br| |br|

-  ``"IsoRatioFileNames"``: list of iso ratio file names indicating the
   optimized fit parameters after the application of a certain
   optimization algorithm,
   |br| |br|

-  ``"IsoRatioFilesContent"``: list of the corresponding iso ratio file
   contents,
   |br| |br|

-  ``"ListOfSpectraFileNames"``: list of spectra file names after the
   application of a certain optimization algorithm,
   |br| |br|

-  ``"ListOfSpectraFilesContent"``: list of numpy arrays describing the
   optimized spectra after the application of a certain optimization
   algorithm,
   |br| |br|

-  ``"BestMolfitFileName"``: name of the molfit file of the best fit
   |br| |br|

-  ``"BestMolfitFileContent"``: content of the molfit file corresponding
   to the best fit,
   |br| |br|

-  ``"BestIsoRatioFileName"``: name of the iso ratio file of the best
   fit,
   |br| |br|

-  ``"BestIsoRatioFileContent"``: content of the iso ratio file which
   belongs to the best fit,
   |br| |br|

-  ``"BestSpectraFileNames"``: path and name of file describing the
   spectra of the best result,
   |br| |br|

-  ``"BestSpectraFilesContent"``: spectra of best fit.
   |br| |br|

Note, if only one algorithm is applied, the content of the items
``"MolfitFileNames"`` and ``"BestMolfitFileName"`` etc. are identical.
|br| |br|



.. ----------------------------------------------------------------------------------------



.. _api-myxclassmapfit:

myXCLASSMapFit
--------------


.. code:: python

    # import myXCLASSMapFit function
    from xclass import task_myXCLASSMapFit

    myXCLASSMapFitCore(MolfitsFileName = "",
                       MolfitFileName = None,
                       AlgorithmXMLFileName = "",
                       AlgorithmXMLFile = "",
                       NumberIteration = 50,
                       NumberProcessors = 4,
                       ObsXMLFileName = "",
                       ObsDataFileName = "",
                       experimentalData = "",
                       FastFitFlag = True,
                       FullFitFlag = False,
                       ChannelIntegrationFlag = False,
                       clusterdef = None,
                       daskFlag = False,
                       ParallelMethod = "process",
                       regionFileName = "",
                       FITSImageMaskFileName = "",
                       Threshold = None,
                       EstimateContinuumFlag = False,
                       EstimateConNumParts = 20,
                       EstimateConNumEntireCubeFlag = True,
                       UsePreviousResults = None,
                       DataSmoothValue = 0.0,
                       ParameterMapDir = None,
                       ParamMapIterations = 1,
                       ParamSmoothMethodParam = 1.0,
                       ParamSmoothMethod = "uniform",
                       FreqMin = None,
                       FreqMax = None,
                       TelescopeSize = None,
                       BMIN = None,
                       BMAJ = None,
                       BPA = None,
                       Redshift = None,
                       Inter_Flag = False,
                       t_back_flag = True,
                       tBack = 0.0,
                       tSlope = 0.0,
                       N_H = 0.0,
                       beta_dust = 0.0,
                       kappa_1300 = 0.0,
                       DustFileName = "",
                       BackgroundFileName = "",
                       ContPhenFuncID = None,
                       ContPhenFuncParam1 = None,
                       ContPhenFuncParam2 = None,
                       ContPhenFuncParam3 = None,
                       ContPhenFuncParam4 = None,
                       ContPhenFuncParam5 = None,
                       iso_flag = False,
                       IsoTableFileName = "",
                       NumModelPixelXX = 100,
                       NumModelPixelYY = 100,
                       LocalOverlapFlag = False,
                       NoSubBeamFlag = False,
                       EmAbsPATH = None,
                       RestFreq = 0.0,
                       vLSR = 0.0,
                       ZipDirFlag = False,
                       DoParameterEstimationFlag = False,
                       InternalParameterList = {},
                       JobDir = None,
                       NameOfFunction = None)


In contrast to the *myXCLASSFit* function, the **myXCLASSMapFit**
function fits a complete (FITS) data cube [1]_ Here, the
**myXCLASSMapFit** function reads in the data cube(s), extracts the
spectra for each pixel and fits these spectra separately using an
user-defined optimization algorithm. The **myXCLASSMapFit** function
provides three different fitting procedures: ``"fast"``, ``"full"``, and
``"normal"``. The first two methods allow accelerated fitting without
MAGIX and instead provide an interface to the ``SciPy``
[Virtanen_et_al_2020]_ optimization functions described in
Sect. ":ref:`myxclassfit-alg-xml-file`".

These optimization algorithms are described in an algorithm xml file,
see Sect. ":ref:`myxclassfit-alg-xml-file`". In principle, it is also
possible to combine algorithms, i.e. to start with a global optimization
algorithm and use the results of this algorithm as input for a local
optimization algorithm such as ``"trf"``. In contrast to the myXCLASSFit
function, all optimization algorithms are not parallelized, i.e. the
optimization procedure for a single pixel uses only one core.

If the algorithm XML file contains a definition for the number of
processors (cores) for an optimization algorithm, this number now
defines the number of pixels that are fitted simultaneously. If
more processor cores are defined than are available on the computer,
*XCLASS* reduces the number to the number of available processors
(cores) minus one. If no algorithm xml file is used, the
**myXCLASSMapFit** function uses the ``trf`` algorithm with four
cores and performs no more than 50 iterations.

With the ``"fast"`` method (applied by default), the
**myXCLASSMapFit** function uses simplified versions of the *XCLASS*
core functions to compute the synthetic spectra used for the
optimization algorithms. These simplified functions are able to
compute the contribution of molecules and recombination lines in LTE
in conjunction with dust contributions. Additionally, it is possible
to arrange the components
according to the distance parameter along the line-of-sight, see
Sect. ":ref:`myxclass-molfit-stacking`". In contrast to the
``"fast"`` method, the ``"full"`` method uses the full
*XCLASS* core routines, which is why it is possible to use sub-beam
description Sect. ":ref:`myxclass-molfit-subbeam`. Compared to the
``"fast"`` method mentioned above, this fitting procedure is
computationally more complex, so the fitting takes a little more time.
Finally, the ``"normal"`` method provides an interface to the
*MAGIX* optimization package, similar to the *myXCLASSFit*
function. This fitting procedure requires a lot of I/O to the hard
disk, which is why it is much slower compared to the previously
mentioned procedures.

For each run the **myXCLASSMapFit** function creates a so-called job
directory, where the name of a job directory is made up of four
components: The first part of the name consists of the phrase
``"job_"`` whereas the second part describes the date (day, month,
year), the third part the time stamp (hours, minutes, seconds) of the
function execution. The last part describes a so-called job ID which
is composed of the so-called PID followed by a four digit random
integer number to create a really unambiguous job number, e.g.

::

   /path-of-XCLASS-run/myXCLASSMapFit/job__25-07-2013__12-02-03__189644932/.


If the ``"normal"`` fitting method is selected, the **myXCLASSMapFit**
function creates a subdirectory within this job directory called
``"Pixel-Fits/``, which contains further subdirectories for each pixel,
where the names of these subdirectories are made up of the values (in
degrees) for the right ascension and for the declination, respectively,
e.g. ``"83.65498__-5.24258"``. Additionally, the indices of the
corresponding pixel are added as well separated by "``_-_``", e.g.
``"83.65498__-5.24258__1_-_2"``. All output files, created by MAGIX for
this pixel are stored in this subdirectory. If the user applies the
Levenberg-Marquardt algorithm, the **myXCLASSMapFit** function uses the
parameter given in the molfit file as initial guess for all pixels in
the first row of the selected region.

At the end of the whole fit procedure, the **myXCLASSMapFit** function
creates FITS images for each optimized parameter, where each pixel
corresponds to the value of the optimized parameter taken from the best
fit for this pixel. The name of each parameter FITS image consists of
the phrase ``"BestResult"`` followed by the name of the parameter,
e.g. ``T_rot`` for the rotation temperature etc, the name of the
corresponding molecule, and finally by the index of the related
component. For example, the FITS file

::

   BestResult___parameter__T_rot___molecule__CH3OH_v=0____component__1.fits,


describes the optimized excitation (rotation) temperature of the first
component of molecule "CH\ :math:`_3`\ OH,v=0" for each pixel of the
selected fit region. In addition to the parameter maps, the
**myXCLASSMapFit** function creates one FITS image, where each pixel
corresponds to the :math:`\chi^2` value of the best fit, i.e. the
quality of the fit, for the corresponding pixel.

Furthermore, the **myXCLASSMapFit** function creates FITS cubes for
each used algorithm and fitted data cube, where each pixel contains
the modeled spectrum. The name of these FITS cubes ends with the
expression ``"__model.out.fits"``. (If more than one fit algorithm was
used, this expression is extended by the respective name of the
optimization algorithm). If more than one frequency range was used for
a given FITS cube, the name of the corresponding FITS cube describing
the synthetic spectra also contains the frequency limits (in MHz),
i.e.

::

   name-of-FITS-file__MinFreq_-_MaxFreq__MHz__model.out.fits.


The FITS files, which end with ``".chi2.out.fits"``, describe the
:math:`\chi^2` function for each pixel.
In addition, the **myXCLASSMapFit** function converts the following
parameters ``N_tot``, ``EM_RRL``,
``nHcolumn_cont_dust``, and ``nHcolumn`` to a log scale, i.e.
these parameter values are converted
automatically to their log10 values to get a better fit. At the end of
the fitting process, the log10 values are converted back to the
original linear values. So, the MAGIX log files contain the log10
values of these parameters, whereas the input and output molfit files
contain the linear values, respectively.

The **myXCLASSMapFit** function offers the possibility to use a
so-called cluster consisting of at least two computers. The nodes
(computers) of the cluster are defined by the input parameter
``clusterdef``, see below. **Unfortunately, due to problems with the
used parallelization packages, cluster computation with more than one
computer is currently not possible.**

The **myXCLASSMapFit** function can handle FITS cubes (and images) for
background and dust files as well, i.e. the user can specify the path
and name of a FITS cube describing the background (or dust) spectrum
for each pixel and frequency range. If a FITS image is provided
instead of a cube, the corresponding spectrum is automatically
generated for the required frequency points. If a background spectrum
is given in Jy/beam, *XCLASS* automatically converts the intensities to
Kelvin. The FITS cubes (or images) need not to cover the entire
region. Where no background (or dust) file is given, no background (or
dust) spectrum is used.



Input parameters:
^^^^^^^^^^^^^^^^^

-  ``MolfitsFileName``: path and name of the extended molfit file, see
   Sect. ":ref:`myxclass-molfit`".
   |br| |br|

-  ``MolfitFileName``: (optional) alias of ``MolfitsFileName``,
   (default: ``None``).
   |br| |br|

-  ``FastFitFlag``: (optional) flag indicating fast fitting,
   (default: ``True``).
   |br| |br|

-  ``FullFitFlag``: (optional) full fit flag, (default: ``False``). If
   ``FastFitFlag`` and ``FullFitFlag`` are set to ``False``, normal
   fitting is applied.
   |br| |br|

-  ``ChannelIntegrationFlag``: (optional, for full fitting method only)
   flag indicating channel integration (default: ``False``).
   |br| |br|

-  ``AlgorithmXMLFileName``: (optional) path and name of an algorithm
   xml-file describing settings for an algorithm or algorithm chain, see
   Sect. ":ref:`myxclassfit-alg-xml-file`".

   NOTE, if the user specify a xml file, the number of iterations given
   by the parameter ``NumberIteration`` is ignored. The number of
   iteration is then given by the xml file.
   |br| |br|

-  ``AlgorithmXMLFile``: (optional) alias of ``AlgorithmXMLFileName``.
   |br| |br|

-  ``NumberIteration``: (only necessary if no algorithm xml and no
   cluster file is given) max. number of iterations (default: 50).
   |br| |br|

-  ``NumberProcessors``: (optional) max. number of cores, only used if
   no algorithm xml file is applied (default: 4).
   |br| |br|

-  ``clusterdef``: path and name of a file describing a cluster,
   (default: ``""``).

   In order to start the **myXCLASSMapFit** function on a multi-computer
   cluster, a so-called “cluster configuration file” is required. The
   following requirements are necessary for all nodes which are included
   in the cluster:

   #. Password-less ssh access from the controller (user) machine to all
      other nodes included in the cluster.

      NOTE: This is not necessary when using only "localhost", i.e. if
      the cluster is deployed only on the machine where *XCLASS* is
      running.

   #. *XCLASS* interface and gfortran (with OpenMP/OpenMPI) is installed
      on all nodes of the cluster.

   #. The *XCLASS* job directory must be located in a shared file-system,
      accessible from all nodes comprising the cluster, and mounted in
      the same path of the file-system.

      NOTE: If the cluster contains computers with different operating
      systems, e.g. Linux and MAC OS, the user has to define the
      different paths of the *XCLASS* interface directories.

   Example of a “cluster configuration file” used for the
   **myXCLASSMapFit** function:

   ::

              # cluster configuration file
              # node      number of cores      path of XCLASS interface
              anu,        2
              lugal,      3

   In the example described above, the nodes "anu" and "lugal" will be
   used with two (three) cores, respectively.
   |br| |br|

-  ``regionFileName``: (optional) path and name of a so-called ds9 [2]_
   region file, (default: ``""``).
   |br| |br|

-  ``FITSImageMaskFileName``: (optional) path and name of a FITS image
   used for masking. Here, each pixel with a real numerical value,
   i.e. which is not NaN, is fitted, (default: ``""``).
   |br| |br|

-  ``Threshold``: defines a threshold for a pixel. If the spectrum of a
   pixel has an max. intensity lower than the value defined by this
   parameter the pixel is not fitted (ignored), (default: ``None``).

   Please note, the value for the ``Threshold`` parameter has to be
   given in the same unit than the spectrum in the FITS file.

   NOTE, if an observational xml-file is used, the user can define
   different threshold values for each frequency range by using the tag
   ``<Threshold>``. Please note, that the tag ``<Threshold>`` has to be
   given for each frequency range. If tag ``<Threshold>`` is defined in
   the xml file, the value of the input parameter ``Threshold`` is
   ignored.
   |br| |br|

-  ``EstimateContinuumFlag``: (optional) flag indicating continuum
   estimation using the ``statcont``
   [SanchezMonge_et_al_2018]_ package (default: ``False``).
   |br| |br|

-  ``EstimateConNumParts``: (optional) number of sub-parts used for
   continuum estimation to describe non-constant continuum levels as
   well, (default: 20). In order to estimate the continuum level, the
   obs. data (of each pixel) are divided into :math:`n`
   (=\ ``EstimateConNumParts``) equidistant parts to which ``statcont``
   is applied. Now, the obs. data within each part is replaced by the
   corresponding continuum level located at the center of each part.
   Afterwards, the well-known expression

   .. math:: I_{\rm bg} (\nu) = T_{\rm bg} \cdot \left(\frac{\nu}{\nu_{\rm min}} \right)^{T_{\rm slope}}

   is fitted to these data points to achieve the parameters
   :math:`T_{\rm bg}` and :math:`T_{\rm slope}`.
   |br| |br|

-  ``EstimateConNumEntireCubeFlag``: (optional) flag indicating that the
   continuum estimation is done for the entire spectral range of the
   corresponding FITS cube and not only for the local frequency range,
   (default: ``True``).
   |br| |br|

-  ``DataSmoothValue``: (optional) smooth factor (=0, no smoothing is
   performed) used for spectral smoothing, (default: 0.0). Here each
   pixel is convolved with a Gaussian whose width is given by this
   parameter.
   |br| |br|

-  ``UsePreviousResults``: Please note, this parameter is no longer
   used.
   |br| |br|

-  ``ParamMapIterations``: (optional) number of iterations to smooth
   parameter maps, (default: 1).

   A value greater 1 indicates a parameter map smoothing procedure,
   i.e. after finishing the first **myXCLASSMapFit** run, the created
   parameters maps are smoothed using the method and parameter described
   by ``ParamSmoothMethodParam`` and ``ParamSmoothMethod``. The values
   of the smoothed parameter maps are used in a second
   **myXCLASSMapFit** run, where the parameters in the molfit files at
   each fitted pixel position are updated by the values of the smoothed
   maps. The whole procedure is repeated as many times as indicated by
   ``ParamMapIterations``. The names of the FITS files describing the
   parameter maps are extended by the phrase ``"_____Iter__n.fits"``,
   where :math:`n` indicates the current iteration, The FITS files
   ending with :math:`n=`\ ``ParamMapIterations`` describe the final
   parameter maps.
   |br| |br|

-  ``ParamSmoothMethodParam``: (optional) parameter used for smoothing
   the parameter map(s), see input parameter ``ParamSmoothMethod``,
   (default: 1.0)
   |br| |br|

-  ``ParamSmoothMethod``: (optional) SciPy method (``"gaussian"``,
   ``"uniform"``, ``"median"``) used for parameter map smoothing,
   (default: ``"uniform"``).

   -  For ``"gaussian"``, SciPy's multidimensional Gaussian filter [3]_
      is used, where ``ParamSmoothMethodParam`` indicates the standard
      deviation for Gaussian kernel (in pixel) which is assumed to be
      equal for both axes.

   -  For ``"uniform"``, SciPy's multidimensional uniform filter [4]_ is
      applied, where ``ParamSmoothMethodParam`` describes the sizes (in
      pixel) of the uniform filter which is equal for both axes.

   -  For ``"median"``, SciPy's multidimensional median filter [5]_ is
      utilized, where ``ParamSmoothMethodParam`` defines the sizes (in
      pixel) of the median filter which is equal for both axes.
      |br| |br|

-  ``DoParameterEstimationFlag``: is deprecated
   |br| |br|

-  ``InternalParameterList``: is deprecated
   |br| |br|

-  ``ParameterMapDir``: (optional) path of a directory containing FITS
   images describing parameter maps to update the parameter defined in
   the molfit file (or iso ratio file) for each pixel (default:
   ``None``). By using this parameter
   the user can modify the content of the molfit file, defined by input
   parameter ``MolfitsFileName``, for each pixel. Therefore, the name of
   the FITS image file describing a parameter map has to consists of the
   name of the molfit parameter (e.g. ``N_tot``), which has to be
   updated, the name of the molecule, and the corresponding component
   number. The different settings has to be separated by ``"___"``. The
   definition of the parameter name has to start with the phrase
   ``"parameter__"`` followed by the name of the parameter, i.e. the
   name has to be ``"source_size"``, ``"source_radius"``,
   ``"s_radius"``, ``"source_center_x"``, ``"s_off_x"``,
   ``"source_center_y"``, ``"s_off_y"``, ``"T_rot"``, ``"T_e"``,
   ``"T_cont_dust"``, ``"T_dOff"``, ``"T_dSlope"``, ``"N_tot"``,
   ``"EM_RRL"``, ``"nHcolumn_cont_dust"``, ``"nHcolumn"``,
   ``"V_width``, ``"V_width_Gauss"``, ``"V_off"``,
   ``"beta_cont_dust"``, ``"kappa_cont_dust"``,
   ``"kappa"``, ``"beta"``, ``"ContFuncID_param_1"``,
   ``"ContPhenFuncParam1"``, ``"ContFuncID_param_2"``,
   ``"ContPhenFuncParam2"``, ``"ContFuncID_param_3"``,
   ``"ContPhenFuncParam3"``, ``"ContFuncID_param_4"``,
   ``"ContPhenFuncParam4"``, ``"ContFuncID_param_5"``,
   ``"ContPhenFuncParam5"``. Additionally, the name of the molecule has
   to start with phrase ``"molecule__"`` followed by the name of the
   molecule, where the characters (``";"``, ``","``, ``"'"``, ``"("``,
   ``")"``, ``"#"``) has to be replaced by ``"_"``. Finally, the
   definition of the component number has to start with
   ``"component__"`` followed by an integer number. For example, we want
   to use a FITS image describing the velocity offsets for the first
   component of CH\ :math:`_3`\ CN,v=0 for each pixel of the selected
   region. The name of the corresponding FITS file is
   ``"parameter__V_off___molecule__CH3CN_v=0____component__1.fits"``.

   In order to define iso ratios for a specific isotopologue, the name
   of the parameter has to be set to ``"isoratio"`` and the name of
   the molecule has to indicate the corresponding isotopologue. The
   part, which describes the component has to be removed, e.g.
   ``"parameter__isoratio___molecule__C-13H3CN_v=0_.fits"``.

-  ``ObsXMLFileName``: (optional) path and name of an obs. xml file
   (recommended procedure), (default: ``""``), see Sect.
   ":ref:`myxclassfit-obs-xml-file`" for a detailed description.

   Note, the name of the xml file has to end with ``".xml"``.
   |br| |br|

-  ``ObsDataFileName``: (optional) path and name of a file describing
   a 3d or 4d FITS data cube.

   Note, the name of the data file has to end with ``".fits"``.

   If the intensities of a data cube are given in Jy/beam, the
   **myXCLASSMapFit** function converts the intensities to Kelvin
   using the following expression [6]_ [Rohlfs_Wilson_1996]_

   .. math:: T_{\rm mb} (\nu) = \frac{c^2 \cdot S_\nu}{2 \, k_B \, \nu^2 \, \Omega} \cdot 10^{-26},

   where :math:`S_\nu` describes the intensity at a certain
   frequency :math:`\nu` in Jy/beam and :math:`c` and :math:`k_B`
   represents the speed of light and the Boltzmann constant,
   respectively. Additionally, :math:`\Omega` indicates the solid
   angle of the beam and can be expressed under the assumption that
   the beam can be approximated by a two-dimensional, elliptical
   Gaussian function :math:`G(\alpha, \beta)`

   .. math:: \Omega = \iint G(\alpha, \beta) \, d\alpha \, d \beta = {\rm BMAJ} \cdot {\rm BMIN} \cdot \frac{\pi}{4 \, \ln(2)},

   where BMAJ and BMIN indicate the FWHM of the beam major and
   minor axis length in arcsec, respectively [7]_.

   Please note, without using an obs. xml file, it is not possible
   to fit more than one data cube, simultaneously.

-  ``experimentalData``: (optional) alias of ``ObsDataFileName``,
   (default: ``None``)
   |br| |br|

The following parameters are needed, if parameter ``ObsDataFileName`` is
used instead of parameter ``ObsXMLFileName``:

-  ``FreqMin``: start frequency of simulated spectrum (default: 0).

   Please note, in contrast to previous *XCLASS* releases, the min. and
   max. frequency has to be defined! Additionally, the step size,
   i.e. the difference between two frequencies is taken from the FITS
   header.
   |br| |br|

-  ``FreqMax``: end frequency of simulated spectrum (default: 0).
   |br| |br|

-  ``vLSR``: velocity (local standard of rest) in km s\ :math:`^{-1}`
   (default: 0) used in the calculation of the synthetic spectra
   |br| |br|

-  ``TelescopeSize``: for single dish observations
   (``Inter_Flag = False``): ``TelescopeSize`` describes the size of
   telescope (in m), (default: 1); for interferometric observations
   (``Inter_Flag = True``): ``TelescopeSize`` describes the
   interferometric beam FWHM size (in arcsec), (default: 1).
   |br| |br|

-  ``BMIN``: (optional) beam minor axis length (in arcsec),
   (default: ``None``).

   Note, in the header of FITS files, the beam minor and major axis
   lengths are often given in degrees and not in arcsec, i.e. the values
   have to be divided by 3600.
   |br| |br|

-  ``BMAJ``: (optional) beam major axis length (in arcsec),
   (default: ``None``).
   |br| |br|

-  ``BPA``: (optional) beam position angle (in degree),
   (default: ``None``).
   |br| |br|

-  ``Redshift``: (optional) red shift (dimensionless),
   (default: ``None``).
   |br| |br|

-  ``Inter_Flag`` (``True``/``False``): defines, if single dish
   (``False``) or interferometric observations (``True``) are described,
   (default: ``False``).
   |br| |br|

-  ``t_back_flag`` (``True``/``False``): defines, if the user defined
   background temperature :math:`T_{\rm bg}` and temperature slope
   :math:`T_{\rm slope}` given by the input parameters ``tBack`` and
   ``tSlope`` describe the continuum contribution completely
   (``t_back_flag = True``) or not (``t_back_flag = False``)
   (default: ``True``).
   |br| |br|

-  ``tBack`` background temperature (in K), (default: 0.0).
   |br| |br|

-  ``tSlope`` temperature slope (dimensionless), (default: 0.0).
   |br| |br|

-  ``BackgroundFileName`` (optional) path and name of file describing
   the background as function of frequency (in MHz),
   (default: ``None``).
   |br| |br|

-  ``N_H`` (optional) Hydrogen column density (in cm\ :math:`^{-2}`),
   (default: 0.0).
   |br| |br|

-  ``beta_dust`` (optional) spectral index for dust (dimensionless),
   (default: 0.0).
   |br| |br|

-  ``kappa_1300`` (optional) kappa at 1.3 mm
   (cm\ :math:`^2 \,`\ g\ :math:`^{-1}`), (default: 0.0).
   |br| |br|

-  ``DustFileName`` (optional) path and name of file describing dust
   contribution, (default: ``None``).
   |br| |br|

-  ``ContPhenFuncID``: (optional) describes which phenomenological
   function is used to describe the continuum, (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam1``: (optional) first parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam2``: (optional) second parameter for
   phenomenological function describing the
   continuum,(default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam3``: (optional) third parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam4``: (optional) fourth parameter for
   phenomenological function describing the
   continuum,(default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam5``: (optional) fifth parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``iso_flag``: use isotopologues (``True``/``False``). If ``iso_flag``
   is set to ``True`` isotopologues defined in the iso ratio file are
   used, (default: ``False``).
   |br| |br|

-  ``IsoTableFileName`` (has to be given only if ``iso_flag`` is set to
   ``True``): path and name of an ASCII file including the iso ratios
   between certain molecules. A detailed description of the iso ratio
   file is given in Sect. ":ref:`myxclass-iso`". If no file
   name is given (default), the so-called iso-flag is set to ``False``.

   NOTE, if the given path is a relative path, i.e. the path does not
   start with ``/``, this path has to be defined relative to the current
   working directory!
   |br| |br|

-  ``NumModelPixelXX``: (optional) used for sub-beam modeling,
   Sect. ":ref:`myxclass-molfit-subbeam`", describes
   the number of pixels used in x-direction, (default: 100).
   |br| |br|

-  ``NumModelPixelYY``: (optional) used for sub-beam modeling,
   Sect. ":ref:`myxclass-molfit-subbeam`", describes
   the number of pixels used in y-direction, (default: 100).
   |br| |br|

-  ``LocalOverlapFlag``: (optional) flag indicates if local-overlap
   description is used or not, see
   Sect. ":ref:`myxclass-localoverlap`",
   (default: ``False``).
   |br| |br|

-  ``NoSubBeamFlag`` (``True``/``False``): (optional) do not use
   sub-beam description (default: ``False``), see
   Sect. ":ref:`myxclass-molfit-subbeam`",
   i.e. *XCLASS* uses the old source description, see
   Sect. ":ref:`myxclass-molfit-1d`".



Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``JobDir``: absolute path of the job directory created for the
   current run.
   |br| |br|



.. ----------------------------------------------------------------------------------------



.. _api-myxclassredomapfit:

myXCLASSMapRedoFit
------------------


.. code:: python

    # import myXCLASSMapRedoFit function
    from xclass import task_myXCLASSMapRedoFit

    myXCLASSMapRedoFitCore(JobNumber = None,
                           PixelList = [],
                           JobPath = "",
                           MaskFileName = "",
                           Threshold = None,
                           MolfitsFileName = "",
                           MolfitFileName = None,
                           EstimateContinuumFlag = False,
                           EstimateConNumParts = 20,
                           EstimateConNumEntireCubeFlag = True,
                           DataSmoothValue = 0.0,
                           NumberIteration = 50,
                           NumberProcessors = 2,
                           AlgorithmXMLFile = "",
                           AlgorithmXMLFileName = "",
                           clusterdef = "",
                           FastFitFlag = True,
                           FullFitFlag = False,
                           ChannelIntegrationFlag = False,
                           daskFlag = False,
                           FreqMin = None,
                           FreqMax = None,
                           t_back_flag = True,
                           tBack = 0.0,
                           tSlope = 0.0,
                           N_H = 0.0,
                           beta_dust = 0.0,
                           kappa_1300 = 0.0,
                           DustFileName = "",
                           BackgroundFileName = "",
                           ContPhenFuncID = None,
                           ContPhenFuncParam1 = None,
                           ContPhenFuncParam2 = None,
                           ContPhenFuncParam3 = None,
                           ContPhenFuncParam4 = None,
                           ContPhenFuncParam5 = None,
                           iso_flag = False,
                           IsoTableFileName = "",
                           NumModelPixelXX = 100,
                           NumModelPixelYY = 100,
                           LocalOverlapFlag = False,
                           NoSubBeamFlag = True,
                           EmAbsPATH = None)


This function offers the possibility to redo one or more so called
pixel fits of a previous *myXCLASSMapFit* run. The function performs
fits for the selected pixels and recreates the different parameter
maps using the new optimized parameter values together with the
corresponding FITS cube(s) describing the synthetic spectra for all
selected pixels. The names of these maps are created in the same way
as described in Sect. ":ref:`api-myxclassmapfit`". In
addition, the **myXCLASSMapRedoFit** function renames the files
describing the parameter maps from the previous call of the
**myXCLASSMapFit** function by replacing the end of the each filename
``".fits"`` by the phrase ``"__REDO-OLD.fits"``. The user has to
define the pixel coordinates, which should be re-fitted, the job
number of the previous *myXCLASSMapFit* run, and the new molfit
file.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``JobNumber``: job number of a previous *myXCLASSMapFit* run which
   should be improved.
   |br| |br|

-  ``PixelList``: list of all pixel coordinates which should be
   re-fitted. (These pixel coordinates are used to identify the pixel
   directories created by the selected *myXCLASSMapFit* call, see
   Sect. ":ref:`api-myxclassmapfit`"). Each coordinate
   consists of two numbers separated by a comma, where the first number
   corresponds to the right ascension and second to the declination.
   Different pixel coordinates are enclosed by squared brackets and
   separated by commas. For example, we want to refit the pixels
   83.2013422325, -15.1345324232 and 83.1111111111, -15.2211111111. The
   ``PixelList`` parameter has to be defined as follow

   ::

          PixelList = [[83.2013422325, -15.1345324232],
                       [83.1111111111, -15.2211111111]]

   Please note, that these coordinates are used to identify the pixel
   directories in the selected *myXCLASSMapFit* job directory,
   i.e. the values defined in the ``PixelList`` parameter have to be
   included in the names of the corresponding pixel directories. For
   example, we want to refit the pixel with pixel directory
   ``83.2013422325__-15.1345324232__1_-_3``. In order to identify this
   pixel the ``PixelList`` parameter can be defined as

   ::

          PixelList = [[83.2013422325, -15.1345324232]]

   Additionally, the ``myXCLASSMapRedoFit`` function offers the
   possibility to define the indices of the pixels which should be
   refitted. In the example described above, the ``PixelList`` parameter
   can be defined as

   ::

          PixelList = [[1, 3]]

   to identify the pixel 83.2013422325, -15.1345324232.
   |br| |br|

-  ``JobPath``: (optional) path of job directory for application of the
   *myXCLASSMapFit* function, (default: ``""``).
   |br| |br|

-  ``MaskFileName``: (optional) path and name of a FITS image used for
   masking. Here, each pixel with a real numerical value, i.e. which is
   not NaN, is fitted, (default: ``""``).
   |br| |br|

-  ``Threshold``: defines a threshold for a pixel (default: ``None``).
   If the spectrum of a pixel has a max. intensity lower than the value
   defined by this parameter the pixel is not fitted (ignored).
   |br| |br|

-  ``MolfitsFileName``: path and name of the extended molfit file.
   |br| |br|

-  ``MolfitFileName``: (optional) alias of ``MolfitsFileName``,
   (default: ``None``).
   |br| |br|

-  ``EstimateContinuumFlag``: (optional) flag indicating continuum
   estimation, (default: ``False``).
   |br| |br|

-  ``EstimateConNumParts``: (optional) number of sub parts used for
   continuum estimation, (default: 20).
   |br| |br|

-  ``EstimateConNumEntireCubeFlag``: (optional) flag indicating that
   continuum estimation is done for the entire spectral range,
   (default: ``True``).
   |br| |br|

-  ``DataSmoothValue``: (optional) smooth factor (=0, no smoothing is
   performed) used for smoothing obs. data, (default: 0.0).
   |br| |br|

-  ``NumberIteration``: max. number of iterations, (default: 50).
   |br| |br|

-  ``NumberProcessors``: (optional, only used if no alg. xml file is
   defined) number of cores, (default: 2).
   |br| |br|

-  ``AlgorithmXMLFileName``: path and name of an algorithm xml-file,
   (default: ``""``).. (A relative path has to be defined relative to
   the current working directory!)
   |br| |br|

-  ``AlgorithmXMLFile``: (optional) alias of ``AlgorithmXMLFileName``.
   |br| |br|

-  ``FastFitFlag``: (optional) flag indicating usage of fast-fitting
   method, (default: ``True``).
   |br| |br|

-  ``FullFitFlag``: (optional) flag indicating usage of full-fitting
   method, (default: ``False``).
   |br| |br|

-  ``ChannelIntegrationFlag``: (optional, for ``full``-fitting method
   only) flag indicating channel integration, (default: ``False``).
   |br| |br|

-  ``FreqMin``: new start frequency of simulated spectrum, (default: 0).
   |br| |br|

-  ``FreqMax``: new end frequency of simulated spectrum, (default: 0).
   |br| |br|

-  ``t_back_flag`` (``True``/``False``): defines, if the user defined
   background temperature :math:`T_{\rm bg}` and temperature slope
   :math:`T_{\rm slope}` given by the input parameters ``tBack`` and
   ``tSlope`` describe the continuum contribution completely
   (``t_back_flag = True``) or not (``t_back_flag = False``),
   (default: ``True``).
   |br| |br|

-  ``tBack`` background temperature (in K), (default: 0).
   |br| |br|

-  ``tSlope`` temperature slope (dimensionless), (default: 0).
   |br| |br|

-  ``BackgroundFileName`` (optional) path and name of file describing
   the background as function of frequency (in MHz),
   (default: ``None``).
   |br| |br|

-  ``N_H`` (optional) Hydrogen column density (in cm\ :math:`^{-2}`),
   (default: ``None``).
   |br| |br|

-  ``beta_dust`` (optional) spectral index for dust (dimensionless),
   (default: ``None``).
   |br| |br|

-  ``kappa_1300`` (optional) kappa at 1.3 mm
   (cm\ :math:`^2 \,`\ g\ :math:`^{-1}`), (default: ``None``).
   |br| |br|

-  ``DustFileName`` (optional) path and name of file describing dust
   contribution (default: ``""``).
   |br| |br|

-  ``ContPhenFuncID``: (optional) describes which phenomenological
   function is used to describe the continuum, (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam1``: (optional) first parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam2``: (optional) second parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam3``: (optional) third parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam4``: (optional) fourth parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``ContPhenFuncParam5``: (optional) fifth parameter for
   phenomenological function describing the continuum,
   (default: ``None``).
   |br| |br|

-  ``iso_flag``: use isotopologues (``True``/``False``). If ``iso_flag``
   is set to ``True`` isotopologues defined in the iso ratio file are
   used, (default: ``False``).
   |br| |br|

-  ``IsoTableFileName`` (has to be given only if ``iso_flag`` is set to
   ``True``): path and name of an ASCII file including the iso ratios
   between certain molecules. A detailed description of the iso ratio
   file is given in Sect. ":ref:`myxclass-iso`". If no file
   name is given (default), the so-called iso-flag is set to ``False``.

   NOTE, if the given path is a relative path, i.e. the path does not
   start with ``/``, this path has to be defined relative to the current
   working directory!
   |br| |br|

-  ``NumModelPixelXX``: (optional) used for sub-beam modeling, describes
   the number of pixels used in x-direction, (default: 100).
   |br| |br|

-  ``NumModelPixelYY``: (optional) used for sub-beam modeling, describes
   the number of pixels used in y-direction, (default: 100).
   |br| |br|

-  ``LocalOverlapFlag`` (``True``/``False``): (optional) take local
   overlap into account (default: ``False``), see
   Sect. ":ref:`myxclass-localoverlap`".
   |br| |br|

-  ``NoSubBeamFlag`` (``True``/``False``): (optional) do not use
   sub-beam description (default: ``False``), see
   Sect. ":ref:`myxclass-molfit-subbeam`".
   |br| |br|


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``None``
   |br| |br|



.. ----------------------------------------------------------------------------------------



.. _api-databasequery:

DatabaseQuery
-------------


.. code:: python

    # import DatabaseQuery function
    from xclass import task_DatabaseQuery

    DatabaseQuery(QueryString)


This function sends a given SQL query string to the *XCLASS* database.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``QueryString``: the query string (default " ").


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``Contents``: contains the screen output of the query command.

   Please note, the user is free to define a different name for the
   output parameter.
   |br| |br|



.. ----------------------------------------------------------------------------------------



.. _api-updatedatabase:

UpdateDatabase
--------------


.. code:: python

    # import UpdateDatabase function
    from xclass import task_UpdateDatabase

    UpdateDatabase(DBUpdateNew,
                   ForceRRLAdd = False,
                   RRLMaxN = 900,
                   RRLMaxDeltaN = 6)


This function updates the *XCLASS* database file located in the
directory ``Database`` from spectroscopic databases connected to the
Virtual Atomic and Molecular Datacentre, VAMDC (www.vamdc.eu).
Currently, data access to the CDMS database and the JPL catalog, is
supported.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``DBUpdateNew``: indicates, if, a complete SQLite3 database file is
   downloaded from the CDMS web server ("new") or if the existing
   database file is updated ("update") via the VAMDC infrastructure,
   i.e. new entries are added to the tables and existing entries are
   overwritten with new data. The complete SQLite3 database file is
   regularly updated via the VAMDC infrastructure and contains data from
   CDMS and JPL (default ``new``).


-  ``ForceRRLAdd``: flag for forcing the addition and calculation
   of RRLs (default: ``False``)

-  ``RRLMaxN``: max. main quantum number n for which RRLs are
   computed, (default: ``900``)

-  ``RRLMaxDeltaN``: max. Delta n for which RRLs are computed,
   (default: ``6``)


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``None``
   |br| |br|


.. ----------------------------------------------------------------------------------------



.. _api-listdatabase:

ListDatabase
------------


.. code:: python

    # import ListDatabase function
    from xclass import task_ListDatabase

    ListDatabaseCore(FreqMin = 1.0,
                     FreqMax = 1.e8,
                     ElowMin = 0.0,
                     ElowMax = 1.e6,
                     SelectMolecule = [],
                     OutputDevice = "",
                     dbFilename = None)


This function reads in entries from the table ``transitions`` located
in the SQLite3 database file and prints out the contents to the screen
or file (defined by the input parameter ``OutputDevice``). The user
can limit the output by defining a minimum and maximum for the
frequency (or for the lower energy) for the transitions.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``FreqMin``: minimum frequency (in MHz) for transitions in the
   ``transitions`` table (default: 0)

-  ``FreqMax``: maximum frequency (in MHz) for transitions in the
   ``transitions`` table (default: :math:`10^8`)

-  ``ElowMin``: minimum for lower energy (in K) (default: 0)

-  ``ElowMax``: maximum for lower energy (in K) (default: :math:`10^6`)

-  ``SelectMolecule``: a (python) list containing the names of all
   molecules which should be considered or a string defining the path
   and the name of an ASCII file including the molecules which should be
   selected.

   Note, if the parameter defines a relative path, this path has to be
   defined relative to the current working directory!

-  ``OutputDevice``: path and name of the file where the output is
   written to. If no file name is defined, the content of the database
   is written to the screen. If this parameter is set to
   ``quiet`` no information is printed to screen.

   Note, if the parameter defines a relative path, this path has to be
   defined relative to the current working directory!

- ``dbFilename``: path and name of used database file (default: ``None``)


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``Contents``: content of the database (as a python array,
   e.g. ``Contents[0]`` contains the entries for the first molecule
   within the frequency/energy range).

   Note, the user is free to define a different name for the output
   parameter.
   |br| |br|


.. ----------------------------------------------------------------------------------------



.. _api-gettransitions:

GetTransitions
--------------


.. code:: python

    # import GetTransitions function
    from xclass import task_GetTransitions

    GetTransitionsCore(obsdata = None,
                       FreqMin = None,
                       FreqMax = None,
                       SelectMolecule = [],
                       FrequencyWidth = 5,
                       ElowMin = 0,
                       ElowMax = 1.e9,
                       modeldata = None)


Similar to the *ListDatabase*\ function, the **GetTransitions**
function displays information from the embedded database about
transitions within a user-defined frequency range. Here, the frequency
range selection is done in an interactive way. Therefore, the
**GetTransitions** function starts a graphical user interface (GUI)
which describes observational data (defined by parameter ``obsdata``)
within a frequency range defined by the parameters ``FreqMin`` and
``FreqMax``. Additionally, the function offers the possibility to plot a
synthetic spectrum (defined by parameter ``modeldata``) of a previous
*myXCLASS* or *myXCLASSFit* function call as well.

By using the mouse in combination with the right mouse button, the user
defines the central frequency (blue vertical line) of the frequency
range (grey vertical bar) which is used for the database query. The
initial half width of this range is defined by parameter
``FrequencyWidth``. Note, the width of the range can be enlarged
(shrinked) by pressing the “``+``” (“``-``”) key. In the following,
*XCLASS* prints out information of all transitions within the selected
frequency range to the screen, starting with the transition with the
lowest transition frequency. In order to sort the transitions by lower
energies, the user has to press the “``1``” key before selecting the
central frequency. Using the “``2``” (“``3``”) key, sorts the
transitions by the Einstein A coefficients (by a products of upper state
degeneracies and Einstein A coefficients (gA). Pressing the “``0``” key
restores the initial order, i.e. by transition frequencies.

Additionally, the user can reduce the number of transitions by
defining a lower and a upper limit for the lower energies using
parameters ``ElowMin`` and ``ElowMax``, respectively. Furthermore, the
screen output can be limited to a few molecules by using parameter
``SelectMolecule``.

Note, the GUI has to be closed to stop the function!


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``obsdata``: 2D numpy array containing the observational data.

   Note, the data has to be given as a function of frequency (in MHz).

-  ``modeldata``: 2D numpy array containing the synthetic spectrum.

   Note, the data has to be given as a function of frequency (in MHz).

-  ``FreqMin``: minimum frequency (in MHz) for the observational data
   (default: None).

-  ``FreqMax``: maximum frequency (in MHz) for the observational data
   (default: None).

-  ``SelectMolecule``: a (python) list containing the names of all
   molecules which should be considered or a file name including the
   molecules which should be selected.

   Note, if the parameter defines a relative path, this path has to be
   defined relative to the current working directory!

-  ``FrequencyWidth``: defines the width of the frequency interval in
   MHz (selected central frequency :math:`\pm`\ ``FrequencyWidth`` where
   the line information are printed out to the screen. (default: 5)

-  ``ElowMin``: minimum for lower energy (in K) (default: 0) in table
   ``transitions``.

-  ``ElowMax``: maximum for lower energy (in K) (default: :math:`10^6`)
   in table ``transitions``.

-  ``modeldata`` 2D numpy array containing the modeled data,
   (default: None)

   Note, the data has to be given as a function of frequency (in MHz).



Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``None``
   |br| |br|


.. ----------------------------------------------------------------------------------------



.. _api-lineid:

LineID
------


.. code:: python

    # import LineID function
    from xclass import task_LineIdentification

    LineIdentificationCore(Noise = 2.0,
                           MaxOverestimationHeight = 10.0,
                           SourceName = "",
                           DefaultMolfitFile = "",
                           EstimateParamFlag = True,
                           VelBin = 2.0,
                           ElowMax = 1.e99,
                           Tolerance = 10.0,
                           TypeSelection = "all",
                           SmoothValue = 0.0,
                           MaxNumTransInFit = 1e99,
                           SelectedMolecules = [],
                           StrongMoleculeList = [],
                           MinColumnDensityEmis = 1.e8,
                           MinColumnDensityAbs = 1.e8,
                           NumberIteration = 50,
                           AlgorithmXMLFileEstParam = "",
                           AlgorithmXMLFileISO = "",
                           AlgorithmXMLFileSMF = "",
                           AlgorithmXMLFileOverAll = "",
                           ObsXMLFileName = "",
                           ObsDataFileName = None,
                           experimentalData = None,
                           vLSR = 0.0,
                           TelescopeSize = None,
                           BMIN = None,
                           BMAJ = None,
                           BPA = None,
                           Redshift = 0.0,
                           Inter_Flag = False,
                           tBack = None,
                           tSlope = None,
                           N_H = None,
                           beta_dust = None,
                           kappa_1300 = None,
                           DustFileName = "",
                           BackgroundFileName = "",
                           ContPhenFuncID = None,
                           ContPhenFuncParam1 = None,
                           ContPhenFuncParam2 = None,
                           ContPhenFuncParam3 = None,
                           ContPhenFuncParam4 = None,
                           ContPhenFuncParam5 = None,
                           NumModelPixelXX = None,
                           NumModelPixelYY = None,
                           LocalOverlapFlag = None,
                           NoSubBeamFlag = False,
                           EmAbsPATH = None,
                           clusterdef = "",
                           InternalParameterList = {})

This function identifies molecules in a given spectrum and returns a
quantitative description of the data.

In general, the **LineIdentification** function takes all molecules into
account which have at least one transition within the user-defined
frequency range(s) [1]_. These molecules are stored into a so-called
*molecule list*. In order to determine the contribution of each
molecule, the **LineIdentification** function performs so-called *single
molecule fits* for each molecule. If a molecule covers a defined
fraction of the spectrum the molecule is “for now” identified and the
optimized molfit file is append to a so-called *overall molfit file*
which describes the contribution of all identified molecules. After all
single molecule fits are done, the **LineIdentification** function
performs a *final fit*, using the overall molfit file created before.


Input parameters:
^^^^^^^^^^^^^^^^^

-  ``Noise``: noise level (in K), (default: 2.0 K). All parts of the
   spectrum with intensities lower than the noise level are ignored.

   The usage of an observational xml file offers the possibility to
   specify a noise level for each frequency range. For that
   purpose, a tag called ``NoiseLevel``, see below, has to be defined for
   each frequency range for all spectra defined in the xml file. If the
   definition is not given for all frequency ranges, the value defined by
   this parameter ``Noise`` is used instead for all frequency ranges of all
   spectra.
   |br| |br|


-  ``MaxOverestimationHeight``: defines the overestimation factor of the
   modeled single molecule spectrum (in %), (default: 10 %).

   Please note, the input parameter ``MaxOverestimationHeight`` has to be
   given in % and does not define the final overestimation limit directly
   which is given by ``MaxOverestimationHeight`` + 100 %.

   If the modeled spectrum does not overestimate the observed spectrum, the
   corresponding molecule is “for now” identified and the fitted molfit
   file is added to the overall molfit file which is used at the end of the
   line identification process to determine the final contribution of each
   molecule.
   |br| |br|


-  ``SourceName``: This parameter defines the path and the name of a source
   (template) molfit file which is used for the single molecule fits.
   Whenever the **LineIdentification** function fits the contribution of
   one of the molecules included in the source molfit file the definitions
   herein are used instead of the definitions in the default molfit file,
   see description below. This offers the possibility to fit the
   contribution(s) of one or more molecules with a different number of
   components, ranges, initial values etc. as defined in the default molfit
   file. In order to perform the single molecule fits for molecules which
   are not described by the source molfit file, the **LineIdentification**
   function uses the definitions in the default molfit file, see below.
   |br| |br|


-  ``DefaultMolfitFile``: This parameter defines the path and name of a
   so-called default molfit file which is used to fit the contribution of
   each molecule.

   The default molfit file defines for one molecule the number of
   components, the ranges and initial values for each parameter.

   During the line identification process the name of the (first) molecule
   defined in the default molfit file is replaced by the name of the
   current molecule.

   NOTE, if the parameter ``DefaultMolfitFile`` defines a relative path,
   the path has to be defined relative to the current working directory!
   |br| |br|


-  ``Tolerance``: defines the max. fraction (in %) of overestimated lines.
   If the fraction of overestimated lines in the result of a single
   molecule fit is lower than the given threshold, the corresponding
   molecule is “for now” identified and the optimized molfit file (and the
   corresponding iso ratios) are considered in the final overall fit
   (default: 10.0).
   |br| |br|


-  ``SelectedMolecules``: A (python) list defining molecules which should
   be excluded from or considered only by the line identification process.

   In general, the **LineIdentification** function considers all molecules
   which are included in the database within the defined frequency
   range(s).

   If the list contains the command words "``known molecules``", the
   **LineIdentification** function adds all known molecules [1]_ to the
   list as well.

   In order to exclude a molecule from the line identification process, the
   name of the molecule has to start with "``--``", e.g. to exclude the
   molecule ``CH3SH;v=0;`` the user has to define
   ``SelectedMolecules = ["--CH3SH;v=0;"]``.

   If the molecule names do not start with "``--``", the
   **LineIdentification** function consider only these molecules.
   |br| |br|


-  ``StrongMoleculeList``: A (python) list including the strong (highly
   abundant) molecules which should be fitted at the beginning
   (default: “[]”).
   |br| |br|


-  ``MinColumnDensityEmis``: min. column density (for core lines) of an
   optimized component of a single molecule fit to be included in the
   *overall* molfit file (default: 0).
   |br| |br|


-  ``MinColumnDensityAbs``: min. column density (for foreground lines) of
   an optimized component of a single molecule fit to be included in the
   *overall* molfit file (default: 0).
   |br| |br|


-  ``NumberIteration``: max. number of iterations (default: 50). This
   parameter is used only if no MAGIX xml files are defined by the
   parameters ``AlgorithmXMLFile`` and ``AlgorithmXMLFileOverAll``.
   |br| |br|


-  ``AlgorithmXMLFileSMF`` (only necessary, if the user wants to use
   another fit algorithm (than Levenberg-Marquardt) for each single
   molecule fit): path and name of a MAGIX xml-file defining settings for
   an algorithm or algorithm tree has to be given. (A relative path has to
   be defined relative to the current working directory!)

   NOTE, if the user specify a xml file, the number of iterations given by
   the parameter ``NumberIteration`` is ignored. The number of iteration is
   then given by the xml file itself. In order to use the implemented fit
   algorithm (Levenberg-Marquardt) clear the ``AlgorithmXMLFileSMF``
   parameter, i.e. ``AlgorithmXMLFileSMF`` = "", and define the max. number
   of iterations by using parameter ``NumberIteration``.
   |br| |br|


-  ``AlgorithmXMLFileOverAll``: only necessary, if the user wants to use
   another fit algorithm (than Levenberg-Marquardt) for the overall fit.
   Therefore, the path and name of a MAGIX xml-file defining settings for
   an algorithm or algorithm tree has to be given. (A relative path has to
   be defined relative to the current working directory!)

   For more information see description of parameter
   ``AlgorithmXMLFileSMF``.
   |br| |br|


-  ``ObsXMLFileName``: (optional) path and name of an obs. xml file
   (recommended procedure), (default: ``""``), see Sect.
   ":ref:`myxclassfit-obs-xml-file`" for a detailed description.

   Note, the name of the xml file has to end with ``".xml"``.
   |br| |br|


-  ``ObsDataFileName``: (optional) describes the observational data, if
   no obs. xml file is given, (default: ``None``). There are two options
   for transferring the data to XCLASS:

   -  the parameter describes path and name of an ASCII file
      called observational data file, where the first column describe
      the frequency (in MHz) and the second column the brightness
      temperature (in Kelvin)

      Please note, without using an obs. xml file, it is not possible
      to fit more than one data cube, simultaneously.

   -  the parameter describes a 2d numpy array, where the first column
      describes the frequency (in MHz) and the second column the brightness
      temperature (in Kelvin).
      |br| |br|

-  ``experimentalData``: (optional) alias of ``ObsDataFileName``,
   (default: ``None``)
   |br| |br|


The following parameters are needed, if parameter ``ObsDataFileName`` is
used instead of parameter ``ObsXMLFileName``:

   -  ``vLSR``: velocity (local standard of rest) in km s\ :math:`^{-1}`
      (default: 0) used in the calculation of the synthetic spectra, see
      description for myXCLASS function Sect. ":ref:`api-myxclass`".
      Please note, using a xml-file, the ``vLSR`` parameter can be defined
      for each obs. data file, see Sect. ":ref:`api-myxclass`"!
      |br| |br|


   -  ``TelescopeSize``: size of telescope (default: 1).
      |br| |br|


   -  ``Inter_Flag`` (``True``/``False``): defines, if single dish
      (``False``) or interferometric observations (``True``) are described,
      (default: ``False``).
      |br| |br|


   -  ``tBack``: background temperature (in K), (default: 0).

      Please note, the background temperature and slope have to describe
      the continuum completely, i.e. ``t_back_flag`` is always set to
      ``True``.
      |br| |br|


   -  ``tSlope``: temperature slope (dimensionless), (default: 0).
      |br| |br|


   -  ``N_H``: Hydrogen column density (in cm\ :math:`^{-2}`),
      (default: 0).
      |br| |br|


   -  ``beta_dust``: spectral index for dust (dimensionless), (default: 0).
      |br| |br|


   -  ``kappa_1300``: dust mass opacity kappa
      (cm\ :math:`^2 \,`\ g\ :math:`^{-1}`), (default: 0.01).
      |br| |br|


   -  ``NumModelPixelXX``: (optional) used for sub-beam modeling, describes
      the number of pixels used in x-direction (default: 100).
      |br| |br|


   -  ``NumModelPixelYY``: (optional) used for sub-beam modeling, describes
      the number of pixels used in y-direction (default: 100).
      |br| |br|


   -  ``LocalOverlapFlag`` (``True``/``False``): (optional) take local
      overlap into account (default: ``False``), see
      Sect. :ref:``myxclass-localoverlap``.
      |br| |br|


   -  ``NoSubBeamFlag`` (``True``/``False``): (optional) do not use
      sub-beam description (default: ``False``), see
      Sect. ":ref:`myxclass-molfit-subbeam`",
      i.e. *XCLASS* uses the old source description, see
      Sect. ":ref:`myxclass-molfit-1d`".


Finally, the last parameter is needed to start the **LineIdentification**
function on a cluster
|br| |br|

-  ``clusterdef``: path and name of a file containing information for
   the cluster as described in the CASA cookbook [10]_ (subsection “10.3
   Parallelization control”). In contrast to CASA's “cluster
   configuration file”, the **LineIdentification** function requires
   only two entries for each node: the ``hostname`` of the target node
   where the cluster is deployed and the number of ``cores`` (engines)
   separated by comma. (Comments are marked with the “#” character.)
   Please note, the third column can be used to define the positions of
   the *XCLASS* directory on each computer in the cluster. This is
   essential, if the cluster contains computers with different operating
   systems, e.g. Linux and MAC OS. If no path is defined, the
   **LineIdentification** function assumes that the *XCLASS* interface is
   located in the same directory as the current *XCLASS* interface.

   Note, a “cluster configuration file” described in the CASA cookbook
   can be used as well whereat the definitions for the work
   directories are interpreted as definition for the *XCLASS* directory
   on the different nodes of the cluster. Additionally, the
   definitions of RAM usage and RAM per engine are ignored.

   The following requirements are necessary for all nodes which are
   included in the cluster:

   #. Password-less ssh access from the controller (user) machine into
      all the hosts to be included in the cluster.

      NOTE: This is not necessary when using only "localhost", i.e. if
      the cluster is deployed only on the machine where ``casapy`` is
      running.

   #. *XCLASS* interface, CASA and gfortran (with OpenMP) are installed on
      all nodes of the cluster.

   #. The *XCLASS* job directory must be located in a shared file-system,
      accessible from all nodes comprising the cluster, and mounted in
      the same path of the file-system.

      NOTE: If the cluster contains computers with different operating
      systems, e.g. Linux and MAC OS, the user has to define the
      different paths of the *XCLASS* interface directories.

   Example of a “cluster configuration file” used for the
   **LineIdentification** function:

   ::

          # cluster configuration file
          # node      number of cores      path of XCLASS interface
          anu,        2
          lugal,      3

   In the example described above, the nodes "anu" and "lugal" will be
   used with two (three) cores, respectively.

   NOTE: The total number of cores used on a node of the cluster is
   determined by the number of processors defined in the algorithm xml
   file times the number of cores defined in the “cluster configuration
   file”. For example, the user wants to apply the Levenberg-Marquardt
   algorithm with eight processors on a cluster defined in the example
   above. On node "anu" 16 (:math:`2 \times 8`) cores and on node
   "lugal" 18 (:math:`3 \times 8`) cores are used.
   |br| |br|


-  ``InternalParameterList``: is deprecated
   |br| |br|


Output parameters:
^^^^^^^^^^^^^^^^^^

-  ``IdentifiedLines``: contains the optimized molfit file including the
   fitted parameters of all identified molecules.
   |br| |br|


-  ``JobDir``: absolute path of the job directory created for the
   current run.
   |br| |br|


.. ----------------------------------------------------------------------------------------



Footnotes
---------

.. footnotes
.. [1]
   Please note, the data cube has to be given in the World Coordinate
   System (WCS) described in
   [Greisen_Calabretta_2002]_, [Calabretta_Greisen_2002]_,
   [Greisen_et_al_2006]_.
   The data cubes must have a spectral axis, where the spectral axis can
   also be in velocity units. For the fitting procedure, the spectral
   axis is automatically converted to frequencies (MHz) and the
   intensities to Kelvin. At the end of the fitting procedure, *XCLASS*
   converts the resulting fitting cubes back to the original units.

.. [2]
   See http://ds9.si.edu/site/Home.html for details.

.. [3]
   https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html

.. [4]
   https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.uniform_filter.html

.. [5]
   https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.median_filter.html

.. [6]
   Note, here we assume that the source size is small compared to the
   telescope beam size.

.. [7]
   If BMAJ and BMIN are not defined, we assume BMAJ = BMIN =
   ``TelescopeSize``, see below. For single dish telescopes the FWHM of
   the beam is computed using
   Eq. `[myXCLASS:DiffractionLimit] <#myXCLASS:DiffractionLimit>`__.

.. [10]
   http://casa.nrao.edu/Doc/Cookbook/casa_cookbook.pdf


.. ----------------------------------------------------------------------------------------



References
----------

.. [Virtanen_et_al_2020]   Virtanen, Gommers, Oliphant, Haberland, Reddy,
                           Cournapeau, Burovski, Peterson, Weckesser, Bright,
                           van der Walt, Brett, Wilson, Millman, Mayorov, Nelson,
                           Jones, Kern, Larson, Carey, Polat, Feng, Moore, VanderPlas,
                           Laxalde, Perktold, Cimrman, Henriksen, Quintero, Harris,
                           Archibald, Ribeiro, Pedregosa, van Mulbregt, \& SciPy 1.0
                           Contributors

.. [SanchezMonge_et_al_2018]     Sanchez-Monge, A., Schilke, P., Ginsburg, A.,
                                 Cesaroni, R., \& Schmiedeke, A. 2018,
                                 Astronomy \& Astrophysics, 609, A101

.. [Rohlfs_Wilson_1996]          Rohlfs, K. \& Wilson, T.~L. 1996, Tools of Radio Astronomy

.. [Greisen_Calabretta_2002]     Greisen, E.~W. \& Calabretta, M.~R. 2002,
                                 Astronomy \& Astrophysics, 395, 1061

.. [Calabretta_Greisen_2002]     Calabretta, M.~R. \& Greisen, E.~W. 2002,
                                 Astronomy \& Astrophysics, 395, 1077

.. [Greisen_et_al_2006]          Greisen, E., Calabretta, M., Valdes, F.,
                                 \& Allen, S. 2006, Astronomy \&
                                 Astrophysics, 446, 747



.. ----------------------------------------------------------------------------------------



.. hack to get extra blank line
.. |br| raw:: html

      <br>
