nirs4all.analysis.results module

Transfer Selection Result Classes.

This module provides dataclasses for storing and visualizing transfer preprocessing selection results.

Supports both object-based and string-based preprocessing definitions.

Classes:

TransferResult: Result from evaluating a single preprocessing. TransferSelectionResults: Full results from selection process with

ranking, visualization, and export methods.

class nirs4all.analysis.results.TransferResult(name: str, pipeline_type: str, components: list[str], transfer_score: float, metrics: dict[str, float], improvement_pct: float, signal_score: float | None = None, transforms: list[Any] | None = None)

Bases: object

Result from evaluating a single preprocessing for transfer.

Variables:

• name (str) – Pipeline display name (e.g., ‘StandardNormalVariate>FirstDerivative’).

• pipeline_type (str) – Type of pipeline (‘single’, ‘stacked’, or ‘augmented’).

• components (list[str]) – List of component names (e.g., [‘StandardNormalVariate’, ‘FirstDerivative’]).

• transfer_score (float) – Combined transfer metric score (higher is better).

• metrics (dict[str, float]) – Dictionary of individual metric values.

• improvement_pct (float) – Percentage improvement over raw baseline.

• signal_score (float | None) – Optional supervised validation score (Stage 4).

• transforms (list[Any] | None) – Optional list of actual transformer objects (for object-based results).

__post_init__()

Validate fields after initialization.

components: list[str]

get_transforms(preprocessings: dict[str, Any] | None = None) → list[Any]

Get the transformer objects for this result.

If transforms are already stored, returns them directly. Otherwise, resolves component names from the preprocessings dict.

Parameters:

preprocessings – Optional name->object mapping for resolution.

Returns:

List of transformer instances.

improvement_pct: float

metrics: dict[str, float]

name: str

pipeline_type: str

signal_score: float | None = None

to_dict() → dict[str, Any]

Convert to dictionary representation.

transfer_score: float

transforms: list[Any] | None = None

class nirs4all.analysis.results.TransferSelectionResults(ranking: list[~nirs4all.analysis.results.TransferResult], raw_metrics: dict[str, float], timing: dict[str, float] = <factory>)

Bases: object

Full results from transfer preprocessing selection.

Provides access to ranked recommendations, timing information, and various output formats for integration with nirs4all pipelines.

Variables:

• ranking (list[nirs4all.analysis.results.TransferResult]) – List of TransferResult sorted by transfer_score (best first).

• raw_metrics (dict[str, float]) – Baseline metrics computed on raw (unprocessed) data.

• timing (dict[str, float]) – Dictionary of execution time per stage.

property best: TransferResult

Get the best recommendation.

Returns:

TransferResult with highest transfer score.

Raises:

ValueError – If no results are available.

plot_improvement_heatmap(top_k: int = 15, figsize: tuple[int, int] = (12, 10))

Plot heatmap of metric improvements vs raw data.

Parameters:

• top_k – Number of top results to display.

• figsize – Figure size as (width, height).

Returns:

matplotlib Figure object.

plot_metrics_comparison(top_k: int = 10, metrics: list[str] | None = None, figsize: tuple[int, int] = (16, 10))

Plot comparison of all metrics for top-K preprocessings.

Parameters:

• top_k – Number of top results to display.

• metrics – Specific metrics to plot. Default: all available.

• figsize – Figure size as (width, height).

Returns:

matplotlib Figure object.

plot_ranking(top_k: int = 15, show_signal_score: bool = True, figsize: tuple[int, int] = (14, 8))

Plot ranked bar chart of preprocessing recommendations.

Parameters:

• top_k – Number of top results to display.

• show_signal_score – Include signal score if available.

• figsize – Figure size as (width, height).

Returns:

matplotlib Figure object.

ranking: list[TransferResult]

raw_metrics: dict[str, float]

summary(top_k: int = 5) → str

Generate human-readable summary.

Parameters:

top_k – Number of top results to include in summary.

Returns:

Formatted summary string.

timing: dict[str, float]

to_dataframe()

Convert results to pandas DataFrame.

Returns:

DataFrame with columns for name, type, scores, and metrics.

Raises:

ImportError – If pandas is not available.

to_pipeline_spec(top_k: int = 1, use_augmentation: bool = False) → str | list[str] | dict[str, list[str]]

Convert results to nirs4all pipeline specification.

Parameters:

• top_k – Number of top recommendations to include.

• use_augmentation – If True and top_k > 1, return augmentation spec.

Returns:

• Single string for top_k=1: “snv>d1”

• List for multiple without augmentation: [“snv”, “d1”]

• Dict for augmentation: {“feature_augmentation”: [“snv”, “d1>msc”]}

Return type:

Pipeline specification usable in nirs4all

Example

>>> results.to_pipeline_spec()
'snv'
>>> results.to_pipeline_spec(top_k=3, use_augmentation=True)
{'feature_augmentation': ['snv', 'd1', 'msc']}

to_preprocessing_list(top_k: int = 10, preprocessings: dict[str, Any] | None = None) → list[list[Any]]

Convert top-K results to a list of preprocessing transform pipelines.

Each result is converted to a list of transformer instances that can be directly used in nirs4all pipeline’s feature_augmentation.

Parameters:

• top_k – Number of top results to convert.

• preprocessings – Optional dict mapping names to transformers. Uses get_base_preprocessings() if not provided. Not needed if results already store transform objects.

Returns:

List of preprocessing pipelines, where each pipeline is a list of transformer instances. For stacked pipelines like SNV>D1, returns [[SNV(), D1()], …].

Example

>>> results = selector.fit(X_train, X_test)
>>> pp_list = results.to_preprocessing_list(top_k=5)
>>> # pp_list = [[SNV()], [MSC()], [SNV(), D1()], ...]
>>>
>>> # Use in pipeline:
>>> pipeline = [
...     {"feature_augmentation": {"_or_": pp_list, "pick": 1}},
...     {"model": PLSRegression()},
... ]

top_k(k: int = 5) → list[TransferResult]

Get top-K recommendations.

Parameters:

k – Number of top results to return.

Returns:

List of top-K TransferResult objects.