ccf-habitat 0.3.0__tar.gz

ccf_habitat-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pan Ziqi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ccf_habitat-0.3.0/NOTICE

@@ -0,0 +1,25 @@
+ccf-habitat (CCF) — Third-Party Notices
+=========================================
+
+This package integrates the following third-party open-source component:
+
+maskslic
+--------
+- Component: masked SLIC supervoxel generation (used by ccf.maskslic)
+- Author/Copyright: Copyright (C) 2016-2019, Benjamin Irving
+- License: BSD-3-Clause (redistribution and use in source and binary forms,
+  with or without modification, are permitted provided that the conditions of
+  the BSD-3-Clause license are met; see the license file distributed with the
+  maskslic package, e.g. maskslic-0.3.4.dist-info/LICENSE.txt)
+- Source: https://pypi.org/project/maskslic/ | https://www.birving.com
+- Upstream usage in this project: the maskslic scripts integrated from the
+  BESMNN biology-analysis kernel-validation package (s01_slic stage),
+  parameter conventions preserved as-is (human single-channel
+  compactness=10; BraTS19 multi-channel compactness=0.5).
+
+The above notice is provided to comply with the BSD-3-Clause attribution
+requirement. No modification is made to the maskslic algorithm itself;
+ccf.maskslic only performs I/O, geometry preservation and parallel
+orchestration around it.
+
+ccf-habitat itself is distributed under the MIT License (see LICENSE).

