OutputDescription.rst

.. index:: Output Description

Output Description

A detailed description of the possible output formats generated by :ref:`running SModelS <runningSModelS>` and their content is given below. For simplicity we will assume that all printer options in the |parameters| are set to True, so the output information is maximal.[1]

Screen (Stdout) Output

The stdout (or :ref:`log output <logOut>`) is intended to provide extensive information about the |database|, the |decomposition|, the |theory predictions| and the :ref:`missing topologies <topCoverage>`. It is most convenient if the input is a single file and not a folder, since the output is quite extensive. If all the options in stdout-printer are set to True (see |parameters|), the screen output contains the following information:

• information about the basic input parameters and the status of the run:

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 1-20

• a list of all the |express| considered (if printDatabase = True). Note that this list corresponds to all the results selected in the database options (see |parameters|). If addAnaInfo = True, for each |expres| entry a list of all the simplified models (or |elements|) constrained by the analysis is also shown using the :ref:`bracket notation <bracketNotation>`:

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 22-34,327-335

• a full list of the |topologies| generated by the |decomposition| (if printDecomp = True). Each |topology| entry contains basic information about the |topology| as well as the number of |elements| with this |topology| and the sum over all the |elements| weights. If addElementInfo = True, the |elements| belonging to each |topology| are also explicitly shown, as well as the |element|'s mass, BSM and SM final state |particles|, weight, the PIDs of the BSM |particles| contributing to the |element| and the element ID:

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 532-594

• a list of all the |theory predictions| obtained and the corresponding |expres| upper limit. For each |expres|, the corresponding id, signal region (|dataset|) and sqrts as well as the constrained simplified models (|txnames|) are printed. After this basic information, the signal cross section (|theory prediction|), the list of :ref:`condition values <ULconditions>` (if applicable) and the corresponding observed upper limit are shown. Also, if available, the expected upper limit is included. If computeStatistics = True, the likelihood for the BSM signal, that for the SM hypothesis, and the maximum likelihood are printed (see :ref:`likelihood calculation <likelihoodCalc>`). Finally, if printExtendedResults = True, basic information about the |elements| being constrained, such as their masses[2], IDs and PIDs, is also shown.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 107644-107765

• information about the combination of results, if combineAnas is defined (available from v2.2 onward):

.. literalinclude:: /images/gluino_squarks.slha.log
  :lines: 109774-109777

• summary information about the :ref:`missing topologies <topCoverage>`, if testCoverage = True. The total missing topology cross section corresponds to the sum of cross sections of all |elements| which are not tested by any |expres|. The cross section for missing topologies with prompt (displaced) decays corresponds to the total signal cross section going into prompt (displaced) decays which are not tested by any displaced |expres| of type prompt (displaced) (see :ref:`simplified model coverage <topCoverage>` for more details). If the |element| is constrained by one or more |express|, but its masses and/or widths are outside the efficiency or upper limit grids (see |EMrs| and |ULrs|), its cross section is included in the total cross section outside the grid.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 109781-109784

• detailed information about the missing topologies with highest cross sections. The |element| cross section (weight) as well as the description of its final states (in :ref:`bracket notation <bracketNotation>`) is included for each distinct :ref:`coverage group <coverageGroups>`. If addCoverageID = True, all the |elements| IDs contributing to the missing topology are shown. These IDs can be traced back to the corresponding |elements| using the |decomposition| information obtained with printDecomp = True and addElementInfo = True.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 109786-109794

• information about the missing topologies with displaced decays. If addCoverageID = True, all the |elements| IDs contributing to the missing topology are shown.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 109800-109801

• information about the missing topologies with prompt decays. If addCoverageID = True, all the |elements| IDs contributing to the missing topology are shown.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 109802-109814

• detailed information about the topologies which are outside the |express| grid. If addCoverageID = True, all the |elements| IDs contributing to the missing topology are shown.

.. literalinclude:: /images/gluino_squarks.slha.log
   :lines: 109815-109827

Log Output

The log-type output is identical to the :ref:`screen output <screenOut>`, except that it is redirected to a .log file. The filename is set as the <input file>.log and stored in the output folder (see the :ref:`runSModelS options <runSModelS>`).

