nirs4all.api.predict module

Module-level predict() function for nirs4all.

This module provides a simple interface for making predictions with trained nirs4all models. It wraps PipelineRunner.predict() with ergonomic defaults.

Example

>>> import nirs4all
>>> result = nirs4all.predict(
...     model="exports/best_model.n4a",
...     data=X_new,
...     verbose=1
... )
>>> print(f"Predictions shape: {result.shape}")
nirs4all.api.predict.predict(model: Dict[str, Any] | str | Path, data: str | Path | ndarray | Tuple[ndarray, ...] | Dict[str, Any] | SpectroDataset | DatasetConfigs, *, name: str = 'prediction_dataset', all_predictions: bool = False, session: Session | None = None, verbose: int = 0, **runner_kwargs: Any) → PredictResult[source]

Make predictions with a trained model on new data.

This function provides a simple interface for running inference with trained nirs4all pipelines. The model can be specified as a prediction dict from a previous run, or as a path to an exported bundle.

Parameters:

  • model – Trained model specification. Can be: - Prediction dict from result.best or result.top() - Path to exported bundle: "exports/model.n4a" - Path to pipeline config directory

  • data – Data to predict on. Can be: - Path to data folder: "new_data/" - Numpy array: X_new (n_samples, n_features) - Tuple: (X,) or (X, y) for evaluation - Dict: {"X": X, "metadata": meta} - SpectroDataset instance

  • name – Name for the prediction dataset (for logging). Default: “prediction_dataset”

  • all_predictions – If True, return predictions from all folds. If False (default), return single aggregated prediction.

  • session – Optional Session for resource reuse. If provided, uses the session’s runner.

  • verbose – Verbosity level (0=quiet, 1=info, 2=debug). Default: 0

  • **runner_kwargs – Additional PipelineRunner parameters. Common options: workspace_path, plots_visible

Returns:

  • y_pred: Predicted values array (n_samples,)

    • metadata: Additional prediction metadata

    • model_name: Name of the model used

    • preprocessing_steps: List of preprocessing steps applied

Use result.to_dataframe() for pandas DataFrame output.

Return type:

PredictResult containing

Raises:

Examples

Predict from an exported bundle:

>>> import nirs4all
>>>
>>> result = nirs4all.predict(
...     model="exports/wheat_model.n4a",
...     data=X_new
... )
>>> print(f"Predictions: {result.values[:5]}")

Predict using a result from a previous run:

>>> # Training
>>> train_result = nirs4all.run(pipeline, train_data)
>>>
>>> # Prediction with best model
>>> pred_result = nirs4all.predict(
...     model=train_result.best,
...     data=X_test
... )

Get all fold predictions:

>>> result = nirs4all.predict(
...     model="exports/model.n4a",
...     data=X_new,
...     all_predictions=True
... )
>>> print(f"Shape: {result.shape}")

Convert to DataFrame:

>>> result = nirs4all.predict(model, data)
>>> df = result.to_dataframe()
>>> df.to_csv("predictions.csv")

See also