Merge branch 'cms-analysis:main' into main

.clang-tidy

@@ -0,0 +1,6 @@
+---
+Checks: -*,
+  ,modernize-use-override,
+WarningsAsErrors: '*'
+HeaderFilterRegex: ''
+...

.github/workflows/ci.yml

@@ -28,17 +28,18 @@ jobs:
     strategy:
       matrix:
         python: ["3.8"]
-        root: ["6.22"]
+        root: ["6.22"]  
         include:
           # to deprecate (11_2_X py2)
           - python: "2.7.18"
-            root: "6.22.0"
-          # python 3.9 root 6.24 (12_3_X)
-          - python: "3.9"
-            root: "6.24"
+            root: "6.22.0" 
           # python 3.10 root 6.26
           - python: "3.10"
             root: "6.26.4"
+          # python 3.10 root 6.32 (not available yet)
+          #- python: "3.10"
+          #  root: "6.32" # version 6.30.07 where the conflicting classes were removed from root is not available, so compiling with 6.32.00 where this issue is resolved
+
     runs-on: ubuntu-latest
     name: Compile (py${{ matrix.python }}, root${{ matrix.root }})
 

.github/workflows/cvmfs-ci.yml

@@ -0,0 +1,61 @@
+name: CI with CVMFS
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test_workflow:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        IMAGE: ["cmscloud/al9-cms"]
+        CMSSW_VERSION: ["CMSSW_14_1_0_pre4"] # ROOT v6.30/07
+        SCRAM_ARCH: ["el9_amd64_gcc12"]
+        include:
+          - IMAGE: "cmscloud/cc7-cms"
+            CMSSW_VERSION: "CMSSW_11_3_4" # ROOT v6.22
+            SCRAM_ARCH: "slc7_amd64_gcc900"
+          - IMAGE: "cmscloud/al9-cms"
+            CMSSW_VERSION: "CMSSW_14_0_0_pre1" # ROOT v6.26/11
+            SCRAM_ARCH: "el9_amd64_gcc12"
+
+    name: Test with ${{ matrix.CMSSW_VERSION }}
+    steps:
+      # checkout the files of this repository
+      - uses: actions/checkout@v4
+      - uses: cvmfs-contrib/github-action-cvmfs@v4
+        with:
+          cvmfs_repositories: 'cms.cern.ch'
+      - uses: rhaschke/docker-run-action@v5
+        with:
+          image: ${{ matrix.IMAGE }}
+          shell: bash
+          options: -v /cvmfs:/cvmfs:shared -v ${{ github.workspace }}:/work/CombinedLimit -w /home/cmsusr -e CMSSW_VERSION=${{ matrix.CMSSW_VERSION }} -e SCRAM_ARCH=${{ matrix.SCRAM_ARCH }}
+          run: | 
+            ls /work/CombinedLimit
+            ls /cvmfs/cms.cern.ch | grep common
+            source /cvmfs/cms.cern.ch/cmsset_default.sh
+            scram project ${CMSSW_VERSION}
+            source /cvmfs/cms.cern.ch/cmsset_default.sh
+            cd ${CMSSW_VERSION}/src
+            cmsenv
+            mkdir -p HiggsAnalysis
+            cp -r /work/CombinedLimit HiggsAnalysis/
+            scramv1 b -j$(nproc)
+            echo ${PATH}
+            root --version
+            combine --help
+            combine HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-2-template-analysis.txt -M HybridNew --LHCmode LHC-limits --rMax 2.0 --clsAcc 0.01
+            combine HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-3-parametric-analysis.txt -M HybridNew --LHCmode LHC-significance -T 100 --mass 125
+            combine HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-3-parametric-analysis.txt -M Significance --mass 125
+            combine HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-1-counting-experiment.txt -M MarkovChainMC --tries 100
+            text2workspace.py HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-5-multi-signal.txt -P HiggsAnalysis.CombinedLimit.PhysicsModel:floatingXSHiggs --PO modes=ggH,qqH -o datacard-5-multi-signal.root --mass 125
+            combine datacard-5-multi-signal.root -M MultiDimFit --algo singles --mass 125
+            combine HiggsAnalysis/CombinedLimit/data/tutorials/CAT23001/datacard-5-multi-signal.txt -M ChannelCompatibilityCheck --mass 125
+
+
+

.github/workflows/docs.yml

@@ -22,4 +22,4 @@ jobs:
         git fetch origin gh-pages --depth=1
         git config user.name ci-bot
         git config user.email [email protected]
