.. index:: Theory Predictions

Theory Predictions
==================

The :doc:`decomposition <Decomposition>` of the input model as a sum of :ref:`elements <element>` is the
first step for confronting the model with the experimental limits.
The next step consists of computing the relevant signal :math:`\sigma \times BR`  
(or *theory predictions*)
for comparison with the experimental limits. Below we describe the procedure
for the computation of the theory predictions after the model has been decomposed.


Computing Theory Predictions
----------------------------

As discussed in :doc:`Database Definitions <DatabaseDefinitions>`, SModelS allows
for two different types of analyses: :ref:`UL analyses <ULanalysis>` and :ref:`EM analyses <EManalysis>`. [*]_ 

Each of them requires different procedures for computing the theoretical predictions.
Since an :ref:`UL analysis <ULanalysis>` contains upper limits for the cross-section of 
a given :ref:`constraint <ULconstraint>` or sum of :ref:`elements <element>`, the corresponding
theoretical prediction must contain contributions only from the :ref:`elements <element>`
appearing in the :ref:`constraint <ULconstraint>`.
On the other hand, a :ref:`EM analysis <EManalysis>` contains limits on the cross-section
for specific signal region(s). In this case all the :ref:`elements <element>` generated by the
:doc:`decomposition <Decomposition>` may contribute (with differing weights or efficiencies)
to the theoretical prediction.

Although the details of the computation procedure differ depending on the type
of analysis, the procedure can always be divided in two main steps:
*Element Selection* and *Element Clustering*. The first step is trivial for :ref:`UL analyses <ULanalysis>`,
but more involved for :ref:`EM analyses <EManalysis>`, while the opposite is true for the clustering of :ref:`elements <element>`.
Once the :ref:`elements <element>` have been selected and clustered, the theory prediction for the analysis is given by
the sum of all the :ref:`element <element>` weights (:math:`\sigma \times BR`) belonging to the same cluster:

.. math::
   \mbox{theory prediction } = \sum_{elements\, in\, cluster} \mbox{element weight}
   :label: thpred

In the case of :ref:`UL analyses <ULanalysis>`, there might be several clusters (see :ref:`Element Clustering <ULcluster>`)
for a given analysis, resulting in a list of theory predictions for the corresponding analysis. Each theory prediction must then
be individually confronted with the analysis experimental upper limit.


Below we describe the method for computing the theory predictions for each type
of analysis separately.

* **Theory predictions are computed using the** `theoryPredictionFor <../../../documentation/build/html/theory.html#theory.theoryPrediction.theoryPredictionFor>`_ **method** 


Theory Predictions for UL Analyses
----------------------------------

In order to compute the signal cross-sections for a given :ref:`UL analysis <ULanalysis>`, so it can be compared
against the analysis upper limits, it is first necessary to select the :ref:`elements <element>` generated by the model 
:doc:`decomposition <Decomposition>` and then cluster them according to their masses.
These two steps are described below. 

.. _ULselection:

Element Selection
^^^^^^^^^^^^^^^^^

An :ref:`UL analysis <ULanalysis>` holds upper limits for the cross-sections of an :ref:`element <element>`
or sum of :ref:`elements <element>`. Consequently, the first step for computing the theory predictions for the corresponding
analysis is to select the :ref:`elements <element>` that appear in the :ref:`analysis constraint <ULconstraint>`.
This is conveniently done attributing to each :ref:`element <element>` an :ref:`efficiency <effmap>` equal to 1 (0) 
if the :ref:`element <element>` appears (does not appear) in the :ref:`analysis constraint <ULconstraint>`.
After all the :ref:`elements <element>` weights (:math:`\sigma \times BR`) have been rescaled by these ''trivial'' efficiencies, only the ones
with non-zero weights are relevant for the analysis.
The :ref:`element <element>` selection is then trivially achieved by selecting all the :ref:`elements <element>` with non-zero weights.

The procedure described above is illustrated graphically in the figure below for the simple example where the :ref:`analysis constraint <ULconstraint>`
is :math:`[[[e^+]],[[e^-]]]\,+\,[[[\mu^+]],[[\mu^-]]]`.

.. image:: images/ULselection.png
   :height: 500px 



* **The element selection is implemented by the** `getElementsFrom <../../../documentation/build/html/theory.html#theory.theoryPrediction._getElementsFrom>`_ **method**

.. _ULcluster:

Element Clustering
^^^^^^^^^^^^^^^^^^