ccf_habitat-0.3.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: ccf-habitat
+Version: 0.3.0
+Summary: Consistency-constrained framework for CT habitat clustering (BESP2/P2 algorithm package)
+Author: Pan Ziqi
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: pandas>=1.3
+Requires-Dist: scikit-learn==1.6.1
+Requires-Dist: SimpleITK>=2.0
+Requires-Dist: PyRadiomics>=3.0
+Requires-Dist: tqdm>=4.60
+Requires-Dist: joblib>=1.0
+Requires-Dist: psutil>=5.8
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: maskslic>=0.3
+Dynamic: license-file
+
+# ccf-habitat
+
+一致性约束的 CT 影像栖息地（habitat）亚区分割工具包。
+算法内核为 **BESP2**（BESMNN 谱聚类扩展版：超节点特征 → 迭代扩展 → 全局图 → 谱聚类）与
+**P2**（五个冻结人源参考预测器，纯 NumPy），用于肺癌等肿瘤 CT 的亚区域无监督分割与跨物种判别。
+
+本包把原先"一键脚本 + 数据同包"的调用方式重构为标准 Python 包：
+
+- `pip install -e .` 即可安装，提供 `ccf-train` / `ccf-predict` / `ccf-example` / `ccf-list-data` / `ccf-slic` 命令；
+- 算法代码原样归档（`ccf/engine_besp2.py`、`ccf/selfsp.py`、`ccf/predictors.py`），**不重写逻辑**，
+  因此结果与既有权威输出一致；
+- **数据不捆绑**：约 35 GB 的影像/中间数据通过 `data_root` 指向外部目录（默认自动探测本机
+  `D:\Software-develop\BESMNN\biology-analysis\02_input`），GitHub 上只保留代码与配置。
+
+## 安装
+
+```bash
+python -m pip install -e .
+# 或直接以包根为工作目录：export PYTHONPATH=<包根>（Windows: $env:PYTHONPATH="<包根>"）
+```
+
+依赖：numpy / scipy / pandas / scikit-learn==1.6.1 / SimpleITK / PyRadiomics / tqdm / joblib / psutil / matplotlib / pyyaml / maskslic。
+
+## 数据策略
+
+| 内容 | 位置 |
+|---|---|
+| 代码 / 配置 / 示例 | 本仓库（GitHub 可公开） |
+| 人源 539 例 CT/ROI/超体素 mask | `02_input/human/besp2_source/shared/{ct,sub,merged_masks}`（外部） |
+| 人源 BESP2 工作套（split、模型、日志） | `02_input/human/besp2_source/BS{3,6,10}`（外部） |
+| 鼠源（6 例）与病理基准 | `02_input/mouse*`、`02_input/mouse_pathology`（外部） |
+
+`data_root` 解析优先级：命令行 `--data-root` / yaml 配置 > 环境变量 `CCF_DATA_ROOT` > 本机默认路径。
+
+## 用法
+
+### 命令行
+
+```bash
+# 查看数据布局探测结果
+ccf-list-data
+
+# 冒烟：前 3 例跑通完整训练链（CPU 可跑，证明安装与调用链路）
+ccf-train -k 3 -o ./out --subset 3
+
+# 完整：全 539 例 K=6 训练+测试（重型，需 GPU 与较长时间）
+ccf-train -k 6 -o ./out --mode train_test
+
+# 判别（P2 预测器；reference 通过 CCF_DATA_REFERENCE 预置）
+ccf-predict -m P2 -i embedding.npy -o ./out
+```
+
+### Python API
+
+```python
+from ccf import CCFHabitatModel, CCFConfig
+
+model = CCFHabitatModel(CCFConfig(k=3, output_dir="./out"))
+fit = model.fit(subset=3)            # 冒烟；去掉 subset=3 为全量
+print(fit["train_data_path"])
+
+from ccf.predictors import FrozenReference
+ref = FrozenReference.from_model(spectral_model, train_index_mapping)
+res = model.predict("P2", ref, embedding=mouse_embedding)   # labels/scores/margin
+```
+
+## 与既有权威流程的关系（结果一致性）
+
+| 组件 | 来源（biology-analysis 核验包） | 本包 |
+|---|---|---|
+| BESP2 主算法 | `01_code/s02_besp2_human/1.BESMNNCORRECT4.5.py` | `ccf/engine_besp2.py`（原样复制，改相对导入） |
+| 谱聚类 | `01_code/s02_besp2_human/selfsp.py` | `ccf/selfsp.py` |
+| P2 预测器 | `01_code/s02_besp2_human/new_predictors.py` | `ccf/predictors.py`（原样复制） |
+| PyRadiomics 配置 | — | `ccf/configs/default_radiomics.yaml` |
+| maskslic 超体素 | `01_code/s01_slic/0.Maskslic20-多线程_human.py`、`1.Maskslic100brats-多线程.py` | `ccf/maskslic.py`（参数口径原样保留） |
+
+## 超体素生成（ccf-slic，集成 maskslic）
+
+上游 `s01_slic` 阶段用 **PyPI maskslic 包**（Benjamin Irving，BSD-3-Clause，scikit-image SLIC 的
+mask 约束变体）生成"仅肿瘤区域内"的超体素；本包把两套上游脚本的参数口径原样集成进
+`ccf/maskslic.py`，只做 I/O、几何信息保留与并行编排，不修改算法。第三方许可声明见 `NOTICE`。
+
+```bash
+# 单例：单模态（人源口径 compactness=10）或多模态（BraTS 口径 compactness=0.5 需显式指定）
+ccf-slic --img ct.nii.gz --roi roi.nii.gz --out subregion_label.nii.gz
+ccf-slic --img t1.nii.gz,t1ce.nii.gz,t2.nii.gz,flair.nii.gz --roi seg.nii.gz \
+         --out label.nii.gz --compactness 0.5
+
+# 批量：img_dir 与 roi_dir 按文件名基线匹配，并行生成（对齐上游 execute_parallel）
+ccf-slic --img-dir ./fuse --roi-dir ./roi2 --out-dir ./labels --workers 8
+```
+
+```python
+from ccf.maskslic import supervoxels, batch_supervoxels
+supervoxels("ct.nii.gz", "roi.nii.gz", "subregion_label.nii.gz")       # 单模态
+supervoxels(["t1.nii.gz", "flair.nii.gz"], "seg.nii.gz", "out.nii.gz",
+            compactness=0.5)                                            # 多通道
+```
+
+既有 9 步全链核验（输入完整性自检、NMF 复现、表 1、三算法病理 KW、RNAseq 方向一致性、
+多重校正、表 5 二项检验）仍由 `D:\Software-develop\BESMNN\biology-analysis` 包 `run_all.py` 提供；
+本包负责把 BESP2/P2 调用标准化，供第三方复现与二次开发。
+
+## 目录结构
+
+```
+ccf/
+├── pyproject.toml          # 可安装包定义 + 命令行入口
+├── ccf/
+│   ├── config.py           # 数据路径/参数配置（yaml / 环境变量 / 默认值）
+│   ├── dataset.py          # 02_input 布局解析
+│   ├── engine_besp2.py     # BESP2 主算法（上游原样归档）
+│   ├── selfsp.py           # 谱聚类修改版（sklearn 1.6.1 扩展）
+│   ├── predictors.py       # P2 冻结人源参考预测器（P1-P5）
+│   ├── model.py            # CCFHabitatModel 高层封装（fit/predict）
+│   ├── maskslic.py         # maskslic 超体素生成（上游 s01_slic 集成）
+│   ├── output.py           # 报告输出
+│   ├── cli.py              # ccf-* 命令
+│   └── configs/            # 默认 yaml
+└── example/                # 小样本冒烟示例 + 数据指引
+```
+
+## 说明
+
+- `02_input` 内数据目录保留上游原始命名（`BES`/`OK`/`BS3`/`5mouse` 等），与源逐文件 MD5 同批，
+  勿改名（详见 `biology-analysis` 包 README 命名映射表）。
+- K=3/6/10 均为论文口径；`run_mode="train"` 只训练、`"test"` 需已有 `train_data.npz`。
+- 本包为科研复现用途；重跑全量需满足原始环境的依赖版本（尤其 scikit-learn==1.6.1）。

