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.

name

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

Type:

str

pipeline_type

Type of pipeline (‘single’, ‘stacked’, or ‘augmented’).

Type:

str

components

List of component names (e.g., [‘StandardNormalVariate’, ‘FirstDerivative’]).

Type:

List[str]

transfer_score

Combined transfer metric score (higher is better).

Type:

float

metrics

Dictionary of individual metric values.

Type:

Dict[str, float]

improvement_pct

Percentage improvement over raw baseline.

Type:

float

signal_score

Optional supervised validation score (Stage 4).

Type:

float | None

transforms

Optional list of actual transformer objects (for object-based results).

Type:

List[Any] | None

__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: ~typing.List[~nirs4all.analysis.results.TransferResult], raw_metrics: ~typing.Dict[str, float], timing: ~typing.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.

ranking

List of TransferResult sorted by transfer_score (best first).

Type:

List[nirs4all.analysis.results.TransferResult]

raw_metrics

Baseline metrics computed on raw (unprocessed) data.

Type:

Dict[str, float]

timing

Dictionary of execution time per stage.

Type:

Dict[str, float]

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.