Naively one would expect that after all the :ref:`elements <element>` appearing in the :ref:`analysis constraint <ULconstraint>`
have been selected, it is trivial to compute the theory prediction for the analysis: one must simply sum up the weights (:math:`\sigma \times BR`) of all the :ref:`elements <element>`.
However, the selected :ref:`elements <element>` usually differ in their masses [*]_ and the analysis
experimental limit (see :ref:`UL analysis <ULconstraint>`) assumes that all the :ref:`elements <element>` appearing
in the :ref:`analysis constraint <ULconstraint>` have the same mass (or mass array).
As a result, the selected :ref:`elements <element>` must be grouped into *clusters* of equal masses.
When grouping the :ref:`elements <element>`, however, one must allow for small mass differences, 
since the experimental efficiencies should not be strongly sensitive to small mass
differences. For instance, assume two :ref:`elements <element>` contain identical mass arrays, except for the parent masses
which differ by 1 MeV. In this case it is obvious that for all experimental purposes the two :ref:`elements <element>`
have identical masses and should contribute to the same theory predictions (e.g. their weights should be
added when computing the signal cross-section). 
Unfortunately there is no way to
unambiguously define ''similar masses'' and the definition should be analysis-dependent, since
different analysis will be more or less dependent to mass differences. SModelS uses an analysis dependent
measure of the distance between two :ref:`element <element>` masses, as described in :ref:`Mass Distance <massdist>`.


If two of the selected :ref:`elements <element>` have a :ref:`mass distance <massdist>` smaller
than a maximum value (defined by `maxDist <../../../documentation/build/html/theory.html#theory.clusterTools.clusterElements>`_),
they are gouped in the same mass cluster, as illustrated by the example below:



.. image:: images/ULcluster.png
   :height: 550px


Once all the :ref:`elements <element>` have been clustered, their weights can finally be added together
and compared against the experimental upper limit.



* **The clustering of elements is implemented by the** `clusterElements <../../../documentation/build/html/theory.html#theory.clusterTools.clusterElements>`_  **method**.

.. _massdist:  

Mass Distance
^^^^^^^^^^^^^

As mentioned :ref:`above <ULcluster>`, in order to cluster the :ref:`elements <element>` it is necessary
to determine whether two :ref:`elements <element>` have similar masses (see :ref:`Element <element>` and :ref:`Bracket Notation <bracketnotation>`
for more details on :ref:`element <element>` mass).
Since an absolute definition of ''similar masses'' is not possible and the sensitivity to mass differences
depend on the analysis, SModelS uses an analysis-dependent definition. For each :ref:`element <element>`'s mass array,
the analysis upper limit for the corresponding mass values is obtained from the :ref:`UL analysis <ULanalysis>`.
This way, each mass array is mapped to a single number (the cross-section upper limit for the analysis).
Then the distance between the two :ref:`element <element>`'s masses is simply given by the relative difference between their respective
upper limits. More explicitly:

.. math::

   \mbox{Element } A\; (& M_A = [[M1,M2,...],[m1,m2,...]]) \rightarrow \mbox{ Upper Limit}(M_A) = x\\
   \mbox{Element } B\; (& M_B = [[M1',M2',...],[m1',m2',...]]) \rightarrow \mbox{ Upper Limit}(M_B) = y\\
                                       & \Rightarrow \mbox{mass distance}(A,B) = \frac{|x-y|}{(x+y)/2}
   
where :math:`M_A,M_B` (:math:`x,y`) are the mass arrays (upper limits) for the :ref:`elements <element>` A and B, respectively.
If the mass distance of two :ref:`elements <element>` is smaller than `maxDist <../../../documentation/build/html/theory.html#theory.clusterTools.clusterElements>`_,
the two masses are considered similar.

Notice that the above definition of mass distance quantifies the experimental analysis
sensitivity to mass differences, which is the relevant parameter when :ref:`clustering elements <ULcluster>`.
Also, a check is performed to ensure that masses with very distinct values but similar upper limits are not
clustered together.

* **The mass distance function is implemented by the** `distance <../../../documentation/build/html/theory.html#theory.auxiliaryFunctions.distance>`_ **method**



Theory Predictions for EM Analyses
----------------------------------

In order to compute the signal cross-sections for a given :ref:`EM analysis <EManalysis>`, so it can be compared
against the analysis limits, it is first necessary to apply the :ref:`analysis efficiencies <effmap>` to all the :ref:`elements <element>` generated by the model 
:doc:`decomposition <Decomposition>`. This procedure is similar (in nature) to the :ref:`Element Selection for UL an analysis <ULselection>`
applied in the case of an :ref:`UL analysis <ULanalysis>`.
After the :ref:`element <element>`'s weights have being rescaled by the corresponding efficiencies,
all of them can be grouped together in a single cluster, which will provide a single theory prediction (signal
cross-section) for the analysis. Hence the :ref:`element clustering <EMcluster>` discussed below is completely trivial.
On the other hand the :ref:`element selection <EMselection>` is slightly more involved than in the :ref:`UL analysis <ULanalysis>`
case and will be discussed in more detail.::


   Note: Efficiency Map analyses are not yet functional in the public release!!!


