Interactive Example Browser

NIRS4ALL ships with 70+ comprehensive examples organized into three categories, each demonstrating real-world spectroscopy workflows. Browse by difficulty, topic, or learning path to find the perfect starting point for your use case.

Quick Start

🚀 First Time Here?

Start with the beginner learning path: 4 examples covering basics to get you analyzing spectra in 30 minutes.

Recommended for new users

🎯 Looking for Something Specific?

Jump directly to examples organized by topic: data handling, preprocessing, models, pipelines, etc.

For experienced users

Running Examples

All examples are executable Python scripts located in examples/ with sample datasets included:

# Run from project root
cd examples

# Run all user examples
./run.sh -c user

# Run specific example
python user/01_getting_started/U01_hello_world.py

# Run with visualizations
python user/01_getting_started/U02_basic_regression.py --plots --show

---

Beginner Learning Path

Start here if you’re new to nirs4all. Follow this 4-step path to understand core concepts:

1️⃣ Hello World

★☆☆☆☆ | ~1 minute

examples/user/01_getting_started/U01_hello_world.py

Your first pipeline in 20 lines. Train a PLS model on NIRS data and get predictions.

Topics: nirs4all.run() basics, pipeline structure, reading results

2️⃣ Basic Regression

★★☆☆☆ | ~3 minutes

examples/user/01_getting_started/U02_basic_regression.py

Add preprocessing, feature augmentation, and visualization to your pipeline.

Topics: SNV, derivatives, PredictionAnalyzer, comparing models

3️⃣ Flexible Data Inputs

★☆☆☆☆ | ~2 minutes

examples/user/02_data_handling/U01_flexible_inputs.py

Learn all the ways to load data: numpy arrays, dictionaries, SpectroDataset objects.

Topics: Data formats, partition specification, dataset configuration

4️⃣ Preprocessing Basics

★★☆☆☆ | ~3 minutes

examples/user/03_preprocessing/U01_preprocessing_basics.py

Explore NIRS-specific preprocessing: scatter correction, derivatives, smoothing.

Topics: SNV, MSC, Detrend, Savitzky-Golay, wavelets

Next Steps: After completing this path, explore Intermediate Learning Path or browse examples by topic below.

---

Intermediate Learning Path

Ready to build production-ready models? Follow this path:

5️⃣ Multi-Model Comparison

★★☆☆☆ | ~3 minutes

examples/user/04_models/U01_multi_model.py

Compare multiple models in one run using the _or_ generator syntax.

Topics: Model selection, generator syntax, performance comparison

6️⃣ Cross-Validation Strategies

★★☆☆☆ | ~4 minutes

examples/user/05_cross_validation/U01_cv_strategies.py

Proper validation with K-Fold, stratified splits, and group-aware CV.

Topics: KFold, ShuffleSplit, StratifiedKFold, custom splits

7️⃣ Save, Load, and Predict

★★☆☆☆ | ~3 minutes

examples/user/06_deployment/U01_save_load_predict.py

Export trained models and make predictions on new data.

Topics: Model persistence, prediction API, workspace management

8️⃣ SHAP Basics

★★☆☆☆ | ~4 minutes

examples/user/07_explainability/U01_shap_basics.py

Understand model predictions with SHAP waterfall and spectral plots.

Topics: SHAP integration, feature importance, visualization

Next Steps: Explore Advanced Learning Path or dive into specific topics in the sections below.

---

Advanced Learning Path

Master advanced features for research and production systems:

9️⃣ Branching Basics

★★★☆☆ | ~5 minutes

examples/developer/01_advanced_pipelines/D01_branching_basics.py

Create parallel preprocessing branches and compare results.

Topics: Duplication branches, separation branches, branch comparison

🔟 Generator Syntax

★★★☆☆ | ~5 minutes

examples/developer/02_generators/D01_generator_syntax.py

Master the generator syntax for automated pipeline exploration.

