FUCKROOT 0.0.3

FUCKROOT toolkit for ROOT I/O and HEP-style plotting

FUCKROOT

FUCKROOT 是一个面向高能物理（HEP）分析场景的小工具包，提供两类核心能力：

• ROOT 文件读取与树结构访问（基于 uproot）
• Matplotlib 的 HEP 风格绘图投影（projection="hep"）

当前版本：0.1.1

Features

• ROOT 类：打开 ROOT 文件并打印目录树结构
• Tree 类：
  • 缓存分支数据，支持 tree["branch"] 直接取 NumPy 数组
  • 快速查看分支名 tree.keys()
  • hist1d(...) 一键绘制 1D 直方图
• HepAxes 自定义投影：
  • LHCb 风格默认样式（刻度、线宽、配色、字体）
  • ax.hist(..., stat=True, errors=True) 自动统计文本与误差棒
  • 多次 hist 自动使用统一 bin/range，便于叠图比较
  • 支持 twinx()（当前版本有已知对齐限制，见下方注意事项）

Installation

要求：Python >= 3.10

推荐在虚拟环境中安装：

python -m venv .venv
source .venv/bin/activate
pip install -e .

项目依赖（由 pyproject.toml 管理）：

• matplotlib>=3.8
• numpy>=1.24
• pandas>=2.0
• uproot>=5.0
• tqdm>=4.65

Quick Start

1) 打开 ROOT 文件并查看目录

from FUCKROOT import ROOT

rt = ROOT("your_file.root")
print(rt)  # 打印 ROOT 目录树

2) 访问树并读取分支

tree = rt["tree"]
print(tree.keys())

x = tree["var_0"]  # 返回 numpy.ndarray
print(x.shape)

3) 画 HEP 风格直方图

import matplotlib.pyplot as plt

fig, ax = plt.subplots(subplot_kw={"projection": "hep"})
ax.hist(x, bins=60, label="var_0", stat=True, errors=True)
ax.set_xlabel("var_0")
ax.set_ylabel("Entries")
ax.legend()
plt.show()

说明：导入 FUCKROOT.HEP_PLOT 后，plt.subplots() 默认会启用 projection="hep"。

Public API

FUCKROOT/__init__.py 暴露以下对象：

• ROOT
• Tree
• HepAxes

你可以直接：

from FUCKROOT import ROOT, Tree, HepAxes

Notes And Caveats

• Tree.__init__ 在数据量较大时只预取前 500 和后 500 条用于快速预览；实际分支数据在 tree["branch"] 时按需读取并缓存。
• Tree.hist1d(...) 当前实现会内部创建新的 figure/axes 并直接显示（plt.show(block=False)）。
• HepAxes.twinx() 会给出 warning：双轴直方图在当前版本下可能存在 bin 对齐问题，不建议用于严格对齐比较。

Package Layout

FUCKROOT/
	HEP_PLOT/
		HepFigure.py   # HepAxes 实现与投影注册
		lhcbStyle.C    # ROOT 风格参考文件
	ROOT_BASE/
		ROOT.py        # ROOT 文件包装
		Tree.py        # 树数据与绘图辅助

Development

本地开发安装：

pip install -e .

构建分发包：

python -m build