CMS Combine tutorial

The CMS Combine tool is a software package based on RooStats and RooFit, utilized extensively for statistical analysis. Originally developed within the Higgs Physics Analysis Group (PAG), its usage has since become widespread across the CMS collaboration. Typically, Combine is executed within the CMSSW framework.

This repository provides a workflow to build and run Combine locally. All dependencies in this guide are compiled using cmake/make and installed directly into your home directory ($HOME). This avoids the need for sudo access, making the setup fully compatible with high-performance clusters where you may lack root or administrator privileges.

🔗 Official Documentation: HiggsAnalysis-CombinedLimit

📚 Tutorial structure

This repository is structured into progressively complex levels, mimicking the actual workflow of developing a CMS analysis. The tutorials progress from basic counting experiments to multi-region shape-based analyses with nuisance parameters. Each level is contained within its own directory. Each directory contains a dedicated README file detailing the concepts, along with the necessary datacards, ROOT files, and executable run scripts.

• level1_GettingStarted: Introduces the basic structure of a CMS Combine datacard. Starting from a simple counting experiment, it gradually adds multiple backgrounds, multiple signal regions, and automatic MC statistical uncertainties, while demonstrating the most commonly used Combine commands.

• level2_ShapeAnalysis: Introduces shape-based analyses by mapping kinematic distributions into ROOT histograms. It demonstrates how outsourcing binning details to ROOT files keeps text datacards clean and scale-invariant, explores the distinction between signal regions and individual bins.

To get the most out of these tutorials, I recommend progressing through the directories in numerical order.

1. 📂 Navigate to the specific directory.
2. 📖 Read the local README.md file for the step-by-step instructions and theoretical context for that level.
3. 🔍 Inspect the provided datacard.txt and any associated .root files to understand their structure.
4. ⚙️ Execute the provided scripts to run the Combine commands locally and analyze the output limits and significance.

🛠️Setting up Combine locally

If you have access to lxplus, you can install and use Combine there rather than on your local machine. Follow the installation instructions in the official documentation.

Get the dependencies first!

Before building Combine itself, you need to install its dependencies. We will install everything into a local directory (e.g., $HOME/local) to maintain an isolated, user-level environment.

• ROOT
  I highly recommend staying in the exact same environment where ROOT is built to avoid system path and Python-related conflicts. Pick a Conda environment and install ROOT using the following guides:

  • Installing Miniconda [this ensures Python path compatibility]
  • Building ROOT [Can be installed in the base environment]

  ⚠️ Important: Installing Combine requires ROOT's MathMore library. For this, ROOT needs to be built using the -Dmathmore=ON option. If you alredy have ROOT, you can check whether this library by doing the following.

   root-config --features
   ls $HOME/root_install/lib/libMathMore*

  If you can't find the MathMore library, rebuild ROOT like this.

   cd $HOME/root_build
   cmake $HOME/root_src -DCMAKE_INSTALL_PREFIX=$HOME/root_install -Dmathmore=ON
   make -j8 ## Use all available CPUs for speed
   make install

• Boost
  Combine uses the Boost library for parsing command-line options. Download the latest .tar.gz source from the Boost release page (https://www.boost.org/releases/latest/). Move it to your home area, extract it, and build using the following commands. It takes a couple of minutes.

   tar -xzvf boost_1_91_0.tar.gz
   cd boost_1_91_0/
   bash bootstrap.sh                 # creates a binary named b2
   ./b2 install --prefix=$HOME/local # installs in home area

• Eigen
  Used for linear algebra operations within CMSInterferenceFunc and RooSplineND. Download and install from GitLab.

   git clone https://gitlab.com/libeigen/eigen.git
   cd eigen/
   mkdir build && cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/local
   make -j8     # Use all available CPUs for speed
   make install # Might take 15-20 minutes

  This is a slow build step (~15-20 minutes). The compiler verbosity is minimal, so it may appear stuck at 0% for a long time before suddenly jumping to 33%. Be patient.

• VDT [optional]
  VDT provides fast, vectorized math functions. Download and install from GitHub.

   git clone https://github.com/dpiparo/vdt.git
   cd vdt/
   mkdir build && cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/local -DCMAKE_POLICY_VERSION_MINIMUM=3.5
   # hack: VDT requires older cmake version
   make -j8 # Use all available CPUs for speed
   make install

Install CMS Combine

⚠️Make sure that ROOT's MathMore library is available [read the ROOT section carefully].
✅Once all dependencies are ready, you can clone Combine directly from GitHub and compile as follows.

git clone https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit.git
cd HiggsAnalysis-CombinedLimit/
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/local -DCMAKE_PREFIX_PATH="$HOME/local;$HOME/root_install"
# In case you did not install VDT, use the -DUSE_VDT=FALSE option here
# It may also complain about missing GTest library.
# It's not necessary; we are not uging the google test library.
cmake --build . -j8  # Use all available CPUs for speed

Once the build is complete, the binary is created in the build/bin directory. Update the system path variables in the .bashrc by including the following lines.

export PATH=$HOME/HiggsAnalysis-CombinedLimit/build/bin:$PATH
export LD_LIBRARY_PATH=$HOME/HiggsAnalysis-CombinedLimit/build/lib:$LD_LIBRARY_PATH
export PYTHONPATH=$HOME/HiggsAnalysis-CombinedLimit/build/python:$PYTHONPATH

Done!
Verify the installation by running the following.

combine --help

---

I hope this guide makes navigating Combine outside of CMSSW a bit easier. If you encounter any issues, have suggestions for improvements, or just want to discuss CMS data analysis, feel free to reach out!

Prachurjya Hazarika