RDFAnalyzerCore Documentation

Welcome to the RDFAnalyzerCore documentation! This framework provides a powerful, config-driven system for building physics analyses with ROOT RDataFrame.

Getting Started

New to RDFAnalyzerCore? Start here:

• Getting Started Guide - Installation, setup, and your first analysis
• Quick Start - Get running in 5 minutes

User Documentation

Building Analyses

• Analysis Guide - Comprehensive guide to building analyses
  • Step-by-step tutorial
  • Working with data
  • Event selection
  • Machine learning integration
  • Histogramming
  • Complete examples
• Configuration Reference - Complete configuration documentation
  • Main configuration options
  • Plugin configurations (BDT, ONNX, corrections, triggers, WeightManager, RegionManager, GoldenJsonManager, CutflowManager)
  • Configuration file format and YAML config overview
  • Example configurations
• Configuration Validation - YAML analysis config schema and validation
  • Full JSON Schema reference for the analysis YAML config
  • Validation error messages and troubleshooting
  • Nuisance group, region, and histogram config schema

Python Analysis

• Python Bindings - Full Python API and usage patterns
• Python Bindings Testing - Validation and troubleshooting guide

Framework Features

• Machine Learning
  • ONNX Models - Runtime ML from any framework (PyTorch, TensorFlow, scikit-learn)
  • SOFIE Models - Build-time compiled models for maximum performance
  • BDT Models - FastForest boosted decision trees
  • ONNX Multi-Output - Models with multiple outputs
• Batch Submission - HTCondor job submission guide
• Production Manager - Production-scale job management and monitoring

Data Management & Outputs

• Dataset Manifest - Describing and managing input datasets
  • Dataset manifest file format and schema
  • Sample metadata, cross-sections, and grouping
• Output Schema - Structure of framework output files
  • ROOT output file layout (event tree, histograms, metadata)
  • Histogram naming conventions and cutflow outputs
• Validation Reports - Automated output validation
  • Interpreting validation report contents
  • Checking histogram integrity and cutflow consistency

Systematics & Physics Objects

• Nuisance Groups - Configuring systematic nuisance groups
  • Weight and shape systematic definitions
  • Nuisance group YAML schema and examples
• Region Binding - Region-aware histogram and cutflow auto-binding
  • Defining analysis regions and hierarchies
  • Automatic per-region histogram booking
• Physics Objects - Physics object collection reference
  • Standard column names for leptons, jets, MET, and other objects
  • Collection conventions and branch naming
• Jet Energy Corrections - JES/JER correction plugin reference
  • CMS NanoAOD JEC workflow (strip, apply, systematic sets)
  • Type-1 MET propagation
  • PhysicsObjectCollection integration and variation maps

Batch Processing & Performance

• LAW Tasks - Luigi/LAW workflow task reference
  • Available LAW tasks and their parameters
  • Running and monitoring large-scale batch workflows
• Performance Monitoring - Profiling and tuning analysis jobs
  • Identifying bottlenecks in RDataFrame processing
  • Memory and CPU usage guidelines

API Reference

• API Reference - Complete API documentation
  • Analyzer class
  • Configuration interfaces
  • Data management
  • Plugin interfaces
  • Manager implementations

Developer Documentation

Extending the Framework

• Architecture - Internal design and structure
  • Design philosophy
  • Core components
  • Plugin system
  • Data flow
  • Build system
• Plugin Development - Creating custom plugins
  • When to create a plugin
  • Plugin types
  • Step-by-step guide
  • Advanced patterns
  • Testing

Key Concepts

Config-Driven Design

RDFAnalyzerCore separates configuration from code:

# config.txt
fileList=data.root
saveFile=output.root
threads=-1
onnxConfig=cfg/onnx_models.txt

Same binary, different configs = different analyses. Version control your configs with Git for reproducibility.

Plugin Architecture

Framework is extensible via plugins:

• BDTManager: Boosted decision trees
• OnnxManager: Neural networks and ML models
• SofieManager: Build-time compiled models
• CorrectionManager: Scale factors and corrections
• JetEnergyScaleManager: JES/JER corrections, CMS systematic sets, MET propagation, and PhysicsObjectCollection integration
• TriggerManager: Trigger logic
• NDHistogramManager: N-dimensional histograms
• WeightManager: Nominal and varied event weights
• RegionManager: Named analysis regions with hierarchy
• CutflowManager: Sequential cutflow and N-1 tables
• GoldenJsonManager: Data certification via golden JSON

Add custom plugins without modifying core code.

Lazy Evaluation

Built on ROOT RDataFrame’s lazy evaluation:

analyzer.Define("var", ...);    // Queued
analyzer.Filter("cut", ...);    // Queued
analyzer.save();                // Executes all at once

Efficient processing with automatic optimization.

Quick Links

For New Users

1. Installation
2. First Analysis
3. Configuration Basics
4. Analysis Tutorial

For Advanced Users

1. Architecture Overview
2. Creating Plugins
3. Systematic Uncertainties
4. HTCondor Submission

Common Tasks

• Add ML model: ONNX Configuration
• Apply corrections: CorrectionManager
• Apply JES/JER corrections: Jet Energy Corrections
• Book histograms: Histogramming Guide
• Handle systematics: Systematics Guide
• Submit to batch: HTCondor Scripts
• Validate my config: Configuration Validation
• Understanding outputs: Output Schema
• Physics object collections: Physics Objects
• LAW task reference: LAW Tasks

Examples

Minimal Analysis

#include <analyzer.h>

int main(int argc, char **argv) {
    Analyzer analyzer(argv[1]);
    
    // Define variable
    analyzer.Define("pt_gev",
        [](float pt) { return pt / 1000.0; },
        {"jet_pt"}
    );
    
    // Apply selection
    analyzer.Filter("pt_cut",
        [](float pt) { return pt > 25.0; },
        {"pt_gev"}
    );
    
    // Apply ML model
    auto* onnx = analyzer.getPlugin<IOnnxManager>("onnx");
    onnx->applyAllModels();
    
    // Save
    analyzer.save();
    return 0;
}

Full Analysis Example

See Complete Example in the Analysis Guide for a production-ready analysis with:

• Event selection
• Machine learning
• Corrections
• Histograms
• Systematics

Requirements

• ROOT: 6.30/02 or later
• CMake: 3.19.0 or later
• Compiler: C++17 compatible
• OS: Linux, macOS

ONNX Runtime is downloaded automatically during build.

Support

• Documentation: Browse this site
• GitHub: RDFAnalyzerCore Repository
• Issues: Report a bug
• Examples: Check analyses/ExampleAnalysis/ in the repository

Contributing

Contributions welcome! See Plugin Development Guide to get started.

For implementation details and design notes for major features, see the DEVELOPMENT directory.

License

See repository for license information.

---

Repository: https://github.com/brkronheim/RDFAnalyzerCore

Last Updated: March 2026