Metadata-Version: 2.4
Name: btvit-cli
Version: 0.2.2
Summary: Typer CLI package for the Vit medical multi-axis Vision Transformer project.
Author: SuShuHeng
License: Apache-2.0
Project-URL: Repository, https://github.com/SuShuHeng/Vit-cli
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1,>=0.12
Requires-Dist: PyYAML>=6
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: torch
Requires-Dist: torchvision
Requires-Dist: einops
Requires-Dist: opencv-python
Requires-Dist: tqdm
Requires-Dist: rich>=13.0
Dynamic: license-file

# btvit-cli

基于 PyTorch 的三轴 ViT 医学影像二分类 CLI。

## 安装

```bash
pip install btvit-cli
vit --version
```

## 当前主线

项目现在只保留一条流程：

1. `axis` 阶段分别训练 `x / y / z` 三个轴的单轴 ViT
2. `fusion` 阶段复用三轴 encoder，训练患者级 `fusion_nn` 头
3. `pred` 阶段支持两种患者级输出：
   - `weighted_vote`
   - `fusion_nn`
   - `both`

每个患者的每张 `(16, 368)` 灰度图都作为独立样本共享患者标签，不再使用旧的中间特征缓存或跨轴组合穷举训练流程。

## 快速开始

### 1. 导出模板

```bash
vit get --path ./configs
```

导出内容：

- `model_config.yaml`
- `data_config.yaml`
- `training_config.yaml`
- `experiment_config.yaml`
- `multi_axis_config.yaml`
- `monitoring_config.yaml`
- `USAGE.md`

### 2. 训练三轴 ViT

```bash
vit train --config configs/base --stage axis --axis x --verbose
vit train --config configs/base --stage axis --axis y --verbose
vit train --config configs/base --stage axis --axis z --verbose
```

关键参数：

- `--stage axis`
- `--axis x|y|z`
- `--config <yaml_dir>`
- `--data` 可选。未提供时使用 `multi_axis.axis_data_paths.<axis>`
- `--label` 可选。未提供时使用配置文件中的标签路径

### 3. 训练 fusion 头

```bash
vit train --config configs/base --stage fusion --verbose
```

fusion 阶段会默认解析：

- `experiments/<name>/axis-x/checkpoints/best_model.pth`
- `experiments/<name>/axis-y/checkpoints/best_model.pth`
- `experiments/<name>/axis-z/checkpoints/best_model.pth`

也可以显式覆盖：

- `--axis-checkpoint-x`
- `--axis-checkpoint-y`
- `--axis-checkpoint-z`

### 4. 患者级预测

```bash
vit pred --mode weighted_vote --config configs/base --data dataset/predict_root
vit pred --mode fusion_nn --config configs/base --data dataset/predict_root
vit pred --mode both --config configs/base --data dataset/predict_root --label dataset/label.csv
```

预测模式：

- `weighted_vote`：单图概率 -> 轴内患者均值 -> 跨轴加权投票
- `fusion_nn`：单图特征 -> 轴内患者均值 -> fusion head
- `both`：同时输出两条分支

预测数据支持：

1. 根目录包含 `data-x/`、`data-y/`、`data-z/`
2. 平铺 PNG 目录，文件名为 `{patient_id}_{Z}_{Y}_{X}.png`

## 输出结构

训练输出：

```text
experiments/<experiment_name>/
  axis-x/
    checkpoints/
    results/
    logs/
  axis-y/
    checkpoints/
    results/
    logs/
  axis-z/
    checkpoints/
    results/
    logs/
  fusion/
    checkpoints/
    results/
    logs/
  testset/
    data-x/
    data-y/
    data-z/
    label.csv
```

预测输出：

- `predictions.csv`
- `prediction_summary.json`
- `confusion_matrix_weighted_vote.png`，当有标签且启用 `weighted_vote`
- `confusion_matrix_fusion_nn.png`，当有标签且启用 `fusion_nn`

## 配置要点

- `training.common`：设备、worker、混合精度等公共训练参数
- `training.axis`：单轴 ViT 训练参数
- `training.fusion`：fusion 头训练参数
- `multi_axis.patient_pooling`：患者内均值聚合规则
- `multi_axis.weighted_vote`：加权投票配置
- `multi_axis.fusion_head`：患者级 fusion 头配置
- `monitoring.axis / monitoring.fusion / monitoring.prediction`：分阶段监控与预测阈值

## 开发

```bash
conda activate Vit
pip install -e .
vit --help
```

构建：

```bash
conda run -n Vit python -m build
```

## 许可证

Apache-2.0
