Splitters Reference

Your independent unit may be a specimen, subject, batch or instrument. The splitter assigns these units to training and validation. Random splitting, stratification, group splitting and calibration sampling answer different questions. The tables enumerate each strategy and its parameters.

Choose what must remain unseen before choosing a splitter

Read split: define what must be unseen for the worked result figure, expected dimensions and exercises. Choose a family below to compare the enumerated operators.

Same worked recipe in JSON, YAML and Python

JSON

{
  "pipeline": [
    {
      "split": {
        "class": "sklearn.model_selection.KFold",
        "params": {
          "n_splits": 3,
          "shuffle": true,
          "random_state": 42
        }
      }
    },
    {
      "model": {
        "class": "sklearn.cross_decomposition.PLSRegression",
        "params": {
          "n_components": 2
        }
      }
    }
  ]
}

YAML

pipeline:
- split:
    class: sklearn.model_selection.KFold
    params:
      n_splits: 3
      shuffle: true
      random_state: 42
- model:
    class: sklearn.cross_decomposition.PLSRegression
    params:
      n_components: 2

Python

from sklearn.model_selection import KFold
from sklearn.cross_decomposition import PLSRegression

pipeline = [
    KFold(n_splits=3, shuffle=True, random_state=42),
    {"model": PLSRegression(n_components=2)},
]

These are Python SDK operators. Native R/Octave/WASM recipes use their own method IDs and facade; see 10. Run the same recipe in your language.

---

NIRS-Specific Splitters

All splitters below are imported from nirs4all.operators.splitters.

Single-Split Methods

These produce a single train/test split.

Class	Key Parameters	Description
KennardStoneSplitter	test_size, pca_components=None, metric="euclidean"	Kennard-Stone algorithm: selects maximally diverse training samples using max-min distance criterion
SPXYSplitter	test_size, pca_components=None, metric="euclidean"	SPXY (Sample set Partitioning based on joint X and Y distances): Kennard-Stone extended to include target information
KMeansSplitter	test_size, pca_components=None, metric="euclidean"	K-Means clustering-based split: clusters samples and assigns cluster centers to training
KBinsStratifiedSplitter	test_size, n_bins=10, strategy="uniform", encode="ordinal"	Stratified sampling using KBins discretization of continuous targets
SystematicCircularSplitter	test_size	Systematic circular sampling: orders by y-value, then selects at regular intervals
SPlitSplitter	test_size	Data twinning algorithm (Vakayil & Joseph 2022): selects a statistically representative subset

K-Fold Methods

These produce multiple folds for cross-validation.

Class	Key Parameters	Description
SPXYFold	n_splits=5, metric="euclidean", y_metric="euclidean", pca_components=None	SPXY-based K-Fold: assigns samples to folds using joint X-Y distances for spatially representative folds
SPXYGFold	n_splits=5, metric="euclidean", y_metric="euclidean", pca_components=None	Group-aware SPXY K-Fold: respects group boundaries while using SPXY distance criterion
BinnedStratifiedGroupKFold	n_splits=5, n_bins=10, strategy="quantile", shuffle=False	Stratified Group K-Fold with binned continuous targets: ensures balanced target distribution across folds while respecting groups

Group Wrapper

Class	Key Parameters	Description
GroupedSplitterWrapper	splitter, aggregation="mean", y_aggregation=None	Wraps any sklearn splitter to add group-awareness; aggregates samples by group and ensures no group leakage

Usage:

JSON

{
  "class": "nirs4all.operators.splitters.grouped_wrapper.GroupedSplitterWrapper",
  "params": {
    "splitter": "sklearn.model_selection._split.KFold"
  }
}

YAML

class: nirs4all.operators.splitters.grouped_wrapper.GroupedSplitterWrapper
params:
  splitter: sklearn.model_selection._split.KFold

Python

from nirs4all.operators.splitters import GroupedSplitterWrapper
from sklearn.model_selection import KFold

# Any splitter becomes group-aware
wrapper = GroupedSplitterWrapper(KFold(n_splits=5))

---

Commonly Used sklearn Splitters

