Core Concepts and Mental Model

Establish a shared vocabulary before reading HABIT’s implementation. The following terms are used throughout the developer documentation.

Global mental model

HABIT connects domain concepts to engineering roles through a configuration pipeline:

        flowchart TD
  V["Voxel feature"] --> SV["Supervoxel"] --> H["Habitat"]
  H --> F["Habitat feature"] --> M["Machine-learning model"]
  C["Configurator"] --> O["Orchestrator"]
  R["Registry"] --> O
  K["Contract"] -.-> O
  O --> V

Domain concepts

Term	Meaning
Voxel	The smallest unit of a 3D medical image. Habitat analysis starts with voxel-level features.
Voxel feature	A feature vector calculated for each voxel, such as raw intensity, kinetic measurements, or local radiomics.
Supervoxel	A local group of similar voxels within one subject, used as an intermediate product by the `two_step` strategy.
Habitat	An image-phenotype region inside a tumor, represented by an integer label image.
Habitat feature	A downstream feature calculated after habitat maps are generated, such as radiomics, MSI, or ITH.
Clustering mode	One of `two_step`, `one_step`, or `direct_pooling`.

Engineering roles

Role	Responsibility	Representative symbol
Config / Schema	Typed representation of configuration and its validation rules.	`BaseConfig`, `MLConfig`
Configurator	Assembles validated configuration into an executable object; it does not execute the workflow.	`MLConfigurator`
Orchestrator	Executes a complete workflow through `run()` or `fit()`/`predict()`.	`BatchProcessor`, `HabitatAnalysis`
Registry / Factory	Maps names to classes or functions and creates the selected algorithm.	`ModelFactory`, `PreprocessorFactory`
Contract	Shared interface rules protected by architecture tests.	`ClassRegistry`, `ORCHESTRATOR_CONTRACT`

Tip

Remember the three most easily confused roles: Configurator assembles, Orchestrator executes, and Registry resolves names into objects.

Workflow and Runner

The machine-learning subsystem separates orchestration from execution:

Workflow, such as HoldoutWorkflow, decides what should happen: orchestration, data splitting, and result organization.
Runner, such as HoldoutRunner, decides how it happens: concrete training and inference operations.

This separation allows the two concerns to evolve and be tested independently.

Configuration to execution

Every subsystem follows the same high-level chain:

        flowchart LR
  Y["Configuration"] --> S["Schema<br/>validate"]
  S --> C["Configurator<br/>assemble"]
  C --> O["Orchestrator<br/>execute"]
  R["Registry"] -.->|create by name| O

See Complete Request Lifecycle for a command-level walkthrough and Code Map for the implementation locations.