nirs4all.pipeline.analysis.topology module

Pipeline topology analyzer.

Inspects an expanded pipeline configuration and identifies its structural properties (branching, merging, stacking, separation, model placement, etc.).

The topology descriptor is used by: - The refit mechanism to dispatch to the appropriate strategy

(simple, stacking, nested, separation).

  • The caching layer for shared-prefix detection across pipeline variants.

Example

>>> from nirs4all.pipeline.analysis.topology import analyze_topology
>>> steps = [
...     {"class": "sklearn.preprocessing.MinMaxScaler"},
...     {"class": "sklearn.model_selection.KFold", "params": {"n_splits": 5}},
...     {"model": {"class": "sklearn.cross_decomposition.PLSRegression", "params": {"n_components": 10}}},
... ]
>>> topo = analyze_topology(steps)
>>> topo.has_stacking
False
>>> len(topo.model_nodes)
1
class nirs4all.pipeline.analysis.topology.ModelNodeInfo(model_class: str, branch_path: list[int], step_index: int, merge_type: str | None, branch_depth: int)[source]

Bases: object

Describes a single model node found in the pipeline.

Variables:

  • model_class (str) – Fully qualified or short class name of the model.

  • branch_path (list[int]) – Branch indices leading to this model (empty for top-level).

  • step_index (int) – Position of this model in the step list at its nesting level.

  • merge_type (str | None) – Merge type that follows this model’s branch (if any).

  • branch_depth (int) – How many branch levels deep this model sits.

branch_depth: int
branch_path: list[int]
merge_type: str | None
model_class: str
step_index: int
class nirs4all.pipeline.analysis.topology.PipelineTopology(has_stacking: bool = False, has_feature_merge: bool = False, has_mixed_merge: bool = False, has_concat_merge: bool = False, has_separation_branch: bool = False, has_branches_without_merge: bool = False, max_stacking_depth: int = 0, model_nodes: list[ModelNodeInfo] = <factory>, splitter_step_index: int | None = None, has_sequential_models: bool = False, has_multi_source: bool = False)[source]

Bases: object

Structural descriptor of an expanded pipeline configuration.

Variables:

  • has_stacking (bool) – True if merge: "predictions" is present.

  • has_feature_merge (bool) – True if merge: "features" is present.

  • has_mixed_merge (bool) – True if a merge step combines both features and predictions (e.g. merge: {"features": ..., "predictions": ...}).

  • has_concat_merge (bool) – True if merge: "concat" is present.

  • has_separation_branch (bool) – True if any branch uses by_metadata, by_tag, by_source, or by_filter.

  • has_branches_without_merge (bool) – True if a duplication branch is not followed by a merge step at the same nesting level.

  • max_stacking_depth (int) – Deepest nesting of merge: "predictions" (1 for flat stacking, 2+ for nested stacking, 0 if no stacking).

  • model_nodes (list[nirs4all.pipeline.analysis.topology.ModelNodeInfo]) – All model nodes discovered, with location metadata.

  • splitter_step_index (int | None) – Index of the first CV splitter step (0-based), or None if no splitter is found.

  • has_sequential_models (bool) – True if multiple model steps exist at the same nesting level without intervening branch/merge steps.

  • has_multi_source (bool) – True if a by_source branch is present.

has_branches_without_merge: bool = False
has_concat_merge: bool = False
has_feature_merge: bool = False
has_mixed_merge: bool = False
has_multi_source: bool = False
has_separation_branch: bool = False
has_sequential_models: bool = False
has_stacking: bool = False
max_stacking_depth: int = 0
model_nodes: list[ModelNodeInfo]
splitter_step_index: int | None = None
nirs4all.pipeline.analysis.topology.analyze_topology(steps: list[Any]) → PipelineTopology[source]

Walk an expanded pipeline step list and produce a topology descriptor.

The function handles nested branch/merge structures recursively, tracking branch paths, merge types, and model positions.

Parameters:

steps – List of expanded pipeline steps (dicts, serialized components, or direct operator instances).

Returns:

A PipelineTopology describing the structural properties of the pipeline.