merged develop into resummino, preparing for 2.3.3

ReleaseNotes

@@ -1,9 +1,23 @@
-Release v2.x.x, xxx 2023
+Release v2.3.2, Wed 30 Aug 2023
+=======================================================
+
+  * fixed bug in initialisation of analysis combination
+  * smodels version now printed in all output formats
+
+Release v2.3.1, Mon 17 Jul 2023
 =======================================================
 
   * fixed bug for reading QNUMBERS from SLHA files
   * small fixes in how pythia6 and pythia8 are built
-  * small fix with experimental truncated Gaussian feature
+  * small fix in truncated Gaussian llhd experimental feature
+  * small fix in computation of combined upper limits
+  * combinationmatrices are now forced to be symmetric
+  * added isCombinableWith method also for CombinedDataSets
+  * added a recipe for how to use a combinations matrix
+  * runtime.nCPUs() now returns number of available CPUs, not all CPUs
+  * xseccomputer now has --tempdir option
+  * StatsComputer now has CLs method
+  * changed default prompt width from 1e-8 to 1e-11 GeV in code
 
 
 Release v2.3.0, Tue 23 May 2023

docs/manual/source/Examples.rst

@@ -50,6 +50,7 @@ Examples displaying several functionalities:
 
 * `How to plot likelihoods from analysis combinations <plotCombinedLikelihood.html>`_ (download the Python code :download:`here <recipes/plotCombinedLikelihood.py>`, IPython notebook :download:`here <recipes/plotCombinedLikelihood.ipynb>`)
 
+* `How to use a combinations matrix <combinationsmatrix.html>`_ (download the Python code :download:`here <recipes/combinationsmatrix.py>`, IPython notebook :download:`here <recipes/combinationsmatrix.ipynb>`)
 
 Examples using the cross-section computer:
 ------------------------------------------

docs/manual/source/ReleaseUpdate.rst

@@ -37,6 +37,26 @@ What's New
 ==========
 The major novelties of all releases since v1.0 are as follows:
 
+New in Version 2.3.2:
+^^^^^^^^^^^^^^^^^^^^^
+
+  * fixed bug in initialisation of :ref:`analyses combination <analysesCombination>`
+  * smodels version now printed in all output formats
+
+New in Version 2.3.1:
+^^^^^^^^^^^^^^^^^^^^^
+
+  * fixed bug for reading :ref:`QNUMBERS blocks <qnumberSLHA>` from SLHA files
+  * small fixes in how pythia6 and pythia8 are built
+  * small fix in truncated Gaussian llhd experimental feature
+  * small fix in computation of combined upper limits
+  * combinationmatrices are now forced to be symmetric
+  * added isCombinableWith method also for CombinedDataSets
+  * added a recipe for how to use a `combinations matrix <combinationsmatrix.html>`_
+  * `runtime.nCPUs() <tools.html#tools.runtime.nCPUs>`_ now returns number of available CPUs, not all CPUs
+  * :ref:`xsecComputer <xsecCalc>` now has --tempdir option
+  * StatsComputer now has `CLs <tools.html#tools.statsTools.StatsComputer.CLs>`_ method
+  * changed default prompt width from 1e-8 to 1e-11 GeV in code
 
 New in Version 2.3.0:
 ^^^^^^^^^^^^^^^^^^^^^

docs/manual/source/recipes/combinationsmatrix.ipynb