Summary File Output

The summary-type output is similar to the :ref:`screen output <screenOut>`, but restricted to the list of |theory predictions| and model :ref:`coverage <topCoverage>`. The output is printed to the file <input file>.smodels and stored in the output folder (see the :ref:`runSModelS options <runSModelS>`).

Below we describe in detail the blocks contained in the summary output:

• information about the basic input parameters and the status of the run:

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 1-20

• a list of all the |theory predictions| obtained and the corresponding |expres| upper limit. If expandedSummary = False only the most constraining |expres| is printed. For each |theory prediction| entry, the corresponding |expres| id, the signal region (|dataset|) used (only for |EMrs|) and the |expres| sqrts is printed. Furthermore, the |txnames| contributing to the signal cross section, the theory cross section (Theory_Value), the observed upper limit (Exp_limit), the (theory cross section)/(observed upper limit) ratio (r) and, when available, the (theory cross section)/(expected upper limit) ratio (r_expect) are also printed. For |ULrs| the condition violation (see :ref:`upper limit conditions <ULconditions>`) is also included. Finally, if computeStatistics = True, the likelihood values (for |EMrs|) are printed:

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 22-41

• the maximum r value, that is the highest (theory cross section)/(observed upper limit) ratio. If this value is greater or equal 1, the input model is likely excluded by one of the |express| (see :ref:`confronting predictions <confrontPredictions>`). For a more informed statistical interpretation, from v2.1 onward the ATLAS and CMS analyses with highest available expected r values are reported in addition.

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 513-515

• information about the combination of results, if combineAnas is defined (available from v2.2 onward):

.. literalinclude:: /images/gluino_squarks.slha.smodels
 :lines: 517-520

• summary information about the :ref:`missing topologies <topCoverage>`, if testCoverage = True. The total missing topology cross section corresponds to the sum of cross sections of all |elements| which are not tested by any |expres|. The cross section for missing topologies with prompt (displaced) decays corresponds to the total signal cross section going into prompt (displaced) decays which are not tested by any displaced |expres| of type prompt (displaced) (see :ref:`simplified model coverage <topCoverage>` for more details). If the |element| is constrained by one or more |express|, but its masses and/or widths are outside the efficiency or upper limit grids (see |EMrs| and |ULrs|), its cross section is included in the total cross section outside the grid.

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 524-527

• detailed information about the missing topologies with highest cross sections. The |element| cross section (weight) as well as the description of its final states (in :ref:`bracket notation <bracketNotation>`) is included for each distinct :ref:`coverage group <coverageGroups>`.

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 529-541

• information about the missing topologies with displaced decays.

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 543-544

• information about the missing topologies with prompt decays.

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 545-557

• information about the topologies which are outside the |express| grid

.. literalinclude:: /images/gluino_squarks.slha.smodels
   :lines: 558-570

Python Output

The Python-type output is similar to the :ref:`screen output <screenOut>`, however converted to a Python dictionary. If all options are set to True, it includes information about the |decomposition|, the list of |theory predictions| and :ref:`simplified model coverage <topCoverage>`. The output is printed to the file <input file>.py and stored in the output folder (see the :ref:`runSModelS options <runSModelS>`).

Below we describe in detail the dictionary keys and values contained in the Python dictionary output:

• information about the basic input parameters and the status of the run stored under the OutputStatus key:

.. literalinclude:: /images/gluino_squarks.slha.py
   :lines: 1-2

• a full list of the |elements| generated by the |decomposition| (if addElementList = True) stored under the Element key. Each list entry contains basic information about the |elements|. The list can be considerably long, so it is recommended to set addElementList to False, unless the |decomposition| information is required by the user.

.. literalinclude:: /images/gluino_squarks.slha.py
   :lines: 3-4, 41-42

