NIRS4ALL

A comprehensive Python library for Near-Infrared Spectroscopy data analysis

Documentation • Installation • Quick Start • Examples • Contributing

Which nirs4all do you need?

nirs4all comes in two flavors — pick the one that fits your workflow:

Not sure? If you've never written Python code, start with nirs4all Studio. It uses this library under the hood and gives you all the same capabilities through a graphical interface.

Overview

NIRS4ALL bridges the gap between spectroscopic data and machine learning by providing a unified framework for data loading, preprocessing, model training, and evaluation. Built for researchers and practitioners working with Near-Infrared Spectroscopy data.

Key Features

• NIRS-Specific Preprocessing — SNV, MSC, Savitzky-Golay, Norris-Williams, wavelet denoise, OSC/EPO, and 30+ spectral transforms
• Advanced PLS Models — AOM-PLS, POP-PLS, OPLS, DiPLS, MBPLS, and 15+ PLS variants with automatic operator selection
• Multi-Backend ML — Seamless integration with scikit-learn, TensorFlow, PyTorch, and JAX
• Declarative Pipelines — Define complex workflows with simple, readable syntax
• Parallel Execution — Multi-core pipeline variant execution via joblib
• Hyperparameter Tuning — Built-in Optuna integration for automated optimization
• Rich Visualizations — Performance heatmaps, candlestick plots, SHAP explanations
• Model Deployment — Export trained pipelines as portable .n4a bundles
• sklearn Compatible — NIRSPipeline wrapper for SHAP, cross-validation, and more
• Stable API Contracts — Public API signatures, result schemas, and workspace storage format are stable since v0.9.0

Advanced visualization capabilities for model performance analysis

Installation

Basic Installation

pip install nirs4all

This installs the core library with scikit-learn support. Deep learning frameworks are optional.

With ML Backends

# TensorFlow
pip install nirs4all[tensorflow]

# PyTorch
pip install nirs4all[torch]

# JAX
pip install nirs4all[jax]

# All frameworks
pip install nirs4all[all]

# All frameworks with GPU support
pip install nirs4all[all-gpu]

# Verified native Methods training, full refit, and Archive V2/V3 replay
pip install nirs4all[native]

The native extra enables the explicit, fail-closed engine="native" Methods subset: raw-array PLS training with explicit sample IDs, stateful native sessions, strict Methods HPO, Archive V2 export/load, target-bound Archive V3 full-refit export/load, and replay. It does not change the default engine, fit a legacy runner, or silently fall back for a native request.

Docker

docker pull ghcr.io/gbeurier/nirs4all:latest
docker run -v $(pwd):/workspace ghcr.io/gbeurier/nirs4all python my_script.py

Development Installation

git clone https://github.com/GBeurier/nirs4all.git
cd nirs4all
pip install -e ".[dev]"

Verify Installation

nirs4all --test-install      # Check dependencies
nirs4all --test-integration  # Run integration tests
nirs4all --version           # Check version

Quick Start

Simple API (Recommended)

import nirs4all
from sklearn.preprocessing import MinMaxScaler
from sklearn.model_selection import ShuffleSplit
from sklearn.cross_decomposition import PLSRegression

# Define your pipeline
pipeline = [
    MinMaxScaler(),
    {"y_processing": MinMaxScaler()},
    ShuffleSplit(n_splits=3, test_size=0.25),
    {"model": PLSRegression(n_components=10)}
]

# Train and evaluate
result = nirs4all.run(
    pipeline=pipeline,
    dataset="path/to/your/data",
    name="MyPipeline",
    verbose=1
)

# Access results
print(f"Best RMSE: {result.best_rmse:.4f}")
print(f"Best R²: {result.best_r2:.4f}")

# Export for deployment
result.export("exports/best_model.n4a")

Session for Multiple Runs

import nirs4all
from sklearn.preprocessing import MinMaxScaler
from sklearn.cross_decomposition import PLSRegression
from sklearn.ensemble import RandomForestRegressor

with nirs4all.session(verbose=1, save_artifacts=True) as s:
    # Compare models with shared configuration
    pls_result = nirs4all.run(
        pipeline=[MinMaxScaler(), PLSRegression(n_components=10)],
        dataset="data/wheat.csv",
        name="PLS",
        session=s
    )

    rf_result = nirs4all.run(
        pipeline=[MinMaxScaler(), RandomForestRegressor(n_estimators=100)],
        dataset="data/wheat.csv",
        name="RandomForest",
        session=s
    )

    print(f"PLS: {pls_result.best_rmse:.4f} | RF: {rf_result.best_rmse:.4f}")

