CLI 参考文档

概述

HABIT 提供了强大的命令行接口（CLI），支持所有核心功能的批处理和自动化。

主要命令：

habit preprocess: 图像预处理
habit get-habitat: 生境分析
habit extract: 特征提取
habit model: 机器学习建模
habit compare: 模型对比分析
habit icc: ICC (组内相关系数) 分析
habit retest: Test-retest 重现性分析
habit merge-csv: CSV 文件合并
habit dicom-info: DICOM 信息提取
habit dice: Dice 系数计算
habit radiomics: 传统影像组学特征提取
habit cv: K-fold 交叉验证
habit --help: 显示帮助信息
habit --version: 显示版本信息

通用参数

所有命令都支持以下通用参数：

--config, -c: 配置文件路径

类型: 字符串
必需: 是
说明: 指定 YAML 配置文件的路径
示例: habit preprocess --config config_preprocessing.yaml

--debug: 启用调试模式

类型: 标志
必需: 否
说明: 启用详细的日志输出，便于调试
示例: habit preprocess --config config.yaml --debug

--help, -h: 显示帮助信息

类型: 标志
必需: 否
说明: 显示命令的帮助信息
示例: habit preprocess --help

--version, -v: 显示版本信息

类型: 标志
必需: 否
说明: 显示 HABIT 的版本信息
示例: habit --version

图像预处理命令

命令: habit preprocess

功能: 对医学图像进行预处理，包括 DICOM 转换、重采样、配准、标准化等。

基本用法:

habit preprocess --config config_preprocessing.yaml

参数:

--config, -c: 配置文件路径（必需）
--debug: 启用调试模式（可选）

配置文件示例:

data_dir: ./files_preprocessing.yaml
out_dir: ./preprocessed

Preprocessing:
  dcm2nii:
    images: [delay2, delay3, delay5]
    dcm2niix_path: ./dcm2niix.exe
    compress: true
    anonymize: true

  n4_correction:
    images: [delay2, delay3, delay5]
    num_fitting_levels: 4

  resample:
    images: [delay2, delay3, delay5]
    target_spacing: [1.0, 1.0, 1.0]

  registration:
    images: [delay2, delay3, delay5]
    fixed_image: delay2
    moving_images: [delay3, delay5]
    type_of_transform: SyNRA
    use_mask: false

  zscore_normalization:
    images: [delay2, delay3, delay5]
    only_inmask: false
    mask_key: mask

processes: 2
random_state: 42

输出:

预处理后的图像保存在 out_dir 指定的目录
处理日志保存在 preprocessing.log

生境分析命令

命令: habit get-habitat

功能: 对预处理后的图像进行生境分割和特征提取。

基本用法:

# 训练模式（以配置文件 run_mode 为准）
habit get-habitat --config config_habitat.yaml --mode train

# 预测模式（需要 pipeline_path 或 --pipeline）
habit get-habitat --config config_habitat.yaml --mode predict --pipeline ./results/habitat_pipeline.pkl

参数:

--config, -c: 配置文件路径（必需）
--mode: 运行模式（可选，用于覆盖配置文件中的 run_mode） - train: 训练新的生境分割模型 - predict: 使用预训练模型进行预测
--pipeline: Pipeline 文件路径（predict 模式必需，用于覆盖配置文件中的 pipeline_path）
--debug: 启用调试模式（可选）

配置文件示例:

run_mode: train
data_dir: ./file_habitat.yaml
out_dir: ./results/habitat/train

FeatureConstruction:
  voxel_level:
    method: concat(raw(delay2), raw(delay3), raw(delay5))
    params: {}

  supervoxel_level:
    supervoxel_file_keyword: '*_supervoxel.nrrd'
    method: mean_voxel_features()
    params:
      params_file: {}

HabitatsSegmention:
  clustering_mode: two_step

  supervoxel:
    algorithm: kmeans
    n_clusters: 50
    random_state: 42

  habitat:
    algorithm: kmeans
    max_clusters: 10
    habitat_cluster_selection_method:
      - inertia
      - silhouette
    random_state: 42

processes: 2
plot_curves: true
save_results_csv: true
random_state: 42

输出:

结果表：`out_dir/habitats.csv`（若启用保存）
生境图：out_dir/<subject>_habitats.nrrd
超像素图（Two-Step）：out_dir/<subject>_supervoxel.nrrd
可视化图表：out_dir/visualizations/
处理日志：out_dir/habitat_analysis.log

特征提取命令

命令: habit extract

功能: 从生境图中提取各种特征。

基本用法:

habit extract --config config_extract_features.yaml

参数:

--config, -c: 配置文件路径（必需）
--debug: 启用调试模式（可选）

配置文件示例:

params_file_of_non_habitat: ./parameter.yaml
params_file_of_habitat: ./parameter_habitat.yaml

raw_img_folder: ./preprocessed/processed_images
habitats_map_folder: ./results/habitat
out_dir: ./results/features

n_processes: 3
habitat_pattern: '*_habitats.nrrd'

feature_types:
  - traditional
  - non_radiomics
  - whole_habitat
  - each_habitat
  - msi
  - ith_score

debug: false

输出:

特征文件保存在 out_dir 指定的目录
处理日志保存在 feature_extraction.log

机器学习命令

命令: habit model

功能: 使用提取的特征进行机器学习建模。

基本用法:

# 训练模式
habit model --config config_machine_learning.yaml --mode train

# 预测模式（配置文件需使用 PredictionConfig 结构）
habit model --config config_ml_predict.yaml --mode predict

参数:

--config, -c: 配置文件路径（必需）
--mode: 运行模式（可选，默认：train） - train: 训练新的机器学习模型 - predict: 使用预训练模型进行预测

配置文件示例 (训练模式):

input:
  - path: ./ml_data/clinical_feature.csv
    subject_id_col: PatientID
    label_col: Label
output: ./results/ml/train
random_state: 42
split_method: stratified
test_size: 0.3

feature_selection_methods:
  - method: variance
    params:
      threshold: 0.0

models:
  LogisticRegression:
    params:
      C: 1.0
      solver: liblinear
      random_state: 42

配置文件示例 (预测模式):

model_path: ./results/ml/train/models/LogisticRegression_final_pipeline.pkl
data_path: ./ml_data/new_data.csv
output_dir: ./results/ml/predict
evaluate: true
label_col: Label

output_label_col: predicted_label
output_prob_col: predicted_probability

输出:

训练输出保存在训练配置中的 output 目录
预测输出保存在预测配置中的 output_dir 目录
预测结果文件默认为 prediction_results.csv

帮助命令

命令: habit --help

功能: 显示 HABIT 的帮助信息，包括所有可用命令和参数。

基本用法:

habit --help

# 显示特定命令的帮助
habit preprocess --help
habit get-habitat --help
habit extract --help
habit model --help

版本命令

命令: habit --version

功能: 显示 HABIT 的版本信息。

基本用法:

habit --version

命令行参数优先级

当同一个参数在配置文件和命令行中都指定时，命令行参数的优先级更高。

**优先级顺序**（从高到低）：

命令行参数
配置文件参数
默认值

示例:

# 配置文件中 processes: 2
# 命令行中指定 processes: 4
habit preprocess --config config.yaml --processes 4

# 实际使用的进程数为 4（命令行参数优先）

错误处理

当命令执行失败时，HABIT 会：

显示错误信息: 在控制台显示清晰的错误信息
记录错误日志: 在日志文件中记录详细的错误堆栈
提供解决建议: 对于常见错误，提供解决建议

常见错误及解决方法:

配置文件不存在: 检查配置文件路径是否正确
数据路径不存在: 检查数据路径是否正确
参数错误: 检查配置文件中的参数是否正确
依赖缺失: 安装缺失的依赖包

日志记录

HABIT 会记录详细的日志信息，便于调试和问题排查。

日志级别:

DEBUG: 详细的调试信息
INFO: 一般信息
WARNING: 警告信息
ERROR: 错误信息
CRITICAL: 严重错误信息

日志文件:

每个命令都会生成对应的日志文件
日志文件保存在输出目录中
日志文件命名格式：<command>.log

启用调试模式:

habit preprocess --config config.yaml --debug

批处理示例

示例 1: 批量预处理