Topics: _or_, _range_, _grid_, _zip_, _chain_

1️⃣1️⃣ Session Workflow

★★★★☆ | ~6 minutes

examples/developer/06_internals/D01_session_workflow.py

Use sessions for stateful multi-step workflows with training, prediction, and retraining.

Topics: Session API, persistence, multi-run workflows

1️⃣2️⃣ Cache Performance

★★★★☆ | ~6 minutes

examples/developer/06_internals/D03_cache_performance.py

Optimize large pipeline runs with step caching and CoW snapshots.

Topics: CacheConfig, memory optimization, performance tuning

---

Browse by Topic

📚 Getting Started (4 examples)

Perfect first examples for understanding nirs4all basics.

Example	Difficulty	Description
U01: Hello World	★☆☆☆☆	Your first pipeline in 20 lines
U02: Basic Regression	★★☆☆☆	Preprocessing, feature augmentation, visualization
U03: Basic Classification	★★☆☆☆	Classification pipelines and confusion matrices
U04: Visualization	★★☆☆☆	Heatmaps, candlestick charts, prediction analysis

Key APIs: nirs4all.run(), PredictionAnalyzer, RunResult

---

💾 Data Handling (6 examples)

Loading data, multi-source datasets, synthetic data generation.

Example	Difficulty	Description
U01: Flexible Inputs	★☆☆☆☆	All data input formats: arrays, dicts, SpectroDataset
U02: Multi-Datasets	★★☆☆☆	Analyze multiple datasets in one run
U03: Multi-Source	★★★☆☆	Combine NIR, markers, and other data sources
U04: Wavelength Handling	★★☆☆☆	Resample, downsample, focus on spectral regions
U05: Synthetic Data	★★☆☆☆	Generate synthetic datasets with nirs4all.generate()
U06: Advanced Synthetic Data	★★★☆☆	SyntheticDatasetBuilder with metadata and batch effects

Key APIs: SpectroDataset, DatasetConfigs, nirs4all.generate(), SyntheticDatasetBuilder

---

🔬 Preprocessing (4 examples)

NIRS-specific preprocessing operators and signal conversions.

Example	Difficulty	Description
U01: Preprocessing Basics	★★☆☆☆	SNV, MSC, Detrend, derivatives, smoothing, wavelets
U02: Feature Augmentation	★★★☆☆	Explore preprocessing combinations with feature_augmentation
U03: Sample Augmentation	★★★☆☆	Data augmentation for training set expansion
U04: Signal Conversion	★★★☆☆	Convert between absorbance, reflectance, transmittance

Key APIs: SNV, MSC, Detrend, SavitzkyGolay, Derivative, ToAbsorbance, FromAbsorbance

---

🤖 Models (7 examples)

Model training, hyperparameter tuning, ensembles, PLS variants, and AOM models.

Example	Difficulty	Description
U01: Multi-Model	★★☆☆☆	Compare multiple models with _or_ generator
U02: Hyperparameter Tuning	★★★☆☆	Automated tuning with grid, random, Bayesian search
U03: Stacking Ensembles	★★★☆☆	StackingRegressor, VotingRegressor, meta-learners
U04: PLS Variants	★★★★☆	PLSRegression, IKPLS, OPLS, SparsePLS, IntervalPLS
U05: Advanced Fine-Tuning	★★★★☆	Advanced model fine-tuning workflows
U06: TabPFN NIRS	★★☆☆☆	Fixed-recipe TabPFN regressor for NIRS
U07: AOM Panoply	★★★★★	AOM-PLS, AOM-Ridge, AutoSelector, Blender, FastAOM with pipeline folds

Key APIs: finetune_params, StackingRegressor, PLS variants, AOM models, hyperparameter search

---

✅ Cross-Validation (6 examples)

Validation strategies, group splitting, outlier filtering, aggregation.