sklearn Integration with SHAP

import nirs4all
from nirs4all.sklearn import NIRSPipeline
import shap

# Train with nirs4all
result = nirs4all.run(pipeline, dataset)

# Wrap for sklearn compatibility
pipe = NIRSPipeline.from_result(result)

# Use with SHAP
explainer = shap.Explainer(pipe.predict, X_background)
shap_values = explainer(X_test)
shap.summary_plot(shap_values)

Public API (v0.9.0+)

The following entry points and result objects are stable contracts — their signatures and return types are guaranteed within the 0.9.x series:

import nirs4all

result = nirs4all.run(pipeline=[...], dataset="path/to/data", verbose=1)
preds  = nirs4all.predict("model.n4a", new_data)
expl   = nirs4all.explain("model.n4a", data)
result = nirs4all.retrain("model.n4a", new_data, mode="transfer")
sess   = nirs4all.session(...)
sess   = nirs4all.load_session(path)
ds     = nirs4all.generate(n_samples=500, complexity="realistic")

Result objects: RunResult, PredictResult, ExplainResult — expose best_score, best_rmse, best_r2, best_accuracy, top(n), export(), filter(**kwargs), get_datasets(), get_models().

Pipeline Syntax

NIRS4ALL uses a declarative syntax for defining pipelines:

from nirs4all.operators.transforms import SNV, SavitzkyGolay, FirstDerivative

pipeline = [
    # Preprocessing
    MinMaxScaler(),
    SNV(),
    SavitzkyGolay(window_length=11, polyorder=2),

    # Target scaling
    {"y_processing": MinMaxScaler()},

    # Cross-validation
    ShuffleSplit(n_splits=5, test_size=0.2),

    # Models to compare
    {"model": PLSRegression(n_components=10)},
    {"model": RandomForestRegressor(n_estimators=100)},

    # Neural network with training parameters
    {
        "model": nicon,
        "name": "NICON-CNN",
        "train_params": {"epochs": 100, "patience": 20}
    }
]

Advanced Features

# Feature augmentation - generate preprocessing combinations
{
    "feature_augmentation": {
        "_or_": [SNV, FirstDerivative, SavitzkyGolay],
        "size": [1, (1, 2)],
        "count": 5
    }
}

# Hyperparameter optimization
{
    "model": PLSRegression(),
    "finetune_params": {
        "n_trials": 50,
        "model_params": {"n_components": ("int", 1, 30)}
    }
}

# Branching for parallel preprocessing paths
{
    "branch": [
        [SNV(), PLSRegression(n_components=10)],
        [MSC(), RandomForestRegressor()]
    ]
}

# Merge branch outputs (stacking)
{"merge": "predictions"}

Available Transforms

NIRS-Specific Preprocessing

Signal Processing

Built-in NIRS Models

Splitting Methods

See Preprocessing Guide for complete reference.

Examples

The examples/ directory is organized by topic:

User Examples (examples/user/)

Reference Examples (examples/reference/)

Complete syntax reference and advanced pipeline patterns.

Run examples:

cd examples
./run.sh              # Run all
./run.sh -i 1         # Run by index
./run.sh -n "U01*"    # Run by pattern

Documentation

Full documentation: nirs4all.readthedocs.io

Research Applications

NIRS4ALL has been used in published research:

Houngbo, M. E., et al. (2024). Convolutional neural network allows amylose content prediction in yam (Dioscorea alata L.) flour using near infrared spectroscopy. Journal of the Science of Food and Agriculture, 104(8), 4915-4921. John Wiley & Sons, Ltd.

Citation

If you use NIRS4ALL in your research, please cite:

@software{beurier2025nirs4all,
  author = {Gregory Beurier and Denis Cornet and Lauriane Rouan},
  title = {NIRS4ALL: Open spectroscopy for everyone},
  url = {https://github.com/GBeurier/nirs4all},
  version = {0.12.10},
  year = {2026},
}

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• Report bugs
• Request features
• Improve documentation

License

nirs4all is dual-licensed open-source — CeCILL-2.1 OR AGPL-3.0-or-later (your choice) — with an optional commercial license for closed-source / SaaS use. For any commercial use, contact nirs4all-admin@cirad.fr. See LICENSING.md, the full texts bundled under LICENSES/, and third-party attributions in THIRD_PARTY_NOTICES.md.

Acknowledgments

• CIRAD for supporting this research
• The open-source scientific Python community