MLSpec

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class MLSpec(name: str, classifier: Spec, pre_preprocessing_feature_selectors: Tuple[Spec, ...] = (), table_preprocessors: Tuple[Spec, ...] = (), feature_selectors: Tuple[Spec, ...] = (), metrics: Tuple[Spec, ...] = (), random_seed: int | None = None, version: str = '1.0', steps: Tuple[Spec, ...] = ())[source]

Bases: object

Complete specification of a tabular machine-learning analysis.

A frozen, fingerprintable value object describing ONE modelling definition: an ordered chain of table steps (preprocessors and feature selectors, interleaved however the design calls for), exactly one terminal classifier, and the evaluation metric panel. It deliberately does NOT describe the validation design (split counts, resampling, id files) – those are choices of the calling recipe, not of the model definition.

Step order lives in one ordered list. steps is the pipeline: position N of the list is step N of the fit. The three fields pre_preprocessing_feature_selectors, table_preprocessors and feature_selectors are the DEPRECATED predecessor of that list – they expressed order through three fixed slots, which allowed a selector to sit only before all preprocessing or after all of it. Declaring any of them still works for the whole of v1.x: the three are concatenated in their documented order (pre -> preprocessors -> post) into steps, with a DeprecationWarning. Declaring both layouts at once is an error – which of the two is the pipeline would be a guess.

Which layout a spec serialises in. to_dict() emits the three deprecated keys for a spec declared with them, and the single steps key for a spec declared with steps. That asymmetry is deliberate and load-bearing: every provenance record and golden baseline HABIT has ever written hashes this payload, so unconditionally adding a steps key would move the fingerprint of every analysis already published. A spec with no table steps at all serialises in the deprecated shape for the same reason.

name

Human-readable specification name.

Type:: str

classifier

Spec of the terminal classifier.

Type:: habit.spec.specs.Spec

pre_preprocessing_feature_selectors

DEPRECATED. Ordered specs of the selection chain fitted on the RAW training table, BEFORE any preprocessing (v0.1’s before_z_score: true selectors). The stage exists because some selection statistics are distorted by normalisation – after z-scoring every feature variance is 1.0, so variance-based selection only carries information on the raw table. Use steps and put the selector before the preprocessor instead.

Type:: Tuple[habit.spec.specs.Spec, …]

table_preprocessors

DEPRECATED. Ordered specs of the stateful preprocessing chain fitted on the TRAINING rows and replayed afterwards (v0.1’s normalization). Use steps.

Type:: Tuple[habit.spec.specs.Spec, …]

feature_selectors

DEPRECATED. Ordered specs of the selection chain, fitted after preprocessing (v0.1’s feature_selection_methods entries without before_z_score). Use steps.

Type:: Tuple[habit.spec.specs.Spec, …]

metrics

Specs of the evaluation metric panel. An empty tuple asks the calling recipe for its default panel.

Type:: Tuple[habit.spec.specs.Spec, …]

random_seed

Seed applied to every Seedable component. Seeds change the scientific result, so they live in the spec (and its fingerprint), not in the run policy.

Type:: int | None

version

Specification schema version.

Type:: str

steps

The ordered table-step chain – preprocessors and feature selectors in the exact order they are fitted. Names are resolved across both registries by habit.pipeline.assembly.build_table_pipeline(); the spec layer records the order and stays registry-free. Declared last among the fields purely so that existing positional construction keeps meaning what it meant.

Type:: Tuple[habit.spec.specs.Spec, …]

__post_init__() → None[source]

Coerce payloads into Specs, and fold deprecated chains into steps.

Raises:: HABITAPIError – On a missing/mistyped name or classifier, a chain entry that is not a Spec, or a spec that declares both steps and any deprecated chain.

property declares_deprecated_chains: bool

Report whether this spec was declared through the deprecated chains.

Derived from the fields alone (never from hidden construction state) so that two equal specs always agree on it – and therefore always serialise identically. A spec with no table steps at all counts as deprecated-shaped, which is what keeps its payload byte-identical to every one written before steps existed.

Returns:: True when to_dict() emits the three deprecated chain keys, False when it emits the single steps key.
Return type:: bool

describe_methods(style: str = 'radiology') → str[source]

Render the specification as a manuscript methods paragraph.

Same verb, signature, and vocabulary as HabitatSpec.describe_methods(); this describes what was INTENDED and can be read before anything runs.

Parameters:: style – Target venue convention. "radiology" opens with the design sentence; "nature" closes with it.
Returns:: English prose describing every configured step and its parameters.
Raises:: HABITAPIError – On an unknown style.

fingerprint() → str[source]: Return a stable hash identifying this exact specification.

to_dict() → Dict[str, Any][source]

Serialise to a plain dict (YAML isomorphic).

Emits exactly ONE of the two table-step layouts – see the class docstring for why the choice is asymmetric rather than always writing both.

Returns:: The payload, with either the three deprecated chain keys or the single steps key, never both.
Return type:: Dict[str, Any]

classmethod from_dict(payload: Mapping[str, Any]) → MLSpec[source]

Rebuild a machine-learning specification from its dict form.

Reads whichever table-step layout the payload carries. A payload that carries both is rejected rather than resolved by precedence: picking one would silently drop half of a hand-written document’s pipeline.

Parameters:: payload – Mapping as produced by to_dict(), or a hand-written v1 spec section.
Returns:: The reconstructed specification.
Raises:: HABITAPIError – If the classifier component is missing, or the payload declares both steps and a deprecated chain.

__init__(name: str, classifier: Spec, pre_preprocessing_feature_selectors: Tuple[Spec, ...] = (), table_preprocessors: Tuple[Spec, ...] = (), feature_selectors: Tuple[Spec, ...] = (), metrics: Tuple[Spec, ...] = (), random_seed: int | None = None, version: str = '1.0', steps: Tuple[Spec, ...] = ()) → None