These are imported from sklearn.model_selection and work directly in nirs4all pipelines.

Class	Key Parameters	Description
KFold	n_splits=5, shuffle=False	Standard K-Fold cross-validation
StratifiedKFold	n_splits=5, shuffle=False	K-Fold with stratification on target classes
ShuffleSplit	n_splits=10, test_size=0.1	Random train/test splits with configurable sizes
RepeatedKFold	n_splits=5, n_repeats=10	Repeated K-Fold cross-validation
LeaveOneOut	(none)	Leave-one-out cross-validation
GroupKFold	n_splits=5	K-Fold respecting group boundaries
StratifiedGroupKFold	n_splits=5, shuffle=False	Stratified K-Fold respecting groups

---

SPXYFold Parameters Detail

SPXYFold supports several configurations for different use cases:

Parameter	Values	Description
y_metric	"euclidean"	For regression (continuous y) – default SPXY behavior
y_metric	"hamming"	For classification (categorical y)
y_metric	None	Ignore Y (pure Kennard-Stone, X-only selection)
pca_components	int or None	Apply PCA dimensionality reduction before distance computation

---

See Also

• Pipeline Keywords Reference – Pipeline keyword syntax

• Filters Reference – Sample filtering operators

• Built-in Models Reference – Built-in models reference

Choose the independent unit before the algorithm

Educational workflow result; read the accompanying explanation for scope and interpretation.

The split defines the generalization claim. New samples, new physical subjects, future acquisitions and unseen instruments are different questions. Repeated scans, pixels from one specimen, augmented copies and repeated source observations do not become independent because they occupy different rows. Group them by the appropriate origin before assigning folds.

Strategy	Why choose it	What it does not establish
Shuffled KFold/ShuffleSplit	Exchangeable independent samples from one population	Generalization to unseen batches or future drift
StratifiedKFold	Preserve class coverage across classification folds	Independence between repeated measurements
GroupKFold/GroupedSplitterWrapper	Hold out complete origins, subjects or batches	Class or target balance without a separate balancing policy
BinnedStratifiedGroupKFold	Balance continuous-target bins while preserving groups	Exact balance when groups are large or scarce
Kennard–Stone	Cover feature-space diversity in calibration rows	Random-population test performance or unseen-target extrapolation
SPXY/SPXYFold/SPXYGFold	Represent joint X/y space, optionally respecting groups	Prospective selection without labels for future samples
KMeansSplitter	Representative calibration based on cluster structure	A guarantee of coverage for small rare subgroups
KBinsStratified/SystematicCircular	Spread target ranges across partitions	A deployment drift test
SPlitSplitter	Representative subset through data twinning	Independence if repeated origins were not grouped
TimeSeriesSplit	Respect temporal ordering in ordered observations	Protection against overlap when one origin spans dates
LeaveOneOut	Train on nearly all available independent samples	Low variance of the estimated score or freedom from selection bias

Kennard–Stone uses a max-min distance criterion to spread selected calibration samples. The metric, scaling and optional PCA therefore define what “diverse” means. SPXY adds target distances: selection uses known targets and must be described as retrospective calibration design. Group-aware variants avoid splitting origins, but still require sufficient independent groups in every fold. Stratification and grouping solve different problems.

Folds are part of the experiment

The number of folds changes training size and compute. Repeated folds increase resampling evidence but are correlated because rows recur. Report how scores are aggregated; an unweighted mean of fold RMSE is not pooled RMSE when folds have unequal sizes. Avoid selecting a preprocessing or model using the final test fold. Use nested selection or a separate development/holdout design.

Record row IDs, group/origin relations, partition roles, seeds and any distance-based representation used to create the folds. Reusing identical folds makes candidate comparisons easier to interpret. Resume and artifact audit also depend on these identities, not merely on random_state=42.

For runnable group binding see U02_group_splitting.py; for comparisons run U01_cv_strategies.py. The split node, fold files and group metadata are documented in split: define what must be unseen. Check 6. Measure whether your model answers the question before adding nested search, ensembles or calibration on top of a splitter.