.. include:: <isogrk1.txt>
.. index:: mupp
.. _mupp:

mupp - |mgr|\SR Parameter Plotter
=================================

``mupp`` is a little helper program which allows to quickly plot a collection of msr-file parameters,
as for instance generated by :ref:`msr2data <msr2data>`. It can handle ``db``- and ``dat``-files.
Also a collection of ``msr``-files can be invoked. ``mupp`` is heavily inspired by |mgr|\View (see
`here <http://musr.org/muview/>`_).

``mupp`` can be operated from within as graphical user interface or via a command line scripting interface.
The ``mupp`` GUI can be invoked either directly from the command line or from within :ref:`musredit <musredit-sec>`.

.. index:: mupp-gui

The Graphical User Interface
----------------------------

A typical setting could look like this

.. image:: ../images/mupp-gui-0.*

1. shows the list of loaded collections. A collection is defined as ``db``- or ``dat``-file (typically the 
   output from :ref:`msr2data <msr2data>`). If you call the open-dialog and select a collection of
   ``msr``-files, ``mupp`` will call ``msr2data`` and tries to generate a collection on-the-fly.
2. in this list, the data-tags of the currently selected collection is presented. The data-tags can be
   directly dragged over to the ``x``- and ``y``-axis list. Another way is to select the data-tag
   wished and click ``add X`` to add the selected data-tag to the ``x``-axis list. Analogous it is done
   for the ``y``-axis.
3. ``x``-axis list. The labels are followed by ``(-X-)`` where the number ``X`` corresponds to the
   selection it corresponds to. The numbering of the collection is as given in the collection list.
4. ``y``-axis list. The labels are followed by ``(-X-)`` where the number ``X`` corresponds to the
   selection it corresponds to. The numbering of the collection is as given in the collection list.
5. ``add X`` allows to add the currently selected data-tag to the ``x``-axis list.   
6. ``add Y`` allows to add the currently selected data-tag to the ``y``-axis list. 
7. ``remove X`` will remove the selected ``x``-axis tag.
8. ``remove Y`` will remove the selected ``y``-axis tag.
9. Often one would like to compare trends of different settings. In the above example each collections
   holds an energy scans for a given temperature. Each collection is measured at a different temperature.
   Now, instead of adding ``x``- and ``y``-axis tags for each collection, you can do the following:
   you add ``x``- and ``y``-axis data-tags for the first collection. Afterwards you select all the other
   collections of interest and click on ``Add Ditto``. ``mupp`` will then add the corresponding
   ``x``- and ``y``-axis data-tags accordingly. This is less error prone and quicker!
10. Clicking the ``Plot`` button will invoke ``mupp_plot`` (a ``ROOT`` based application) which will
    present the data, as shown here
    
    .. image:: ../images/mupp-plot-0.*
      :height: 600px
      
11. ``Remove Collection``: will remove the selected collection
12. ``Refresh Collection``: will reload the collection (``db``- or ``dat``-file). This is often useful
    during beamtime where the collection is growing run-by-run.
13. This is the script command line. Currently it allows to perform the tasks without mouse gambling.
    In the future much more commands are planed. See the ``Help / Cmd's`` for the currently available
    commands.

.. index:: mupp-scripting
    
The Scripting Interface
-----------------------

``mupp`` can also be operated in a scripting like manner. The use cases are plot updates during run time, 
or web-based interaction which requests figures. A script is invoked by the command line option ``-s`` (see
:ref:`mupp command line summary <mupp-usage>`. Currently the following scripting commands are available:

**loadPath <dir>** 
  set the load path to ``<dir>``. Bash variables like $HOME are accepted. This is the path where to look for collection files (``db``- and ``dat``-files).

**load <coll>** 
  will load the collection ``<coll>``.

**selectAll** 
  will select all loaded collections. This means every plot of variable x/y will be carried out to *ALL* collections.
  
**select <nn>** 
  selects collection ``<nn>``, where ``<nn>`` is either the *number* of the collections, or its *name*, *e.g.* 
  select YBCO-40nm-T5K-FC150mT-Escan.db.
  
**addX <label>**   
  add ``<label>`` as a *x*-variable. Only *one* is allowed.
  
**addY <label(s)>**
  add ``<label(s)>`` as *y*-variable. *Multiple* labels are possible.  
  
**savePath <dir>**
  set the save path to ``<dir>``. The place where the macros, and/or the plot output will be saved.  
  
**plot <fln>**
  where ``<fln>`` is the file name with extension under which the plot should be saved.
  
**macro <fln>**
  where ``<fln>`` is the file name under which the root macro should be saved.
  
An example script file ``field-vs-energy.txt`` might look like this:

::

  # This is a comment

  loadPath ./

  load YBCO-40nm-T5K-FC150mT-Escan.db
  load YBCO-40nm-T30K-FC150mT-Escan.db
  load YBCO-40nm-T60K-FC150mT-Escan.db
  load YBCO-40nm-T120K-FC150mT-Escan.db

  selectAll

  addX dataE 
  addY Field

  savePath ./
  plot FieldVsEnergy.pdf

  macro FieldVsEnergy.C

  # end


.. index:: mupp-usage
.. _mupp-usage:

The Usage Summary
-----------------

::
 
  usage: mupp [OPTIONS] [[--path <fit-param-path>] <fit-param-file-names>]

  OPTIONS:
    -h, --help: this help
    -v, --version: current mupp version
    -s <fln>, --script <fln>: <fln> being a mupp script.
    --path <fit-param-path>: path where to look for the <fit-param-file-names>
    <fit-param-file-names>: list of file name(s) to be loaded.
       allowed formats are: db, dat, msr

  SCRIPT COMMANDS:
    Lines starting with '#', '%', or '//' are comments and will be ignored.
    The same is true for empty lines. Comments are also allowed at the end
    for a command, i.e. loadPath ./ # the best place ever.

    loadPath <dir> : set the load path to <dir>. Bash variables like
                     $HOME are accepted.
    load <coll>    : will load a collection <coll>. Currently *.db and *.dat
                     are handled.
    selectAll      : will select all loaded collections. Thie means every plot
                     of variable x/y will be carried out to ALL collections.
    select <nn>    : selects collection <nn>, where <nn> is either the number
                     of the collections, or its name, e.g. 
                     select YBCO-40nm-T5K-FC150mT-Escan.db
    addX <label>   : add <label> as a x-variable. Only one is allowed.
    addY <label(s)>: add <label(s)> as y-variable. Multiple labls are possible.
    savePath <dir> : set the save path to <dir>. The place where the macros,
                     and/or the plot output will be saved.
    plot <fln>     : where <fln> is the file name with extension under which
                     the plot should be saved.
    macro <fln>    : where <fln> is the file name under which the root macro
                     should be saved.