Metadata-Version: 2.4
Name: FUCKROOT
Version: 0.0.3
Summary: FUCKROOT toolkit for ROOT I/O and HEP-style plotting
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: uproot>=5.0
Requires-Dist: tqdm>=4.65

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

推荐在虚拟环境中安装：

```bash
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 文件并查看目录

```python
from FUCKROOT import ROOT

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

### 2) 访问树并读取分支

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

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

### 3) 画 HEP 风格直方图

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

你可以直接：

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

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

## Development

本地开发安装：

```bash
pip install -e .
```

构建分发包：

```bash
python -m build
```