-        mike deploy --push v9.2.0 latest 
+        mike deploy --push v10.0.X latest 

BuildFile.xml

@@ -9,6 +9,7 @@
 <lib name="Smatrix"/>
 <use   name="boost_program_options"/>
 <use   name="boost_filesystem"/>
+<flags CXXFLAGS="-DBOOST_BIND_GLOBAL_PLACEHOLDERS -Wno-free-nonheap-object"/>
 <export>
    <lib name="1"/>
 </export>

CMakeLists.txt

@@ -0,0 +1,138 @@
+cmake_minimum_required( VERSION 3.11 FATAL_ERROR )
+set(CMAKE_CXX_STANDARD 17)
+project(CMSCombine VERSION 0.0.1)
+
+option( MODIFY_ROOTMAP "Modify generated Rootmap to take out classes already bundled in StatAnalysis" FALSE )
+
+# Can build with CMake after e.g. setting up StatAnalysis release like this:
+# export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
+# source $ATLAS_LOCAL_ROOT_BASE/user/atlasLocalSetup.sh; asetup StatAnalysis,0.3.2
+# mkdir build; cd build
+# cmake path/to/source # change this path to where-ever you cloned Combine repo to
+# make -j4
+
+list(APPEND CMAKE_PREFIX_PATH $ENV{ROOTSYS})
+find_package( ROOT REQUIRED COMPONENTS Core MathMore RooFitCore RooFit RooStats Minuit HistFactory RooFitHS3)
+find_package(Eigen3 REQUIRED)
+find_package(Vdt)
+find_package(LCG QUIET) # only used for FindBoost in StatAnalysis
+find_package( Boost REQUIRED COMPONENTS program_options filesystem )
+
+message(STATUS "Using ROOT From: ${ROOT_INCLUDE_DIRS}")
+include(${ROOT_USE_FILE})
+
+include_directories(${ROOT_INCLUDE_DIRS})
+include_directories(BEFORE ${CMAKE_CURRENT_SOURCE_DIR})
+add_definitions(${ROOT_CXX_FLAGS})
+
+set(LIBNAME CMSCombine)
+
+file(GLOB HEADERS RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} interface/*.h*)
+file(GLOB SOURCES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} src/*.c*)
+
+# includes require "HiggsAnalysis/CombinedLimit" prefix in many places
+# so create a symlink in the build dir
+file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/HiggsAnalysis)
+execute_process(COMMAND ${CMAKE_COMMAND} -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/HiggsAnalysis/CombinedLimit" )
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+
+ROOT_GENERATE_DICTIONARY(G__${LIBNAME} HiggsAnalysis/CombinedLimit/src/classes.h LINKDEF src/classes_def.xml
+        MODULE ${LIBNAME}
+        OPTIONS --deep)
+add_library(${LIBNAME} SHARED ${SOURCES} G__${LIBNAME}.cxx)
+set_target_properties(${LIBNAME} PROPERTIES PUBLIC_HEADER "${HEADERS}")
+target_link_libraries (${LIBNAME} Eigen3::Eigen ${ROOT_LIBRARIES} ${Boost_LIBRARIES} VDT::VDT)
+
+add_executable(combine bin/combine.cpp)
+target_link_libraries(combine PUBLIC ${LIBNAME})
+
+
+# Create empty __init__.py file in the build directory that will be installed
+# in the Python library directories.
+set(empty_init_py "${CMAKE_CURRENT_BINARY_DIR}/__init__.py")
+
+if(MODIFY_ROOTMAP)
+        # edit the generated rootmap in-situ before installation
+
+        # Define the path to the generated file
+        set(GENERATED_FILE_PATH "${CMAKE_CURRENT_BINARY_DIR}/lib${LIBNAME}.rootmap")
+
+        # Define the custom command to search and replace in-place
+        add_custom_command(
+          OUTPUT "${GENERATED_FILE_PATH}.bak"  # Declare the generated file as output
+          DEPENDS "${GENERATED_FILE_PATH}"  # Ensure it depends on the original generated file
+          COMMAND sed -i.bak -e "/class RooParamKeysPdf/d"
+                            -e "/class RooStarMomentMorph/d"
+                            -e "/class RooStats::HistFactory::RooBSpline/d"
+                            -e "/class RooStats::HistFactory::RooBSplineBases/d" 
+                            -e "/class ResponseFunction/d"
+                            -e "/class RooTwoSidedCBShape/d"
+                            "${GENERATED_FILE_PATH}"
+          COMMENT "Removing conflicting classes from generated rootmap"
+        )
+
+        # Define a custom target that depends on the custom command output
+        add_custom_target(
+                ModifyRootmapFile  # Name of the custom target
+                DEPENDS "${GENERATED_FILE_PATH}.bak"  # Ensure the custom command is executed
+        )
+
+        # Add the custom target as a dependency to another target to ensure it's built
+        add_dependencies(combine ModifyRootmapFile)
+endif()
+
+#####################
+# Installation part #
+#####################
+
+
+# Install the dictionaries.
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/lib${LIBNAME}_rdict.pcm
+        ${CMAKE_CURRENT_BINARY_DIR}/lib${LIBNAME}.rootmap
+        DESTINATION lib)
+
+# Install the libraries and header files.
+install(TARGETS ${LIBNAME}
+        LIBRARY DESTINATION lib
+        PUBLIC_HEADER DESTINATION include/HiggsAnalysis/CombinedLimit/interface
+        )
+# dictionary requires classes.h to be in include path exactly as it was specified
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/HiggsAnalysis/CombinedLimit/src/classes.h
+        DESTINATION include/HiggsAnalysis/CombinedLimit/src)
+
+# Install the "combine" executable in the bin directory.
+install(TARGETS combine DESTINATION bin)
+
+# Install the scripts like "text2workspace" to the bin directory.
+install(DIRECTORY scripts/ DESTINATION bin)
+
+# This block is commented out for now, while using the less sophisticated location below
+# Check if the Python library installation directory is outside the install
+# prefix. If it is, we error out because CMake should not install files outside
+# the prefix. In the future, one can imagine to let the user choose where the
+# Python libraries get installed in the prefix with a CMake configuration flag.
+#find_package(Python COMPONENTS Interpreter Development) # To get the Python library install directory into Python_SITELIB
+#cmake_path(IS_PREFIX CMAKE_INSTALL_PREFIX "${Python_SITELIB}" sitelib_in_prefix)
+#if(NOT ${sitelib_in_prefix})
+#    message( FATAL_ERROR "Your Python library installation directory ${Python_SITELIB} "
+#            "is outside the install prefix ${CMAKE_INSTALL_PREFIX}! "
+#            "This is not supported for now. Consider changing the install prefix "
+#            "with the -DCMAKE_INSTALL_PREFIX:PATH=<path> cmake configuration option.")
+#endif()
+#
+## The the Python library installation directory relative to the install prefix.
+#file(RELATIVE_PATH Python_SITELIB_IN_PREFIX ${CMAKE_INSTALL_PREFIX} ${Python_SITELIB})
+
+set(Python_SITELIB_IN_PREFIX "python")
+
+
+message (STATUS "Using Python install location:" ${Python_SITELIB_IN_PREFIX})
+# The python package will be installed in such a way that the original
+# CMSSW-style directory structure is kept, for maximal compatibility.
+install(DIRECTORY python/ DESTINATION ${Python_SITELIB_IN_PREFIX}/HiggsAnalysis/CombinedLimit)
+
+# Create empty __init__.py files in the Python package subdirectories such that
+# the Python imports work.
+file(TOUCH ${empty_init_py})
+INSTALL(FILES ${empty_init_py} DESTINATION ${Python_SITELIB_IN_PREFIX}/HiggsAnalysis)
+INSTALL(FILES ${empty_init_py} DESTINATION ${Python_SITELIB_IN_PREFIX}/HiggsAnalysis/CombinedLimit)

Makefile

@@ -17,12 +17,12 @@
 # source env_lcg.sh (if `make LCG=1` is used to build)
 #######################################################################
 
-# Hardcoded paths for standalone version identical to CMSSW 11_3_X
+# Hardcoded paths for standalone version identical to CMSSW 14_1_X
 # These are ignored if either CONDA=1 or LCG=1 is set
-BOOST = /cvmfs/cms.cern.ch/slc7_amd64_gcc900/external/boost/1.75.0-ljfedo
-VDT   = /cvmfs/cms.cern.ch/slc7_amd64_gcc900/cms/vdt/0.4.0-ghbfee
-GSL = /cvmfs/cms.cern.ch/slc7_amd64_gcc900/external/gsl/2.6-ljfedo
-EIGEN = /cvmfs/cms.cern.ch/slc7_amd64_gcc900/external/eigen/011e0db31d1bed8b7f73662be6d57d9f30fa457a
+BOOST = /cvmfs/cms.cern.ch/el9_amd64_gcc12/external/boost/1.80.0-87b5de10acd2f2c8a325345ad058b814
+VDT   = /cvmfs/cms.cern.ch/el9_amd64_gcc12/cms/vdt/0.4.3-793cee1e1edef0e54b2bd5cb1f69aec9
+GSL = /cvmfs/cms.cern.ch/el9_amd64_gcc12/external/gsl/2.6-5e2ce72ea2977ff21a2344bbb52daf5c
+EIGEN = /cvmfs/cms.cern.ch/el9_amd64_gcc12/external/eigen/3bb6a48d8c171cf20b5f8e48bfb4e424fbd4f79e-3ca740c03e68b1a067f3ed0679234a78
 # Compiler and flags -----------------------------------------------------------
 CXX = $(shell root-config --cxx)
 ROOTCFLAGS = $(shell root-config --cflags)

README.md

@@ -7,3 +7,7 @@ All documentation, including installation instructions, is hosted at
 http://cms-analysis.github.io/HiggsAnalysis-CombinedLimit/latest
 
 The source code of this documentation can be found in the `docs/` folder in this repository.
+
+### Publication 
+
+The `Combine` tool publication can be found [here](https://arxiv.org/abs/2404.06614). Please consider citing this reference if you use the `Combine` tool. 

bin/combine.cpp

@@ -32,7 +32,7 @@
 using namespace std;
 
 // Update whenever we have a new Tag
-std::string combineTagString = "v9.2.1";
+std::string combineTagString = "v10.0.0";
 // 
 
 int main(int argc, char **argv) {

contributing.md

@@ -109,6 +109,25 @@ Note that this will only affect your *local* copy of the gh-pages documentation.
 Please ensure you use relative paths. Currently, this is the only known feature where the behvaiour differs between local mkdocs and public page deployment. 
 If you'd like to test the deployment directly, the suggested method is to set up a docs page using your personal github account; this should mimic the exact settings of the official page.
 
+## Github Actions 
+
+There are several automated processes defined in the [`.github/workflows`](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/tree/main/.github/workflows) folder which are triggered for every pull request or when a new commit is pushed into the `main` branch. 
+
+ - `CI with CVMFS` workflow defined in [.github/workflows/cvmfs-ci.yml](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/cvmfs-ci.yml) compiles <span style="font-variant:small-caps;">Combine</span> with the CMSSW which is setup from `cvmfs`. This will also run several test <span style="font-variant:small-caps;">Combine</span> commands using tutorial datacards contained in the repository. 
+ - `CI/CD` workflow defined in [.github/workflows/ci.yml](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/ci.yml) runs:
+
+    1. [Linting checks](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/ci.yml#L11) with`flake8` and `black`.
+    2. <span style="font-variant:small-caps;">Combine</span> compilation using conda environment with several combinations of (ROOT, python) versions:  (6.26.4, 3.10), (6.24,3.9), (6.22, 3.9) and (6.22, 2.7.18) 
+
+ - `Docs` workflow defined in [.github/workflows/docs.yml](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/docs.yml) manages the documentation deployment with `mike` as described above.
+
+In addition there are two conditional workflows that can be triggered with [github labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels): 
+
+- `trigger gitlab job` workflow defined in [.github/workflows/gitlabci.yml](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/gitlabci.yml) can be triggered with the "safe to test" label. Please note that this gitlab workflow uses `CMSSW_10_2_13`, therefore it might fail with later versions of <span style="font-variant:small-caps;">Combine</span> and it is likely to be deprecated soon. 
+
+- `Port to <branch>` workflows defined in [.github/workflows/port_to_branch.yml](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/.github/workflows/port_to_branch.yml), e.g. the `Port to 112x-comb2022` can be triggered with the "port to 112x-comb2022" label to port the changes from a pull request to the `112x-comb2022` branch and create a new pull request. 
+
+
 ## Big Contributions
 
 We welcome large contributions to <span style="font-variant:small-caps;">Combine</span>. 

data/tutorials/groups/README.md

@@ -12,17 +12,17 @@ The files in this directory are:
 
 For simplicity, this tutorial does not discuss scans using `-M MultiDimFit --algo=grid`,
 but rather uses `-M MaxLikelihoodFit --robustFit=1`
-to determine the crossings of the likelihood with the 1 sigma levels.
+to determine the crossings of the likelihood with the 1σ levels.
 
 ## Groups of nuisances
 
 Groups of nuisances are defined in the datacard, e.g. [here](./myanalysis.dc.txt#L30), [here](./myanalysis.dc.txt#L38-L40), [here](./myanalysis.dc.txt#L46-L47), and [here](./myanalysis.dc.txt#L56-L58).
 They are parsed when building the binary datacard and result in two actions:
-- creation in the workspace of a `RooArgSet` for each group, containing the concerned nuisance parameters.
+- creation in the workspace of a `RooArgSet` for each group, containing the concerned nuisance parameters, and
 - setting of a `group_%s` attribute in each nuisance parameter.
 
 A nuisance parameter can belong to multiple groups of nuisances.
-It is up to you to list or not list nuisances as part of groups in an exclusive, or overlapping way.
+It is up to you to list or not list nuisances as part of groups in an exclusive or overlapping way.
 In particular, there is no check that every nuisance is in at least one group.
 
 At present, the syntax does not allow to declare groups as members of other groups;
@@ -44,12 +44,12 @@ by fitting the data would not be taken into account and even the central value w
 
 One way to deconstruct the total uncertainty into different components is by freezing nuisances.
 For instance, freezing all nuisances directly gives the statistical component as mentioned above.
-By subtracting in quadrature the statistical uncertainty from the total uncertainty, one can derive the
-systematic uncertainty.
+By subtracting in quadrature the statistical uncertainty from the total uncertainty, one can estimate the
+total systematic uncertainty.
 
 When there are multiple components being disentangled,
 the decomposition can proceed in many ways,
-and an example of extracting the exp. syst. and theo. syst. is given in this tutorial, [here](./Makefile#L42-L70)
+and an example of extracting the `exp. syst.` and `theo. syst.` is given in this tutorial, [here](./Makefile#L42-L70).
 
 ## Show me the money
 

data/tutorials/longexercise/plot1DScan.py

@@ -9,7 +9,7 @@
 
 from six.moves import range
 
-import CombineHarvester.CombineTools.plotting as plot
+import HiggsAnalysis.CombinedLimit.util.plotting as plot
 import ROOT
 
 ROOT.PyConfig.IgnoreCommandLineOptions = True

data/tutorials/longexercise/postFitPlot.py

@@ -1,6 +1,6 @@
 from __future__ import absolute_import
 
-import CombineHarvester.CombineTools.plotting as plot
+import HiggsAnalysis.CombinedLimit.util.plotting as plot
 import ROOT
 
 ROOT.PyConfig.IgnoreCommandLineOptions = True

data/tutorials/parametric_exercise/construct_models_bias_study_part4.py

@@ -15,7 +15,7 @@
 #
 # # Convert to RooDataSet
 # data = ROOT.RooDataSet("data_Tag0", "data_Tag0",
-#     t, ROOT.RooArgSet(mass), "", "weight"
+#     t, ROOT.RooArgSet(mass, weight), "", "weight"
 #     )
 #
 # # Define ranges to fit

data/tutorials/parametric_exercise/construct_models_multipdf_part5.py

@@ -12,7 +12,7 @@
 # t = f.Get("data_Tag0")
 #
 # data = ROOT.RooDataSet("data_Tag0", "data_Tag0",
-#     t, ROOT.RooArgSet(mass), "", "weight"
+#     t, ROOT.RooArgSet(mass,weight), "", "weight"
 #     )
 #
 # # Define ranges to fit for initial parameter values

data/tutorials/parametric_exercise/construct_models_part1.py

@@ -104,7 +104,7 @@
 # # Calculate the total yield and print output
 # lumi = 138000
 # N = xs_ggH*br_gamgam*eff*lumi
-# print("For 138fb^-1, total normalisation of signal is:
+# print("For 138fb^-1, total normalisation of signal is: \
 #     N = xs * br * eff * lumi = %.2f events"%N
 #     )
 
@@ -115,7 +115,7 @@
 #
 # # Convert TTree to a RooDataSet
 # data = ROOT.RooDataSet("data_Tag0", "data_Tag0",
-#     t, ROOT.RooArgSet(mass), "", "weight"
+#     t, ROOT.RooArgSet(mass, weight), "", "weight"
 #     )
 #
 # # Define mass sideband ranges on the mass variable