@@ -0,0 +1,269 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How To: Use a combinations matrix to keep track of combinabilities"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Preparations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Set up the path to SModelS installation folder\n",
+    "import sys; sys.path.append(\".\"); import smodels_paths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import those parts of smodels that are needed for this exercise\n",
+    "from smodels.tools.physicsUnits import GeV\n",
+    "from smodels.experiment.databaseObj import Database\n",
+    "from smodels.theory.theoryPrediction import theoryPredictionsFor, TheoryPredictionsCombiner\n",
+    "from smodels.theory import decomposer\n",
+    "from smodels.tools.physicsUnits import fb\n",
+    "from smodels.particlesLoader import BSMList\n",
+    "from smodels.share.models.SMparticles import SMList\n",
+    "from smodels.theory.model import Model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# a combinations matrix is just a dictionary with combinable analyses as both keys and values.\n",
+    "# we assume symmetricity! (if A is combinable with B, then B is combinable with A)\n",
+    "# Also, CMS results are automatically assumed to be combinable with ATLAS results,\n",
+    "# and 8 TeV with 13 TeV results.\n",
+    "combinationsmatrix = { \"ATLAS-SUSY-2018-41\": [ \"ATLAS-SUSY-2019-08\"]} \n",
+    "# also define a list of analyses we are interested in\n",
+    "analyses = [ \"CMS-SUS-21-002\", \"ATLAS-SUSY-2018-41\", \"ATLAS-SUSY-2019-08\", \"CMS-SUS-20-004\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "here is a visualisation of the combinations matrix for the analyses under consideration:"
+   ]
+  },
+  {
+   "attachments": {
+    "matrix-2.png": {
+     "image/png": "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"
+    }
+   },
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![matrix-2.png](attachment:matrix-2.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "we have selected 4 analyses\n"
+     ]
+    }
+   ],
+   "source": [
+    "## Load the official database:\n",
+    "db = Database(\"official\", combinationsmatrix=combinationsmatrix)\n",
+    "results = db.getExpResults(analysisIDs=analyses, dataTypes = [ \"efficiencyMap\"])\n",
+    "print ( f\"we have selected {len(results)} analyses\" )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['ATLAS-SUSY-2018-41',\n",
+       " 'ATLAS-SUSY-2019-08',\n",
+       " 'CMS-SUS-20-004',\n",
+       " 'CMS-SUS-21-002']"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[ x.globalInfo.id for x in results ]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# the theory we will be using\n",
+    "inputFile = \"inputFiles/slha/ew_ymi2l51r.slha\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# prepare the model\n",
+    "model = Model(BSMparticles=BSMList, SMparticles=SMList)\n",
+    "model.updateParticles(inputFile=inputFile)\n",
+    "# obtain the decomposed model\n",
+    "toplist = decomposer.decompose(model,sigmacut=0.*fb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## run SModelS"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# get the predictions\n",
+    "predictions = list ( theoryPredictionsFor(results, toplist, combinedResults=True ) )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[('ATLAS-SUSY-2018-41', 'r_exp=', 0.869),\n",
+       " ('ATLAS-SUSY-2019-08', 'r_exp=', 0.961),\n",
+       " ('CMS-SUS-21-002', 'r_exp=', 1.158)]"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# let's have a quick look at the predictions, and the (expected) r-values\n",
+    "[ (x.dataset.globalInfo.id, \"r_exp=\", round(x.getRValue(expected=True),3)) for x in predictions ]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "can I combine ATLAS-SUSY-2018-41 with ATLAS-SUSY-2019-08? yes\n",
+      "can I combine ATLAS-SUSY-2018-41 with CMS-SUS-21-002? yes\n",
+      "can I combine ATLAS-SUSY-2019-08 with CMS-SUS-21-002? yes\n"
+     ]
+    }
+   ],
+   "source": [
+    "for i,pr1 in enumerate(predictions[:-1]):\n",
+    "    id1 = pr1.dataset.globalInfo.id\n",
+    "    for pr2 in predictions[i+1:]:\n",
+    "        id2 = pr2.dataset.globalInfo.id\n",
+    "        combinable = pr1.dataset.isCombinableWith(pr2.dataset)\n",
+    "        print ( f\"can I combine {id1} with {id2}? {'yes' if combinable else 'no'}\" )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## combine!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# given [10] from above, we are allowed to combine the three analyses listed below\n",
+    "analyses = [ \"CMS-SUS-21-002\", \"ATLAS-SUSY-2018-41\", \"ATLAS-SUSY-2019-08\"]\n",
+    "combiner = TheoryPredictionsCombiner.selectResultsFrom ( predictions, analyses )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "1.674"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# the combined expected r value must be above the individual expected r-values\n",
+    "round(combiner.getRValue(expected=True),3)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}