# 创建批处理脚本
cat > batch_preprocess.sh << 'EOF'
#!/bin/bash
for config in config_*.yaml; do
    echo "Processing $config..."
    habit preprocess --config "$config" --debug
done
EOF

# 运行批处理
chmod +x batch_preprocess.sh
./batch_preprocess.sh

示例 2: 完整工作流程

# 1. 预处理
habit preprocess --config config_preprocessing.yaml

# 2. 生境分析（训练）
habit get-habitat --config config_habitat.yaml --mode train

# 3. 特征提取
habit extract --config config_extract_features.yaml

# 4. 机器学习（训练）
habit model --config config_machine_learning.yaml --mode train

示例 3: 预测模式

# 1. 生境分析（预测）
habit get-habitat --config config_habitat.yaml --mode predict --pipeline ./results/habitat_pipeline.pkl

# 2. 特征提取
habit extract --config config_extract_features.yaml

# 3. 机器学习（预测）
habit model --config config_ml_predict.yaml --mode predict

示例 4: 模型对比分析

# 模型对比分析
habit compare --config config_model_comparison.yaml

示例 5: ICC 分析

# ICC 分析
habit icc --config config_icc.yaml

示例 6: Test-Retest 分析

# Test-Retest 分析
habit retest --config config_test_retest.yaml

示例 7: CSV 合并

# 合并多个 CSV 文件
habit merge-csv file1.csv file2.csv file3.csv -o merged.csv --index-col PatientID

示例 8: DICOM 信息提取

# 提取 DICOM 信息
habit dicom-info -i ./dicom_directory -o dicom_info.csv --tags "PatientName,StudyDate,Modality"

示例 9: Dice 系数计算

# 计算 Dice 系数
habit dice --input1 ./masks1 --input2 ./masks2 --output dice_results.csv

示例 10: 传统影像组学特征提取

# 传统影像组学特征提取
habit radiomics --config config_radiomics.yaml

示例 11: K-fold 交叉验证

# K-fold 交叉验证
habit cv --config config_machine_learning.yaml

命令详细说明:

habit compare: 模型对比分析 - 参数: --config, -c (必需) - 功能: 比较多个模型的性能，生成 ROC 曲线、校准曲线等
habit icc: ICC (组内相关系数) 分析 - 参数: --config, -c (必需) - 功能: 评估特征在不同扫描条件下的可重复性
habit retest: Test-retest 重现性分析 - 参数: --config, -c (可选，也可以使用命令行参数) - 功能: 评估生境映射在测试-重测扫描中的稳定性
habit merge-csv: CSV 文件合并 - 参数: input_files (必需), --output, -o (必需), --index-col, -c (可选) - 功能: 基于索引列水平合并多个 CSV/Excel 文件
habit dicom-info: DICOM 信息提取 - 参数: --input, -i (必需), --tags, -t (可选), --output, -o (可选) - 功能: 提取 DICOM 文件的元数据信息
habit dice: Dice 系数计算 - 参数: --input1 (必需), --input2 (必需), --output (可选) - 功能: 计算两批图像之间的 Dice 系数
habit radiomics: 传统影像组学特征提取 - 参数: --config, -c (可选) - 功能: 提取传统影像组学特征
habit cv: K-fold 交叉验证 - 参数: --config, -c (必需) - 功能: 执行 K 折交叉验证评估

常见问题

Q1: 如何查看命令的详细帮助？

A: 使用 --help 参数：

habit preprocess --help

Q2: 如何启用调试模式？

A: 使用 --debug 参数：

habit preprocess --config config.yaml --debug

Q3: 如何查看 HABIT 的版本？

A: 使用 --version 参数：

habit --version

Q4: 如何批处理多个配置文件？

A: 使用 shell 脚本或循环：

for config in config_*.yaml; do
    habit preprocess --config "$config"
done

Q5: 如何处理命令执行失败？

A: 查看错误信息和日志文件：

# 查看日志文件
cat preprocessing.log

# 使用调试模式重新运行
habit preprocess --config config.yaml --debug

下一步

现在您已经了解了 CLI 的使用方法，可以：

配置参考: 了解配置文件的详细说明
用户指南: 了解各个功能的详细使用指南
自定义扩展指南: 了解如何自定义和扩展功能