ccf_habitat-0.3.0/README.md

@@ -0,0 +1,128 @@
+# ccf-habitat
+
+一致性约束的 CT 影像栖息地（habitat）亚区分割工具包。
+算法内核为 **BESP2**（BESMNN 谱聚类扩展版：超节点特征 → 迭代扩展 → 全局图 → 谱聚类）与
+**P2**（五个冻结人源参考预测器，纯 NumPy），用于肺癌等肿瘤 CT 的亚区域无监督分割与跨物种判别。
+
+本包把原先"一键脚本 + 数据同包"的调用方式重构为标准 Python 包：
+
+- `pip install -e .` 即可安装，提供 `ccf-train` / `ccf-predict` / `ccf-example` / `ccf-list-data` / `ccf-slic` 命令；
+- 算法代码原样归档（`ccf/engine_besp2.py`、`ccf/selfsp.py`、`ccf/predictors.py`），**不重写逻辑**，
+  因此结果与既有权威输出一致；
+- **数据不捆绑**：约 35 GB 的影像/中间数据通过 `data_root` 指向外部目录（默认自动探测本机
+  `D:\Software-develop\BESMNN\biology-analysis\02_input`），GitHub 上只保留代码与配置。
+
+## 安装
+
+```bash
+python -m pip install -e .
+# 或直接以包根为工作目录：export PYTHONPATH=<包根>（Windows: $env:PYTHONPATH="<包根>"）
+```
+
+依赖：numpy / scipy / pandas / scikit-learn==1.6.1 / SimpleITK / PyRadiomics / tqdm / joblib / psutil / matplotlib / pyyaml / maskslic。
+
+## 数据策略
+
+| 内容 | 位置 |
+|---|---|
+| 代码 / 配置 / 示例 | 本仓库（GitHub 可公开） |
+| 人源 539 例 CT/ROI/超体素 mask | `02_input/human/besp2_source/shared/{ct,sub,merged_masks}`（外部） |
+| 人源 BESP2 工作套（split、模型、日志） | `02_input/human/besp2_source/BS{3,6,10}`（外部） |
+| 鼠源（6 例）与病理基准 | `02_input/mouse*`、`02_input/mouse_pathology`（外部） |
+
+`data_root` 解析优先级：命令行 `--data-root` / yaml 配置 > 环境变量 `CCF_DATA_ROOT` > 本机默认路径。
+
+## 用法
+
+### 命令行
+
+```bash
+# 查看数据布局探测结果
+ccf-list-data
+
+# 冒烟：前 3 例跑通完整训练链（CPU 可跑，证明安装与调用链路）
+ccf-train -k 3 -o ./out --subset 3
+
+# 完整：全 539 例 K=6 训练+测试（重型，需 GPU 与较长时间）
+ccf-train -k 6 -o ./out --mode train_test
+
+# 判别（P2 预测器；reference 通过 CCF_DATA_REFERENCE 预置）
+ccf-predict -m P2 -i embedding.npy -o ./out
+```
+
+### Python API
+
+```python
+from ccf import CCFHabitatModel, CCFConfig
+
+model = CCFHabitatModel(CCFConfig(k=3, output_dir="./out"))
+fit = model.fit(subset=3)            # 冒烟；去掉 subset=3 为全量
+print(fit["train_data_path"])
+
+from ccf.predictors import FrozenReference
+ref = FrozenReference.from_model(spectral_model, train_index_mapping)
+res = model.predict("P2", ref, embedding=mouse_embedding)   # labels/scores/margin
+```
+
+## 与既有权威流程的关系（结果一致性）
+
+| 组件 | 来源（biology-analysis 核验包） | 本包 |
+|---|---|---|
+| BESP2 主算法 | `01_code/s02_besp2_human/1.BESMNNCORRECT4.5.py` | `ccf/engine_besp2.py`（原样复制，改相对导入） |
+| 谱聚类 | `01_code/s02_besp2_human/selfsp.py` | `ccf/selfsp.py` |
+| P2 预测器 | `01_code/s02_besp2_human/new_predictors.py` | `ccf/predictors.py`（原样复制） |
+| PyRadiomics 配置 | — | `ccf/configs/default_radiomics.yaml` |
+| maskslic 超体素 | `01_code/s01_slic/0.Maskslic20-多线程_human.py`、`1.Maskslic100brats-多线程.py` | `ccf/maskslic.py`（参数口径原样保留） |
+
+## 超体素生成（ccf-slic，集成 maskslic）
+
+上游 `s01_slic` 阶段用 **PyPI maskslic 包**（Benjamin Irving，BSD-3-Clause，scikit-image SLIC 的
+mask 约束变体）生成"仅肿瘤区域内"的超体素；本包把两套上游脚本的参数口径原样集成进
+`ccf/maskslic.py`，只做 I/O、几何信息保留与并行编排，不修改算法。第三方许可声明见 `NOTICE`。
+
+```bash
+# 单例：单模态（人源口径 compactness=10）或多模态（BraTS 口径 compactness=0.5 需显式指定）
+ccf-slic --img ct.nii.gz --roi roi.nii.gz --out subregion_label.nii.gz
+ccf-slic --img t1.nii.gz,t1ce.nii.gz,t2.nii.gz,flair.nii.gz --roi seg.nii.gz \
+         --out label.nii.gz --compactness 0.5
+
+# 批量：img_dir 与 roi_dir 按文件名基线匹配，并行生成（对齐上游 execute_parallel）
+ccf-slic --img-dir ./fuse --roi-dir ./roi2 --out-dir ./labels --workers 8
+```
+
+```python
+from ccf.maskslic import supervoxels, batch_supervoxels
+supervoxels("ct.nii.gz", "roi.nii.gz", "subregion_label.nii.gz")       # 单模态
+supervoxels(["t1.nii.gz", "flair.nii.gz"], "seg.nii.gz", "out.nii.gz",
+            compactness=0.5)                                            # 多通道
+```
+
+既有 9 步全链核验（输入完整性自检、NMF 复现、表 1、三算法病理 KW、RNAseq 方向一致性、
+多重校正、表 5 二项检验）仍由 `D:\Software-develop\BESMNN\biology-analysis` 包 `run_all.py` 提供；
+本包负责把 BESP2/P2 调用标准化，供第三方复现与二次开发。
+
+## 目录结构
+
+```
+ccf/
+├── pyproject.toml          # 可安装包定义 + 命令行入口
+├── ccf/
+│   ├── config.py           # 数据路径/参数配置（yaml / 环境变量 / 默认值）
+│   ├── dataset.py          # 02_input 布局解析
+│   ├── engine_besp2.py     # BESP2 主算法（上游原样归档）
+│   ├── selfsp.py           # 谱聚类修改版（sklearn 1.6.1 扩展）
+│   ├── predictors.py       # P2 冻结人源参考预测器（P1-P5）
+│   ├── model.py            # CCFHabitatModel 高层封装（fit/predict）
+│   ├── maskslic.py         # maskslic 超体素生成（上游 s01_slic 集成）
+│   ├── output.py           # 报告输出
+│   ├── cli.py              # ccf-* 命令
+│   └── configs/            # 默认 yaml
+└── example/                # 小样本冒烟示例 + 数据指引
+```
+
+## 说明
+
+- `02_input` 内数据目录保留上游原始命名（`BES`/`OK`/`BS3`/`5mouse` 等），与源逐文件 MD5 同批，
+  勿改名（详见 `biology-analysis` 包 README 命名映射表）。
+- K=3/6/10 均为论文口径；`run_mode="train"` 只训练、`"test"` 需已有 `train_data.npz`。
+- 本包为科研复现用途；重跑全量需满足原始环境的依赖版本（尤其 scikit-learn==1.6.1）。

