analysis-tool 1.0.0

A generic analysis tool for various data analyses. Mainly for the analysis of the LHCb experiment.

Analysis Tool

A comprehensive Python toolkit for High Energy Physics (HEP) data analysis, primarily designed for LHCb experiment analyses. This tool provides a unified interface for common analysis tasks including data selection, multivariate analysis, reweighting, uncertainty estimation, and visualization.

Overview

analysis-tool streamlines the workflow for particle physics data analysis by providing:

• Command-line interface for reproducible analyses
• Integration with ROOT/RooFit for HEP-specific data formats
• Machine learning support via TMVA and XGBoost
• Statistical tools for reweighting and uncertainty quantification
• Flexible plotting utilities with matplotlib and plotly backends

Key Features

Data Processing

• Selection criteria application: Filter data with configurable cuts
• File merging: Combine multiple ROOT files efficiently
• Candidate labeling: Add and manage multiple candidate labels
• Track combinations: Calculate invariant masses for particle combinations
• Bootstrap sampling: Generate bootstrap samples for uncertainty estimation

Multivariate Analysis (MVA)

• TMVA integration: Train and apply ROOT TMVA BDT classifiers
• XGBoost models: Advanced gradient boosting with cross-validation support
• Model persistence: Save and load trained models
• Feature importance: Analyze discriminating variables

Statistical Analysis

• Data reweighting: Multi-dimensional reweighting using BDT or histogram methods
• Weight application: Apply systematic weights to datasets
• Correlation analysis: Study variable correlations with visualization
• Uncertainty propagation: Bootstrap and systematic uncertainty tools

Visualization

• Distribution comparison: Compare multiple samples with error bars
• Before/after plots: Visualize reweighting effects
• Cutflow plots: Display selection efficiency
• Correlation matrices: Clustered and standard heatmaps
• Customizable styling: Support for publication-quality plots

Installation

Requirements

• Python ≥ 3.10
• ROOT (with PyROOT)
• Common scientific Python packages (numpy, pandas, matplotlib, etc.)

Install from Source

# Clone the repository
git clone https://github.com/JieWu-GitHub/Analysis_tools.git
cd Analysis_tools

# Full installation
python -m pip install .

# Editable/development mode
python -m pip install -e .

# Force reinstall (overwrite existing)
python -m pip install --force-reinstall .

# Upgrade after modifications
python -m pip install --upgrade .

Install Development Dependencies

python -m pip install ".[dev]"

Quick Start

After installation, the analysis_tool command provides access to all functionality:

# View all available commands
analysis_tool --help

# Get help for a specific command
analysis_tool apply_selection --help

Example: Apply Selection Cuts

analysis_tool apply_selection \
    --input-files data/*.root \
    --input-tree-name DecayTree \
    --output-file selected_data.root \
    --output-tree-name DecayTree \
    --cut-string "B_PT > 5000 && B_IPCHI2_OWNPV > 9"

Example: Train XGBoost Model

analysis_tool train_xgboost_model \
    --signal-file signal.root \
    --background-file background.root \
    --config-file variables.yaml \
    --output-dir models/

Example: Create Distribution Plots

analysis_tool compare_distributions \
    --input-files sample1.root sample2.root \
    --labels "Sample 1" "Sample 2" \
    --variables B_PT B_IPCHI2_OWNPV \
    --output-dir plots/

Command Reference

Data Processing Commands

• apply_selection - Apply selection criteria to data
• file_merger - Merge multiple ROOT files
• add_candidate_label - Add multiple candidate labels
• track_combination_mass_calculator - Calculate invariant masses
• bootstrap_sample - Generate bootstrap samples

Reweighting Commands

• reweighting - Compute reweighting factors
• apply_weights - Apply weights to datasets

MVA Commands

• train_tmva - Train TMVA BDT models
• apply_bdt_selection - Apply BDT selection
• train_xgboost_model - Train XGBoost models
• add_xgboost_info - Add BDT predictions to data

Plotting Commands

• compare_distributions - Compare sample distributions
• compare_distributions_classicalWay - Classical plotting style
• Plot_BeforeAfter_Weights_comparison - Before/after reweighting
• Plotter - General-purpose plotting tool

Documentation

For detailed documentation on each module and function, please refer to the docstrings in the source code. Additional documentation and examples will be added to the repository wiki.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Note: This tool is in active development (beta status). APIs may change between versions. Please report any issues or suggestions via the GitHub issue tracker.