# 优化一键实验脚本使用说明

## 1. 脚本位置

```text
tools/run_optimized_supervised.sh
```

该脚本服务当前 `XNet2d` 全监督超声分割主线。

## 2. 脚本做什么

脚本会自动完成：

1. 根据 `DATASET` 解析数据集根目录
2. 对需要项目级划分的数据集调用 `scripts/generate_project_split.py`
3. 调用 `tools/train.py`
4. 使用 `configs/segmentation/optimized/*.yaml`
5. 训练前打印实际生效的 `dataset`、`image_size`、`batch_size`、`amp`、`lr` 和 SwanLab 配置

## 3. 可改环境变量

```bash
DATASET="${DATASET:-BUSI}"
SEED="${SEED:-42}"
RUN_ALL="${RUN_ALL:-0}"
EXTRA_SET_ARGS="${EXTRA_SET_ARGS:-}"
```

含义：

1. `DATASET`：选择数据集
2. `SEED`：项目级 split 随机种子
3. `RUN_ALL`：设为 `1` 时依次跑内置全部监督数据集
4. `EXTRA_SET_ARGS`：追加给 `tools/train.py --set` 的覆盖参数

脚本固定使用：

```text
/opt/miniforge3/envs/xnet_mamba/bin/python
```

## 4. 支持的数据集名称

1. `BUS-UCLM`
2. `BUSI`
3. `BUS-BRA`
4. `BUS_UC`
5. `CCAUI`
6. `DDTI`
7. `OTU_2d`
8. `TN3K`
9. `TG3K`

## 5. 常用跑法

跑单个数据集：

```bash
DATASET=BUSI bash tools/run_optimized_supervised.sh
```

短跑调试：

```bash
DATASET=BUSI \
EXTRA_SET_ARGS="train.epochs=2 train.batch_size=2 train.val_batch_size=2 logging.use_swanlab=false" \
bash tools/run_optimized_supervised.sh
```

一次跑全部监督数据集：

```bash
RUN_ALL=1 bash tools/run_optimized_supervised.sh
```

## 6. 当前配置文件

当前正式优化训练配置在：

```text
configs/segmentation/optimized/
```

所有优化配置统一使用 `384x384`、`amp=true`，并默认打开 SwanLab cloud，同时将本地日志保存在 `swanlog/`。

## 7. XNet 消融示例

关闭 wavelet branch：

```bash
DATASET=BUSI \
EXTRA_SET_ARGS="model.use_wavelet_branch=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_wavelet logging.experiment_name=xnet_busi_no_wavelet" \
bash tools/run_optimized_supervised.sh
```

关闭 frequency refine：

```bash
DATASET=BUSI \
EXTRA_SET_ARGS="model.use_frequency_refine=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_freq logging.experiment_name=xnet_busi_no_freq" \
bash tools/run_optimized_supervised.sh
```

关闭两者：

```bash
DATASET=BUSI \
EXTRA_SET_ARGS="model.use_wavelet_branch=false model.use_frequency_refine=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_wavelet_no_freq logging.experiment_name=xnet_busi_no_wavelet_no_freq" \
bash tools/run_optimized_supervised.sh
```

强制 SS2D 使用 torch fallback：

```bash
DATASET=BUSI \
EXTRA_SET_ARGS="model.ssm_backend=torch checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_ssm_torch logging.experiment_name=xnet_busi_ssm_torch" \
bash tools/run_optimized_supervised.sh
```

## 8. 当前推荐实验顺序

先跑：

1. `BUSI`
2. `DDTI`
3. `TN3K`
4. `TG3K`

再扩：

1. `BUS_UC`
2. `BUS-BRA`
3. `BUS-UCLM`
4. `OTU_2d`
5. `CCAUI`

当前项目的论文主线更适合优先落在甲状腺或乳腺 2D 超声分割。