ccf_habitat-0.3.0/ccf/__init__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""ccf-habitat: 一致性约束的 CT 影像栖息地（habitat）聚类包。
+
+算法内核 = 上游 BESP2（BESMNN 谱聚类扩展版 + P2 冻结人源参考预测器）。
+本包为可安装、可移植的标准 Python 包封装：
+  - ``ccf-train``：人源 CT/ROI/超体素 mask -> 全局图 + 谱聚类 -> 亚区分割
+  - ``ccf-predict``：P2 冻结参考预测器判别接口
+  - ``ccf-example``：小样本一键冒烟示例（证明安装/调用链路可跑）
+
+数据不随包分发（约 35 GB），通过配置文件或环境变量指向外部数据目录，
+默认探测 ``D:\\Software-develop\\BESMNN\\biology-analysis\\02_input``。
+"""
+from .config import CCFConfig, default_data_root
+from .model import CCFHabitatModel
+
+__version__ = "0.3.0"
+__all__ = ["CCFConfig", "CCFHabitatModel", "default_data_root", "__version__"]

ccf_habitat-0.3.0/ccf/cli.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""命令行入口：ccf-train / ccf-predict / ccf-example / ccf-list-data。
+
+用法示例：
+  ccf-train -k 3 -o ./out --subset 3        # 冒烟：前 3 例跑通训练链
+  ccf-train -k 6 -o ./out                   # 完整：全 539 例（重型，需 GPU/长时间）
+  ccf-predict -m P2 -i embedding.npy        # P2 收缩高斯判别（需 reference 预置）
+  ccf-example                                # 一键示例（小样本）
+  ccf-list-data                              # 查看数据布局探测结果
+"""
+import argparse
+import os
+import sys
+
+import numpy as np
+
+from .config import CCFConfig
+from .model import CCFHabitatModel
+from . import dataset, output
+
+
+def _common_args(ap):
+    ap.add_argument("--data-root", default=None, help="数据根目录（02_input）")
+    ap.add_argument("-o", "--output-dir", default=None, help="输出目录")
+    ap.add_argument("--config-yaml", default=None, help="yaml 配置覆盖")
+
+
+def train_main(argv=None):
+    ap = argparse.ArgumentParser(prog="ccf-train", description="人源 BESP2 训练/测试链（CCF）")
+    _common_args(ap)
+    ap.add_argument("-k", "--n-clusters", type=int, default=3, choices=(3, 6, 10), help="聚类数")
+    ap.add_argument("--subset", default=None,
+                    help="int=取前 N 例冒烟；逗号分隔 id 列表=指定样本")
+    ap.add_argument("--mode", default="train_test", choices=("train", "train_test", "test"),
+                    help="运行模式")
+    args = ap.parse_args(argv)
+
+    kw = dict(k=args.n_clusters, run_mode=args.mode)
+    if args.data_root:
+        kw["data_root"] = args.data_root
+    if args.output_dir:
+        kw["output_dir"] = args.output_dir
+    if args.config_yaml:
+        cfg = CCFConfig.from_yaml(args.config_yaml, **kw)
+    else:
+        cfg = CCFConfig(**kw)
+
+    subset = None
+    if args.subset:
+        subset = int(args.subset) if args.subset.isdigit() else args.subset.split(",")
+
+    model = CCFHabitatModel(cfg)
+    fit = model.fit(subset=subset)
+    report = output.write_fit_report(fit, os.path.join(fit["output_dir"], "fit_report.txt"))
+    print(report)
+    print("\n完成。输出: %s" % fit["output_dir"])
+    return 0
+
+
+def predict_main(argv=None):
+    ap = argparse.ArgumentParser(prog="ccf-predict", description="P2 冻结人源参考预测器判别")
+    _common_args(ap)
+    ap.add_argument("-m", "--method", required=True, choices=("P1", "P2", "P3", "P4", "P5"))
+    ap.add_argument("-i", "--embedding", default=None, help="npy 文件（P1-P4）")
+    ap.add_argument("--w-human-mouse", default=None, help="npz 文件中的跨物种图（P5）")
+    args = ap.parse_args(argv)
+
+    cfg = CCFConfig(**(dict(data_root=args.data_root) if args.data_root else {}))
+    model = CCFHabitatModel(cfg)
+
+    # reference：CLI 版简化——从环境/约定路径加载。完整用法见 example/README.md。
+    ref = _load_default_reference()
+    if ref is None:
+        print("未预置 FrozenReference。Python API 用法：\n"
+              "  from ccf.predictors import FrozenReference\n"
+              "  ref = FrozenReference.from_model(model, mapping)\n"
+              "  CCFHabitatModel().predict('P2', ref, embedding=embedding)")
+        return 2
+
+    kw = {}
+    if args.method == "P5":
+        if not args.w_human_mouse:
+            print("P5 需要 --w-human-mouse <npz>")
+            return 2
+        kw["w_human_mouse"] = np.load(args.w_human_mouse)["w"]
+    else:
+        if not args.embedding:
+            print("P1-P4 需要 -i embedding.npy")
+            return 2
+        kw["embedding"] = np.load(args.embedding)
+
+    result = model.predict(args.method, ref, **kw)
+    out_dir = args.output_dir or os.path.join(os.getcwd(), "ccf_output")
+    os.makedirs(out_dir, exist_ok=True)
+    print(output.write_predict_report(result, os.path.join(out_dir, "predict_report.txt")))
+    return 0
+
+
+def example_main(argv=None):
+    ap = argparse.ArgumentParser(prog="ccf-example", description="小样本一键冒烟示例")
+    _common_args(ap)
+    args = ap.parse_args(argv)
+
+    cfg = CCFConfig(**(dict(data_root=args.data_root) if args.data_root else {}))
+    print("数据根: %s" % cfg.data_root)
+    print(dataset.describe(cfg.data_root))
+    model = CCFHabitatModel(cfg)
+    fit = model.fit(subset=3, output_dir=args.output_dir)
+    print(output.write_fit_report(fit, os.path.join(fit["output_dir"], "fit_report.txt")))
+    print("\n冒烟完成。输出: %s" % fit["output_dir"])
+    return 0
+
+
+def list_data_main(argv=None):
+    ap = argparse.ArgumentParser(prog="ccf-list-data", description="数据布局探测")
+    ap.add_argument("--data-root", default=None)
+    args = ap.parse_args(argv)
+    cfg = CCFConfig(**(dict(data_root=args.data_root) if args.data_root else {}))
+    print(dataset.describe(cfg.data_root))
+    return 0
+
+
+def slic_main(argv=None):
+    """ccf-slic：maskslic 超体素生成（上游 s01_slic 阶段）。
+
+    单例（多模态/单模态）：
+      ccf-slic --img ct.nii.gz --roi roi.nii.gz --out out/label.nii.gz
+      ccf-slic --img t1.nii.gz,t1ce.nii.gz,t2.nii.gz,flair.nii.gz --roi seg.nii.gz --out out.nii.gz --compactness 0.5
+    批量（img_dir 与 roi_dir 按文件名基线匹配）：
+      ccf-slic --img-dir ./fuse --roi-dir ./roi2 --out-dir ./labels --workers 8
+    """
+    from . import maskslic as _ms
+
+    ap = argparse.ArgumentParser(prog="ccf-slic", description="maskslic 超体素生成")
+    ap.add_argument("--img", default=None, help="单模态文件或逗号分隔多模态列表")
+    ap.add_argument("--roi", default=None, help="肿瘤/ROI mask 文件")
+    ap.add_argument("--out", default=None, help="输出 NIfTI 路径（单例模式）")
+    ap.add_argument("--img-dir", default=None, help="批量模式：图像目录（单模态）")
+    ap.add_argument("--roi-dir", default=None, help="批量模式：ROI 目录")
+    ap.add_argument("--out-dir", default=None, help="批量模式：输出目录")
+    ap.add_argument("--n-segments", type=int, default=100, help="目标超体素数量（默认 100，对齐上游）")
+    ap.add_argument("--compactness", type=float, default=None,
+                    help="紧凑度（默认自动：多通道 0.5 / 单通道 10，对齐上游口径）")
+    ap.add_argument("--workers", type=int, default=None, help="批量并行进程数（默认 CPU 核数）")
+    args = ap.parse_args(argv)
+
+    kw = dict(n_segments=args.n_segments)
+    if args.compactness is not None:
+        kw["compactness"] = args.compactness
+
+    if args.img and args.roi and args.out:
+        img_paths = args.img.split(",")
+        _ms.supervoxels(img_paths, args.roi, args.out, **kw)
+        print("完成: %s" % args.out)
+        return 0
+    if args.img_dir and args.roi_dir and args.out_dir:
+        ok, total = _ms.batch_supervoxels(args.img_dir, args.roi_dir, args.out_dir,
+                                          workers=args.workers, **kw)
+        print("批量完成: 成功 %d/%d" % (ok, total))
+        return 0 if ok == total else 1
+    ap.print_help()
+    return 2
+
+
+def _load_default_reference():
+    """CLI 简化用：默认 reference 从 CCF_DATA_REFERENCE 环境变量指向的 npy 加载。"""
+    path = os.environ.get("CCF_DATA_REFERENCE", "")
+    if not path or not os.path.exists(path):
+        return None
+    from .predictors import FrozenReference
+    d = np.load(path, allow_pickle=True)
+    return FrozenReference(d["embedding"], d["labels"], d["patient_ids"])
+
+
+if __name__ == "__main__":
+    sys.exit(train_main())

