analysis-tool 1.0.0
A generic analysis tool for various data analyses. Mainly for the analysis of the LHCb experiment.
License: MIT
Requires Python: >=3.10
Keywords: HEP, physics, lhcb, data-analysis, root, tmva, xgboost

<!--
 * @Author       : Jie Wu j.wu@cern.ch
 * @Date         : 2025-10-17 05:27:15 +0200
 * @LastEditors  : Jie Wu j.wu@cern.ch
 * @LastEditTime : 2025-10-17 05:30:20 +0200
 * @FilePath     : README.md
 * @Description  : 
 * 
 * Copyright (c) 2025 by everyone, All Rights Reserved. 
-->
# Analysis Tool

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Development Status](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/JieWu-GitHub/Analysis_tools)

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

```bash
# 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

```bash
python -m pip install ".[dev]"
```

## Quick Start

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

```bash
# View all available commands
analysis_tool --help

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

### Example: Apply Selection Cuts

```bash
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

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

### Example: Create Distribution Plots

```bash
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.