RAD: Reaction Aware Dataframes

Modern Particle & Nuclear Physics Data Analysis with ROOT RDataFrame

Read User Guide Developer Guide Doxygen Reference

Core Concepts

Analysis Manager & Recipes

RAD completely overhauls the traditional ROOT event loop using an AnalysisManager orchestrator.

  • Recipe-Based Architecture: Analysis logic is safely sandboxed inside C++ Lambdas (Recipes).
  • Parallel Safety: Thread management and concurrent I/O (TTree writing) are handled automatically under the hood.
  • Zero-Copy Combinatorics: Instantly evaluates all multiparticle topologies via efficient integer lookup arrays.

Modular Streams

The framework easily adapts to any data source using specialized data streams:

  • Reactions: Define the IO backend (e.g., ePICReaction for Podio/EDM4hep, HepMCElectro for HepMC3).
  • KinematicsProcessor: The vectorized physics engine that executes your topology recipes.
  • Multi-Hypothesis: Process Reconstructed (Rec) and Monte Carlo (Truth) streams simultaneously in a single pass.

Example Usage


#include "AnalysisManager.h" 
#include "HepMCElectro.h"        
#include "KinematicsProcElectro.h"        

void CombiJpsi() {
  using namespace rad;
  ROOT::EnableImplicitMT(8);
 
  // 1. Initialize the Orchestrator
  AnalysisManager<HepMCElectro, KinematicsProcElectro> mgr{
    "Jpsi_Analysis", "hepmc3_tree", "data.root"
  };
  mgr.SetOutputDir("output");
  
  auto& reaction = mgr.Reaction();
  reaction.SetupMC();
 
  // 2. Define Particles & Combinatorics
  reaction.SetBeamElectronIndex(0);
  reaction.SetParticleIndex("ele", 4); 
  reaction.SetParticleIndex("pos", 5); 
  reaction.MakeCombinations();
  mgr.AddStream(MC());

  // 3. The Topology Recipe (Injected to all CPU threads)
  auto topology_recipe = [](KinematicsProcElectro& p) {
    p.Creator().Sum("Jpsi", {{"ele", "pos"}});         
    p.Mass("MassJ", {"Jpsi"});             
  };
  
  // 4. The Histogram Recipe
  auto histogram_recipe = [](histo::Histogrammer& h) {
    h.Create("MassJ", "Invariant Mass; Mass [GeV]", 100, 2.0, 4.0, "MassJ");
  };
  
  // 5. Configure & Execute Lazy Event Loop
  mgr.ConfigureKinematics(topology_recipe);
  mgr.ConfigureHistograms(histogram_recipe);
  mgr.Snapshot();
  mgr.Run();
}

Standard workflow for combinatorial analysis using the Recipe pattern.