habit-feature-extraction

name

habit-feature-extraction

description

Extract quantitative features from HABIT habitat maps — traditional radiomics, whole-habitat radiomics, per-habitat radiomics, MSI (Most Significant Intensity), and ITH (Intra-Tumor Heterogeneity) scores. Use when the user has habitat .nrrd maps and wants per-subject feature CSVs ready for ML. Triggers on "提取生境特征", "MSI 特征", "ITH 异质性", "habitat features", "extract radiomics from habitats". Runs `habit extract`.

HABIT Feature Extraction

Extract per-subject quantitative features from previously generated habitat maps. Output is a set of CSV files ready for ML.

CLI

habit extract --config <config_extract_features.yaml>

Required Information

Field	Notes
raw_img_folder	preprocessed images + masks
habitats_map_folder	output of habit get-habitat
out_dir	where CSVs land
feature_types	what to extract (see table below)
habitat_pattern	*_habitats.nrrd for one_step, *_habitats_remapped.nrrd for two_step
params_file_of_*	optional for radiomics types; omit → bundled roi / habitat presets

Feature types

Type	What	Output CSV	Needs PyRadiomics?
traditional	Whole-tumor radiomics on original images	raw_image_radiomics.csv	Yes (params_file_of_non_habitat)
non_radiomics	Volumes, fractions, basic stats	habitat_basic_features.csv	No
whole_habitat	Radiomics on the entire habitat label map	whole_habitat_radiomics.csv	Yes (params_file_of_habitat)
each_habitat	Radiomics for each habitat independently	each_habitat_radiomics.csv	Yes
msi	Most Significant Intensity stats per habitat	msi_features.csv	No
ith_score	Intra-Tumor Heterogeneity entropy scores	ith_scores.csv	No

Recommendations

• Standard publication setup: [traditional, non_radiomics, whole_habitat, msi, ith_score]
  • Use template config/feature_extraction/config_extract_features.yaml.
• Maximum features (slow, high-dim): add each_habitat. Only do this for cohorts >200.
• No PyRadiomics installed: [non_radiomics, msi, ith_score]
  • Use template config/feature_extraction/config_extract_features.yaml.

PyRadiomics parameter files

When using radiomics-based feature types, you may omit both keys to use bundled presets (parameter.yaml for non-habitat, parameter_habitat.yaml for habitat maps). Override with repo paths or custom YAML when needed:

# Optional — omit both for bundled defaults
# params_file_of_non_habitat: ./config/radiomics/parameter.yaml
# params_file_of_habitat: ./config/radiomics/parameter_habitat.yaml

PyRadiomics starter YAMLs (copy or reference by path):

• config/radiomics/parameter_basic.yaml — Original only, ~70 features
• config/radiomics/parameter_with_filters.yaml — + LoG + Wavelet, ~1500 features

When not using radiomics types, omit params_file_of_* entirely (no placeholder needed).

Standard config

# params_file_of_* omitted → bundled presets
raw_img_folder: ./data/preprocessed_images
habitats_map_folder: ./results/habitat_analysis
out_dir: ./results/features

n_processes: 4
habitat_pattern: '*_habitats_remapped.nrrd'

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

n_habitats:           # leave empty = auto-detect
debug: false

Reference templates

Config index: skills/CONFIG_SOURCES.md.

File	Use
config/feature_extraction/config_extract_features.yaml	scaffold
config/feature_extraction/config_extract_features.yaml	full publication setup
config/feature_extraction/config_extract_features.yaml	quick path, no PyRadiomics
config/radiomics/parameter_basic.yaml	minimal PyRadiomics params
config/radiomics/parameter_with_filters.yaml	full PyRadiomics with LoG+Wavelet

Full annotated reference: config/feature_extraction/config_extract_features.yaml.

Voxel-based GLCM defaults (voxel_radiomics only)

Voxel radiomics uses local neighborhoods (kernel_radius=3 → 7×7×7 for CT R3B12 preset; kernel_radius=1 → 3×3×3). Many voxels produce degenerate GLCM matrices (flat patches). If params_file enables glcm: without listing feature names, PyRadiomics computes all 24 GLCM features; MCC, Imc1, Imc2 then fail (CUDA/MKL eigvals crash or NaN).

HABIT behavior: when glcm is unrestricted, substitute the 21 stable features from config/radiomics/params_voxel_radiomics.yaml and log a warning. Explicit feature lists in params_file are respected (unsafe names get a warning only).

Recommended: point params_file at config/radiomics/params_voxel_radiomics.yaml. Do not reuse whole-tumor parameter.yaml with bare glcm: for voxel mode.

Voxel batch size (voxel_batch)

feature_construction.voxel_level.params.voxel_batch controls how many ROI voxels PyRadiomics processes per batch during voxel_radiomics. Habit default is 1000. Use -1 to process all ROI voxels at once (PyRadiomics native, no batching). For large ROIs or GPU/torch paths, users may set a lower positive value (e.g. 512) to cap peak memory. These params are forwarded even when omitted from the method expression string.

TorchRadiomics acceleration (use_torch_radiomics)

Optional in-tree TorchRadiomics injection is controlled by use_torch_radiomics:

• auto (default): use torch+CUDA when available, else CPU PyRadiomics
• true: require torch (fail if missing)
• false: always CPU PyRadiomics

Related params: torch_device (auto, cuda:0, cpu), torch_dtype (default float32; use float64 for CPU parity). Torch is not a core habit dependency.

Validate output (MANDATORY after run)

python skills/habit-feature-extraction/scripts/inspect_feature_csv.py <out_dir>/whole_habitat_radiomics.csv \
  --subject-id-col subject_id --label-col label

Checks for duplicate subject IDs, all-NaN columns, constant features, non-numeric features, label binarity.

Output structure

out_dir/
├── raw_image_radiomics.csv          # if 'traditional'
├── habitat_basic_features.csv       # if 'non_radiomics'
├── whole_habitat_radiomics.csv      # if 'whole_habitat'
├── each_habitat_radiomics.csv       # if 'each_habitat'
├── msi_features.csv                 # if 'msi'
├── ith_scores.csv                   # if 'ith_score'
└── extract_features.log

Each CSV has subject IDs in the first column, features in the rest. Direct input for habit model.

Common pitfalls

1. habitat_pattern mismatch → check actual file names. Use *_habitats.nrrd for one_step output.
2. Missing PyRadiomics params → fail fast; tell user which features need params.
3. each_habitat produces 5×N features for 5 habitats → can balloon to 1000+.
4. Subject ID mismatch between raw_img_folder and habitats_map_folder → all subjects must exist in both.
5. MSI/ITH require habitat maps but no PyRadiomics — fastest path for users without PyRadiomics.

For specific errors, see habit-troubleshoot/references/errors_extraction.md.

Next step

To combine feature CSVs with clinical data into a single ML input file:

habit merge-csv f1.csv f2.csv clinical.csv -o ml_input.csv --index-col subject_id

Then proceed to habit-machine-learning.