Example	Difficulty	Description
U01: CV Strategies	★★☆☆☆	KFold, ShuffleSplit, StratifiedKFold, custom splits
U02: Group Splitting	★★★☆☆	GroupKFold, repetition-aware splitting
U03: Sample Exclusion	★★★☆☆	Outlier detection with exclude keyword
U04: Repetition Aggregation	★★★☆☆	Aggregate predictions from repeated measurements
U05: Tagging Analysis	★★★☆☆	Mark samples with tag for downstream analysis
U06: Exclusion Strategies	★★★★☆	Advanced exclusion with “any” vs “all” modes

Key APIs: GroupKFold, YOutlierFilter, XOutlierFilter, tag, exclude, repetition

---

🚀 Deployment (4 examples)

Model persistence, bundle export, sklearn integration, workspace management.

Example	Difficulty	Description
U01: Save, Load, Predict	★★☆☆☆	Basic prediction workflow with workspace
U02: Export Bundle	★★☆☆☆	Export to .n4a and .n4a.py portable bundles
U03: Workspace Management	★★☆☆☆	Session context, SQLite storage, library management
U04: sklearn Integration	★★☆☆☆	Use NIRSPipeline as sklearn estimator for GridSearchCV

Key APIs: nirs4all.predict(), export(), NIRSPipeline, nirs4all.session()

---

🔍 Explainability (3 examples)

SHAP-based feature importance and variable selection.

Example	Difficulty	Description
U01: SHAP Basics	★★☆☆☆	SHAP waterfall, spectral, and beeswarm plots
U02: SHAP with sklearn	★★★☆☆	Custom SHAP explainers with NIRSPipeline wrapper
U03: Feature Selection	★★★☆☆	CARS, MC-UVE for variable selection

Key APIs: nirs4all.explain(), NIRSPipeline, SHAP integration, feature selection

---

Developer Examples (30 examples)

Advanced examples for extending nirs4all and building complex workflows.

🌿 Advanced Pipelines (7 examples)

Branching, merging, separation, stacking, value mapping.

Example	Difficulty	Description
D01: Branching Basics	★★★☆☆	Duplication and separation branches
D02: Branching Advanced	★★★★☆	BranchAnalyzer for statistical comparison
D03: Merge Basics	★★★★☆	Feature merge, prediction merge, concat merge
D04: Merge Sources	★★★★☆	Multi-source branching and merging
D05: Meta Stacking	★★★★★	MetaModel, StackingConfig, multi-level stacking
D06: Separation Branches	★★★★☆	by_tag, by_metadata, by_filter, by_source
D07: Value Mapping	★★★★☆	Group metadata values for custom branching

Key APIs: branch, merge, by_tag, by_metadata, by_source, MetaModel, StackingConfig

---

🎲 Generators & Synthetic Data (9 examples)

Generator syntax, synthetic data generation, application domains, instruments.

Example	Difficulty	Description
D01: Generator Syntax	★★★☆☆	_or_, _range_, pick, arrange
D02: Generator Advanced	★★★★☆	_mutex_, _requires_, _grid_, _zip_, _chain_, _sample_
D03: Generator Iterators	★★★★☆	Lazy iteration, batch processing, variant inspection
D04: Nested Generators	★★★★★	Hierarchical parameter spaces
D05: Custom Components	★★★★☆	Build custom spectral component libraries
D06: Synthetic Testing	★★★★☆	Use synthetic data for reproducible testing
D07: Wavenumber Procedural	★★★★☆	Overtone calculation, combination bands, H-bonding
D08: Application Domains	★★★★☆	Agriculture, food, pharma, environmental domains
D09: Instruments	★★★★☆	Simulate FOSS, Bruker, SCiO, multi-sensor instruments

Key APIs: _or_, _range_, _grid_, _zip_, generator constraints, SyntheticNIRSGenerator, application domains

---

🧠 Deep Learning (4 examples)

PyTorch, JAX, TensorFlow integration with the @framework decorator.