.. _EMselection:

Element Selection
^^^^^^^^^^^^^^^^^

The element selection for the case of a :ref:`EM analysis <EManalysis>` consists of rescaling all the :ref:`elements <element>`
weights by their efficiencies, according to the :ref:`efficiency map <effmap>` of the corresponding analysis.
The efficiency for a given analysis depends both on the :ref:`element <element>` mass and on its topology and particle content. 
In practice the efficiencies for most of the :ref:`elements <element>` will be extremely small (or zero), hence only a subset effectively
contributes after the element selection  [*]_.

In the figure below we illustrate the element selection for the case of  a :ref:`EM analysis <EManalysis>`:

.. _EMselectionfig:

.. image:: images/EMselection.png
   :height: 500px 

If, for instance, the analysis being considered vetoes :math:`jets` and :math:`\tau`'s in the final state, 
we will have :math:`eff_2,eff_4 \simeq 0` for the example in the :ref:`figure above <EMselectionfig>`.
Nonetheless, the element selection for a :ref:`EM analysis <EManalysis>` is usually more inclusive than
the one applied for the :ref:`UL analysis <ULanalysis>`, resulting in larger values for the theory prediction.

* **The element selection is implemented by the** `getElementsFrom <../../../documentation/build/html/theory.html#theory.theoryPrediction._getElementsFrom>`_ **method**

.. _EMcluster:

Element Clustering
^^^^^^^^^^^^^^^^^^

Unlike the clustering required in the case of :ref:`UL analysis <ULanalysis>` 
(see :ref:`Element Clustering for an UL analysis <ULcluster>`), after the efficiencies have been
applied to the element's weights, there is no longer the necessity to group the :ref:`elements <element>`
according to their masses, since the mass differences have already been accounted for by the different efficiencies.
As a result, after the :ref:`element selection <EMselection>` all elements belong to a single cluster.


* **The (trivial) clustering of elements is implemented by the** `clusterElements <../../../documentation/build/html/theory.html#theory.clusterTools.clusterElements>`_  **method**.


Confronting Predictions with Experimental Limits
------------------------------------------------

Once the :ref:`elements <element>` generated by the model :doc:`decomposition <Decomposition>`
have passed the *Element Selection* and *Clustering* processes, the theory predictions for a specific analysis
are given by the sum of all the :ref:`element <element>`'s weights belonging to the same cluster (see :eq:`thpred`).
In the case of :ref:`UL analyses <ULanalysis>`, where there can be more than one cluster, there is a list of
theory predictions (one for each cluster) for a given analysis.

The cluster total weight can then finally be compared to the experimental limits for the corresponding analysis.
In the case of :ref:`UL analyses <ULanalysis>` the limit is simply the cross-section upper limit provided by
the experimental publication or conference note (see :ref:`Upper Limit analysis <ULanalysis>`).

The procedure described above can be applied to all the analyses in the database, resulting
in a list of theory predictions and upper limits for each analysis. A model can then be considered
excluded by the experimental results if, for one or more analysis, we have *theory prediction* :math:`>` *upper limit* [*]_.

* **The upper limits for a given**  :ref:`UL analysis <ULanalysis>` **can be obtained by the** `getUpperLimitFor <../../../documentation/build/html/theory.html#theory.analysis.ULanalysis.getUpperLimitFor>`_  **method**.




.. [*] *Note that* :ref:`EM analyses <EManalysis>` *are not yet functional in the public release!*
.. [*] When refering to an :ref:`element <element>` mass, we mean all the :ref:`intermediate state <odd states>` masses
   appearing in the :ref:`element <element>` (or the :ref:`element <element>` mass array). Two :ref:`elements <element>` are considered to have identical
   masses if their mass arrays are identical (see :ref:`Element <element>` and :ref:`Bracket Notation <bracketnotation>`
   for more details). 
.. [*] The number of :ref:`elements <element>` passing the selection also depends on the availability of efficiency maps
   for the :ref:`elements <element>` generated by the decomposition. Whenever there are no efficiencies available for a
   element, the efficiency is taken to be zero.
.. [*] The statistical significance of the exclusion statement is difficult to quantify exactly, since the model
   is being tested by a large number of analyses simultaneoustly.