ccf_habitat-0.3.0/ccf/config.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+"""配置：数据路径 + 运行参数，支持 yaml / 环境变量 / 默认值三级覆盖。
+
+GitHub 友好原则：本包不捆绑数据。所有大体积数据（02_input 约 35 GB）
+通过 ``data_root`` 指向外部目录；找不到时给出明确报错与指引。
+"""
+import os
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+# 默认探测路径（本机现有biology-analysis 核验包数据根）
+_DEFAULT_CANDIDATES = [
+    r"D:\Software-develop\BESMNN\biology-analysis\02_input",
+]
+
+_PKG_DIR = os.path.dirname(os.path.abspath(__file__))
+DEFAULT_RADIOMICS_YAML = os.path.join(_PKG_DIR, "configs", "default_radiomics.yaml")
+
+
+def default_data_root():
+    """返回第一个存在的候选数据根；全部不存在时返回空字符串。"""
+    env = os.environ.get("CCF_DATA_ROOT", "").strip()
+    if env and os.path.isdir(env):
+        return env
+    for c in _DEFAULT_CANDIDATES:
+        if os.path.isdir(c):
+            return c
+    return ""
+
+
+class CCFConfig:
+    """CCF 运行配置。
+
+    Parameters
+    ----------
+    data_root : str, optional
+        数据根目录（含 human/mouse 等）。默认见 :func:`default_data_root`。
+    k : int
+        聚类数（3/6/10，论文口径）。默认 3。
+    output_dir : str, optional
+        结果输出目录。默认 ``./ccf_output``。
+    case_subset : int or list or None
+        None=全部样本；int=取前 N 例（冒烟测试）；list=指定样本名。
+    run_mode : str
+        ``"train"`` / ``"train_test"`` / ``"test"``，透传 BESP2 引擎。
+    radiomics_yaml : str, optional
+        PyRadiomics 配置。默认包内 ``configs/default_radiomics.yaml``。
+    seed : int
+        随机种子（BESP2 引擎沿用其内部逻辑；本字段留作记录）。
+    """
+
+    def __init__(self, data_root=None, k=3, output_dir=None,
+                 case_subset=None, run_mode="train",
+                 radiomics_yaml=None, seed=2027):
+        self.data_root = data_root if data_root is not None else default_data_root()
+        self.k = int(k)
+        self.output_dir = output_dir or os.path.join(os.getcwd(), "ccf_output")
+        self.case_subset = case_subset
+        self.run_mode = run_mode
+        self.radiomics_yaml = radiomics_yaml or DEFAULT_RADIOMICS_YAML
+        self.seed = seed
+        if not self.data_root:
+            raise ValueError(
+                "未找到数据根目录。请设置环境变量 CCF_DATA_ROOT，或传入 data_root="
+                "指向 02_input 数据目录（本机: D:\\Software-develop\\BESMNN\\biology-analysis\\02_input）。"
+            )
+
+    # ---- 序列化 ----
+    def to_dict(self):
+        return dict(data_root=self.data_root, k=self.k, output_dir=self.output_dir,
+                    case_subset=self.case_subset, run_mode=self.run_mode,
+                    radiomics_yaml=self.radiomics_yaml, seed=self.seed)
+
+    @classmethod
+    def from_yaml(cls, path, **overrides):
+        if yaml is None:
+            raise ImportError("需要 pyyaml: python -m pip install pyyaml")
+        with open(path, "r", encoding="utf-8") as f:
+            d = yaml.safe_load(f) or {}
+        d.update(overrides)
+        return cls(**d)
+
+    def save_yaml(self, path):
+        if yaml is None:
+            raise ImportError("需要 pyyaml: python -m pip install pyyaml")
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.safe_dump(self.to_dict(), f, allow_unicode=True, sort_keys=False)
+
+    def __repr__(self):
+        return "CCFConfig(data_root=%s, k=%d, run_mode=%s)" % (
+            self.data_root, self.k, self.run_mode)

