nirs4all.api.result module

Result classes for nirs4all API.

These dataclasses wrap the outputs from pipeline execution, prediction, and explanation operations, providing convenient accessor methods.

Classes:

RunResult: Result from nirs4all.run() PredictResult: Result from nirs4all.predict() ExplainResult: Result from nirs4all.explain()

Phase 1 Implementation (v0.6.0):

  • RunResult: Full implementation with best, best_score, top(), export()

  • PredictResult: Full implementation with values, to_dataframe()

  • ExplainResult: Full implementation with values, feature attributions

class nirs4all.api.result.LazyModelRefitResult(model_name: str, selection: PerModelSelection, refit_config: RefitConfig, dataset: Any, context: Any, runtime_context: Any, artifact_registry: Any, executor: Any, prediction_store: Any)[source]

Bases: object

Lazy per-model refit result that triggers refit on first access.

Wraps a PerModelSelection and defers the actual refit execution until a property requiring the result (e.g. .score, .final_entry, .export()) is accessed.

After the first access, the result is cached so subsequent accesses return instantly.

If the underlying resources (artifact registry, step cache) have been destroyed by the time of access, the lazy refit re-executes from scratch.

Variables:

  • model_name – Name of the model.

  • selection – The PerModelSelection metadata from the CV phase.

property cv_entry: dict[str, Any]

Get the best CV prediction entry.

property cv_score: float | None

Get the best CV validation score (does not trigger refit).

property final_entry: dict[str, Any]

Get the refit prediction entry (triggers refit on first access).

property final_score: float | None

Get the refit model’s test score (triggers refit on first access).

property is_resolved: bool

Check if the refit has already been executed.

property metric: str

Get the metric name (does not trigger refit).

property score: float | None

Get the refit model’s test score (triggers refit on first access).

class nirs4all.api.result.ModelRefitResult(model_name: str = '', final_entry: dict[str, ~typing.Any]=<factory>, cv_entry: dict[str, ~typing.Any]=<factory>, final_score: float | None = None, cv_score: float | None = None, metric: str = '')[source]

Bases: object

Per-model refit result metadata.

Captures the refit outcome for a single model node in the pipeline. For Phase 2 (non-stacking), there is only one model node, so RunResult.models will contain exactly one entry.

Variables:

  • model_name (str) – Name of the model (e.g. "PLSRegression").

  • final_entry (dict[str, Any]) – The refit prediction entry (fold_id="final").

  • cv_entry (dict[str, Any]) – The best CV prediction entry for this model.

  • final_score (float | None) – Test score from the refit model.

  • cv_score (float | None) – Best validation score from CV.

  • metric (str) – Metric name used for evaluation.

cv_entry: dict[str, Any]
cv_score: float | None = None
final_entry: dict[str, Any]
final_score: float | None = None
metric: str = ''
model_name: str = ''
nirs4all.api.result.load_workspace_predict_result(workspace_path: str | Path, prediction_id: str) → PredictResult[source]

Load a workspace prediction row as a public PredictResult.

This is the direct one-record public API for the existing Predictions(...).get_predict_result_by_id(...) bridge. It loads arrays from the workspace so intervals, provenance metadata, executable X or spectra evidence, sample ids and model metadata can flow through PredictResult.from_prediction_record() without callers depending on the lower-level Predictions buffer API.

Parameters:

  • workspace_path – nirs4all workspace directory.

  • prediction_id – Stored prediction identifier.

Returns:

Native PredictResult converted from the stored prediction record.

Raises:

  • KeyError – If the prediction id is not present in the workspace.

  • ValueError – If the stored record was not loadable with prediction arrays, propagated from PredictResult.from_prediction_record.

nirs4all.api.result.load_workspace_predict_results(workspace_path: str | Path, *, dataset_name: str | None = None) → list[PredictResult][source]

Load workspace prediction rows as public PredictResult objects.

This is the bulk public API for the existing Predictions(...).to_predict_results() bridge. It opens the workspace with arrays and returns native prediction containers that preserve intervals, sample ids, model metadata and replay provenance.

Parameters:

  • workspace_path – nirs4all workspace directory.

  • dataset_name – Optional dataset filter applied by the workspace query.

Returns:

List of native PredictResult objects in workspace query order.

Raises:

ValueError – If any stored record cannot be converted because its arrays are unavailable or incomplete.

nirs4all.api.result.save_workspace_predict_result(workspace_path: str | Path, result: PredictResult, *, dataset_name: str = 'prediction_dataset', metadata: Mapping[str, Any] | None = None, result_metadata: Mapping[str, Any] | None = None, X: Any | None = None, spectra: Any | None = None, sample_indices: Any | None = None, model_name: str | None = None, model_classname: str = '', pipeline_id: str | None = None, chain_id: str | None = None, partition: str = 'prediction', metric: str = '', task_type: str = 'regression', n_features: int | None = None, preprocessings: str | Sequence[str] | None = None) → str[source]

Persist a public PredictResult as a workspace prediction row.

This is the high-level Python publisher for the workspace/store → PredictResult bridge. It writes prediction values and optional row-aligned executable X/spectra evidence through Predictions.add_prediction(...) so downstream helpers such as load_workspace_predict_result(...) and robustness_from_workspace_prediction(...) can reload the same evidence without callers manipulating the lower-level Predictions facade.

Conformal calibration artifacts and interval guarantees remain owned by save_workspace_calibrated_result(...); this helper publishes prediction rows plus replay evidence/provenance.

Parameters:

  • workspace_path – nirs4all workspace directory.

  • result – Prediction result to persist.

  • dataset_name – Dataset label for the prediction row.

  • metadata – Optional per-sample/sample-level metadata stored in the array sidecar as sample_metadata.

  • result_metadata – Optional result-level metadata merged over result.metadata after removing executable arrays.

  • X – Optional row-aligned feature matrix for spectral/OOD replay.

  • spectra – Optional row-aligned spectra matrix for spectral/OOD replay.

  • sample_indices – Optional row indices. Defaults to result.sample_indices.

  • model_name – Optional model label. Defaults to result.model_name.

  • model_classname – Optional fully qualified model class name.

  • pipeline_id – Optional workspace pipeline id.

  • chain_id – Optional workspace chain id.

  • partition – Prediction partition label.

  • metric – Optional metric name.

  • task_type – Prediction task type.

  • n_features – Optional feature count. Inferred from X or spectra when omitted.

  • preprocessings – Optional preprocessing summary. Defaults to the PredictResult.preprocessing_steps JSON list.

Returns:

Stored workspace prediction id.

Raises:

TypeError – If result is not a PredictResult.