Example	Difficulty	Description
D01: PyTorch Models	★★★★☆	Built-in nicon, decon, transformer, custom models
D02: JAX Models	★★★★★	JAX/Flax integration with JIT compilation
D03: TensorFlow Models	★★★★☆	TensorFlow/Keras nicon and decon architectures
D04: Framework Comparison	★★★★☆	Same model across PyTorch, JAX, TensorFlow

Key APIs: @framework decorator, nicon, decon, transformer, custom DL models

---

🔄 Transfer Learning (3 examples)

Calibration transfer, retraining modes, PCA geometry analysis.

Example	Difficulty	Description
D01: Transfer Analysis	★★★★☆	TransferPreprocessingSelector for transfer problems
D02: Retrain Modes	★★★★☆	full, transfer, finetune retraining modes
D03: PCA Geometry	★★★☆☆	PreprocPCAEvaluator for geometry preservation

Key APIs: nirs4all.retrain(), TransferPreprocessingSelector, retrain modes

---

⚙️ Advanced Features (3 examples)

Metadata branching, concat transform, repetition transform.

Example	Difficulty	Description
D01: Metadata Branching	★★★★☆	Partition by metadata with value mapping
D02: Concat Transform	★★★☆☆	Concatenate multiple transformer outputs
D03: Repetition Transform	★★★★☆	Convert repetitions to sources or preprocessing variants

Key APIs: by_metadata, concat_transform, rep_to_sources, rep_to_pp

---

🔧 Internals (3 examples)

Session API, custom controllers, cache optimization.

Example	Difficulty	Description
D01: Session Workflow	★★★★☆	Stateful workflows with save/load/persist
D02: Custom Controllers	★★★★★	Extend nirs4all with custom operator controllers
D03: Cache Performance	★★★★☆	Step caching, CoW snapshots, memory optimization

Key APIs: nirs4all.session(), @register_controller, CacheConfig, controller architecture

---

Reference Examples (7 examples)

Comprehensive reference examples for advanced features.

Example	Difficulty	Description
R01: Pipeline Syntax	★★☆☆☆	Complete pipeline syntax reference
R02: Generator Reference	★★☆☆☆	All generator keywords and patterns
R03: All Keywords	★★★★★	Integration test for all pipeline keywords
R05: Environmental Effects	★★☆☆☆	Matrix effects simulation in synthetic data
R06: Synthetic Validation	★★☆☆☆	Quality assessment for synthetic spectra
R07: Synthetic Fitter	★★★★★	Fit synthetic data to match real spectra

---

Find Examples by Feature

By Feature Type

• Caching: D03: Cache Performance

• Branching: D01: Branching Basics, D06: Separation Branches

• Merging: D03: Merge Basics, D04: Merge Sources

• Stacking: U03: Stacking Ensembles, D05: Meta Stacking

• Generators: D01: Generator Syntax, D02: Generator Advanced

• Session API: U03: Workspace Management, D01: Session Workflow

• Synthetic Data: U05: Synthetic Data, U06: Advanced Synthetic, D05-D09: Synthetic Generators

• Multi-Source: U03: Multi-Source, D04: Merge Sources

• Aggregation: U04: Repetition Aggregation, D03: Repetition Transform

• Signal Types: U04: Signal Conversion

• Outlier Filtering: U03: Sample Exclusion, U06: Exclusion Strategies

• Deep Learning: D01-D04: Deep Learning Examples

• Custom Controllers: D02: Custom Controllers

---

Next Steps

After exploring examples:

• User Guide: User Guide - Complete documentation with detailed explanations

• API Reference: API Reference - Full API documentation

• Concepts: Concepts - The ideas behind pipelines, datasets, and workflows

• Developer Guide: Developer Guide - Deep dive into architecture and design patterns

• Getting Started: Quickstart - Installation and first steps

Questions? Check the Frequently Asked Questions or raise an issue on GitHub.