ccf_habitat-0.3.0/ccf/configs/default_ccf.yaml

@@ -0,0 +1,8 @@
+# ccf-habitat 默认配置（可被命令行参数覆盖）
+data_root: ""                # 留空则自动探测（环境变量 CCF_DATA_ROOT 或本机 02_input）
+k: 3                         # 聚类数 3/6/10
+output_dir: ./ccf_output     # 结果输出目录
+run_mode: train_test         # train / train_test / test
+case_subset: null            # null=全部；int=前 N 例冒烟；[ids]=指定样本
+radiomics_yaml: ""           # 留空用包内 configs/default_radiomics.yaml
+seed: 2027

ccf_habitat-0.3.0/ccf/configs/default_radiomics.yaml

@@ -0,0 +1,22 @@
+# Built-in default PyRadiomics parameter file.
+# Replace with your study-specific radiomics.yaml using -r/--radiomics when needed.
+
+imageType:
+  Original: {}
+
+featureClass:
+  firstorder: []
+  shape: []
+  glcm: []
+  glrlm: []
+  glszm: []
+  gldm: []
+  ngtdm: []
+
+setting:
+  binWidth: 25
+  interpolator: sitkBSpline
+  resampledPixelSpacing: null
+  normalize: false
+  removeOutliers: null
+  label: 1