• a list of all the |theory predictions| obtained for the |express|, stored under the ExptRes key. For each list entry, the corresponding result id, the |expres| type (if |ULr| or |EMr|), the signal region (|dataset| ID), the sqrts and luminosity, the constrained simplified models (|txnames|), the signal cross section (theory prediction), the corresponding observed upper limit and the maximum condition violation (see :ref:`upper limit conditions <ULconditions>`) are shown. Furthermore, the masses and widths[3] of the |elements| contributing to the signal cross section, the individual contribution of each |txname| (if addTxWeights = True) and the likelihood values (if computeStatistics = True) are also included.

.. literalinclude:: /images/gluino_squarks.slha.py
   :lines: 55-55

• information about the combination of results, if combineAnas is defined (available from v2.2 onward):

.. literalinclude:: /images/gluino_squarks.slha.py
   :lines: 60-60

• the total cross section in each :ref:`missing topology group <coverageGroups>` (if testCoverage = True) followed by a list of |elements| contributing to the group. For each missing topology (element) the missing cross section (weight), the IDs of the |elements| contributing to the topology and its description in :ref:`bracket notation <bracketNotation>` is included (see :ref:`missing topology group <coverageGroups>`).

.. literalinclude:: /images/gluino_squarks.slha.py
   :lines: 56-59

XML Output

The xml-type output is identical to the :ref:`python output <pyOut>`, however converted to a xml format. The output is printed to the file <input file>.xml and stored in the output folder (see the :ref:`runSModelS options <runSModelS>`).

Since the output information and options are the same as described for :ref:`python output <pyOut>`, we simply show below an excerpt of the xml file to illustrate the output format:

.. literalinclude:: /images/gluino_squarks.slha.xml
   :language: xml
   :lines: 13-39

SLHA Output

An SLHA-type output format is also available containing a summary of the |theory predictions| and :ref:`simplified model coverage <topCoverage>`. The file contains the SLHA-type blocks: SModelS_Settings, SModelS_Exclusion and SModelS_Coverage. Below we give a description of each block together with a sample output.

• information about the main input parameters:

.. literalinclude:: /images/gluino_squarks.slha.smodelsslha
   :lines: 1-11

• information about the status of the input model: excluded (1), not excluded (0) or not tested (-1):

.. literalinclude:: /images/gluino_squarks.slha.smodelsslha
   :lines: 13-14

• followed by the list of experimental results. If expandedOutput = True, all results are printed. Otherwise, if the model is excluded, all results with r-value greater than one are shown and if the point is not excluded, only the result with the highest r-value is displayed. For each experimental result, the :ref:`Txname <TxName>`, the r-value, the :ref:`condition violation <ULconditions>` and the experimental result ID are shown. If computeStatistics = True, the likelihood values for |EMrs| are also printed:

.. literalinclude:: /images/gluino_squarks.slha.smodelsslha
   :lines: 15-23

• information about the combination of results, if combineAnas is defined (available from v2.2 onward):

.. literalinclude:: /images/gluino_squarks.slha.smodelsslha
 :lines: 1175-1181

• the label of each :ref:`coverage group <coverageGroups>` (first entry) and the total cross section in each group (second entry) (if testCoverage = True):

.. literalinclude:: /images/gluino_squarks.slha.smodelsslha
   :lines: 1184-1192

Multiple Files Summary Output

When running SModelS over multiple files it might be desirable to have a simplified output with a summary of the results for each input file. Since version 2.1 this information is stored by default in the 'summary.txt' file in the output folder. This text file contains a single line for each input file and provides basic information about the SModelS results. This information includes the most constraining analysis (the one with largest observed r), the respective expected r-value (if available) and the most sensitive ATLAS and CMS analyses (the ones with largest expected r), as shown below:

.. literalinclude:: /images/scan_summary.txt
   :lines: 1-8

[1]	Some of the output may change depending on the code and database versions used.

[2]	The mass shown corresponds to an average mass over all the |elements| contributing to the theory prediction. In the case where the |elements| have distinct |topologies| no mass is shown.

[3]

For particles considered with prompt decays (see :ref:`promptWidth parameter <parameterFileModel>`), the width is replaced by 'prompt', while for particles considered stable (see see :ref:`stableWidth parameter <parameterFileModel>`), the width is replaced by 'stable'. If more than one |element| contributes to the theory prediction, the average widths and masses of the BSM states are shown.