Code Map

This page helps you locate code quickly: it describes the repository layout, the responsibilities of habit/ subpackages, and where to start when changing a particular feature.

Repository root

Path	Contents
habit/	Main Python package containing the application code.
config/	Example and production YAML configurations organized by subsystem.
demo_data/	Demo data and generated artifacts, including images and ML tables.
launchers/	Windows lightweight-release entry points for installation, optional profiles, and the configured HABIT command prompt.
tools/bin/	Versioned third-party runtime executables used by the lightweight release.
tests/	Pytest tests and executable demo scripts (see Contributor Workflow).
docs/	Documentation; Sphinx sources are under docs/source/.
habit-gui/	Optional standalone Web GUI (FastAPI + React + bridge), not checked out by default. See .gitignore; habit gui searches for a sibling habit-gui/ or bundled habit/_gui_bundle.
pyproject.toml	Build metadata and entry-point definitions (habit = "habit.cli:cli").

habit/ package structure

        flowchart TD
  ROOT["habit/"]
  ROOT --> CLI["cli.py — Click command group"]
  ROOT --> CMD["commands/ — cmd_*.py (active CLI impl)"]
  ROOT --> CORE["core/ — business logic"]
  ROOT --> UTILS["utils/ — shared utilities"]

  CORE --> COM["common/ — configs, configurators, contracts"]
  CORE --> SCH["schemas/ — workflow & step schemas, registry, reflect"]
  CORE --> PRE["preprocessing/"]
  CORE --> HAB["habitat_analysis/"]
  CORE --> MLC["machine_learning/"]
  CORE --> DCM["dicom_sort/"]

  COM --> CFG["configs/"]
  COM --> CON["configurators/"]
  COM --> REG["registry.py"]
  COM --> ORC["orchestrator.py"]
    

Top-level package responsibilities

Package	Responsibility
habit/cli.py	Click root command group; subcommands are declared here and command bodies only perform lazy imports and forwarding.
habit/commands/	Active command implementation layer: each cmd_*.py loads configuration, calls the core, and reports results. Shared helpers are in common.py.
habit/core/common/	Cross-domain infrastructure: YAML loading and path resolution (configs/), the Configurator base classes (configurators/), the shared registry base (registry.py → ClassRegistry), and the orchestrator contract table (orchestrator.py → ORCHESTRATOR_CONTRACT).
habit/core/schemas/	Pydantic configuration models for workflows, step parameters, parameter registration, validation, and GUI reflection.
habit/core/preprocessing/	Batch image preprocessing: BatchProcessor, BasePreprocessor, PreprocessorFactory, and step implementations.
habit/core/habitat_analysis/	Habitat segmentation, clustering features, post-segmentation feature extraction, and traditional radiomics (see Subsystems).
habit/core/machine_learning/	Tabular machine learning: data assembly, feature selection, modeling, evaluation, reporting, visualization, and statistical tests.
habit/core/dicom_sort/	Standalone DICOM sorting based on dcm2niix; it does not use BatchProcessor.
habit/utils/	Shared utilities used across subsystems (see below).

Shared utilities: habit/utils/

By convention, reusable cross-subsystem utilities live here. All progress bars must use progress_utils.py. Common modules include:

File	Purpose
progress_utils.py	Shared progress bars (the package standard; do not create local tqdm wrappers).
yaml_utils.py	YAML read/write helpers.
log_utils.py	Logging and LoggerManager / setup_logger.
io_utils.py / file_system_utils.py	Image/mask path discovery and Windows/WSL path conversion.
parallel_utils.py / parallel_gpu_utils.py	General parallel execution and GPU slot allocation for torch radiomics.
visualization_utils.py / font_config.py	Plotting and font configuration (plot text must be English).
habitats_results_io.py / habitat_postprocess_utils.py	Habitat result I/O and post-processing.
radiomics_params_utils.py / torch_radiomics_utils.py	Radiomics parameters and helpers.
job_cancel.py	Cancellation detection for long-running tasks and the GUI.

Cross-subsystem contract files

The following files define package-wide interface contracts. Update them and run the contract tests when adding a factory or orchestrator:

        flowchart LR
  REG["common/registry.py<br/>ClassRegistry"] --> PF["PreprocessorFactory"]
  REG --> MF["ModelFactory"]
  REG --> CF["ClusteringAlgorithmFactory"]
  REG --> EF["FeatureExtractorRegistry"]
  REG --> PP["PreprocessingMethodFactory"]
  REG --> HF["HabitatFeatureFactory"]

  ORC["common/orchestrator.py<br/>ORCHESTRATOR_CONTRACT"] --> BP["BatchProcessor"]
  ORC --> HA["HabitatAnalysis"]
  ORC --> HW["HoldoutWorkflow / ..."]

  TST["tests/test_architecture_contracts.py"] -.-> REG
  TST -.-> ORC
    

Where to start when changing X

Goal	Starting point
Add or modify a CLI command	habit/cli.py + habit/commands/cmd_*.py
Add a preprocessing step	habit/core/preprocessing/ + PreprocessorFactory
Add a clustering algorithm	habit/core/habitat_analysis/clustering/base_clustering.py
Add a clustering feature extractor	habit/core/habitat_analysis/clustering_features/base_extractor.py
Add a machine-learning model	habit/core/machine_learning/models/factory.py
Add a feature-selection method	habit/core/machine_learning/feature_selectors/selector_registry.py
Change configuration fields or validation rules	habit/core/schemas/workflows/ and schemas/steps/
Change the three habitat pipeline strategies	habit/core/habitat_analysis/habitat_analysis.py（_PIPELINE_RECIPES）+ pipelines/steps/
Change the ML training or prediction flow	habit/core/machine_learning/workflows/ and runners/
Add a class-based factory	Subclass ClassRegistry from habit/core/common/registry.py; follow an existing factory in the same domain.
Add a top-level orchestrator for a new CLI pipeline	Implement the class and update ORCHESTRATOR_CONTRACT in common/orchestrator.py. tests/test_architecture_contracts.py reads this table automatically to validate terminal methods.

See also

See Extension and Plugin Guide for the complete extension and registration reference, and Customization and Extension Guide for implementation templates.