Implementation:Interpretml Interpret Sampling

Knowledge Sources	Interpretml Interpret
Domains	Machine_Learning, EBM_Core
Last Updated	2026-02-07 12:00 GMT

Overview

Sampling is a C++ module that provides sampling without replacement functions for creating train/validation splits, including stratified sampling for classification tasks and bag unpacking.

Description

This module implements three key functions for dataset sampling:

• SampleWithoutReplacement: EBM public API function that randomly assigns each sample to either training (BagEbm{1}) or validation (BagEbm{-1}) without replacement. Supports both deterministic (via RandomDeterministic RNG) and non-deterministic (via RandomNondeterministic) modes. The deterministic mode copies the RNG state to CPU registers for performance and restores it after sampling.

• SampleWithoutReplacementStratified: EBM public API function that performs stratified sampling, ensuring that each class is represented proportionally in both training and validation sets. The algorithm:
  • Computes the ideal training proportion across all classes
  • Initializes per-class training counts as the floor of the ideal count minus 1
  • Distributes leftover samples using a greedy improvement algorithm that prioritizes: (a) classes with zero training samples (boost of +32), (b) general improvement toward ideal proportions, (c) deprioritizes classes that would lose their only validation sample (penalty of -32)
  • When multiple classes have equal improvement, randomly selects among them
  • Finally, iterates through all samples and randomly assigns each to train or validation based on the per-class quotas

• Unbag: Internal utility function that counts the total number of training samples (positive bag values) and validation samples (negative bag values) from a bag array. Handles multi-replication bags where the absolute value indicates the replication count.

Usage

These functions are called during EBM initialization to create the train/validation split. SampleWithoutReplacement is used for regression and general cases, while SampleWithoutReplacementStratified is used for classification to maintain class balance. Unbag is used internally by both BoosterCore and InteractionCore to determine subset sizes.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: shared/libebm/sampling.cpp

Signature

EBM_API_BODY ErrorEbm EBM_CALLING_CONVENTION SampleWithoutReplacement(
    void* rng,
    IntEbm countTrainingSamples,
    IntEbm countValidationSamples,
    BagEbm* bagOut);

EBM_API_BODY ErrorEbm EBM_CALLING_CONVENTION SampleWithoutReplacementStratified(
    void* rng,
    IntEbm countClasses,
    IntEbm countTrainingSamples,
    IntEbm countValidationSamples,
    const IntEbm* targets,
    BagEbm* bagOut);

extern ErrorEbm Unbag(
    const size_t cSamples,
    const BagEbm* const aBag,
    size_t* const pcTrainingSamplesOut,
    size_t* const pcValidationSamplesOut);

I/O Contract

Inputs

Name	Type	Required	Description
rng	void*	No	Pointer to a RandomDeterministic RNG (nullptr for non-deterministic)
countTrainingSamples	IntEbm	Yes	Desired number of training samples
countValidationSamples	IntEbm	Yes	Desired number of validation samples
countClasses	IntEbm	Yes (stratified)	Number of target classes
targets	const IntEbm*	Yes (stratified)	Array of target class indices per sample
bagOut	BagEbm*	Yes	Output array for sample assignments

Outputs

Name	Type	Description
return value	ErrorEbm	Error code (Error_None on success)
bagOut	BagEbm*	Array with +1 for training samples and -1 for validation samples
pcTrainingSamplesOut	size_t* (Unbag)	Count of training samples in the bag
pcValidationSamplesOut	size_t* (Unbag)	Count of validation samples in the bag

Usage Examples

Pipeline Context

# This C++ module is called internally via the native bindings
# to create the train/validation split
from interpret.glassbox import ExplainableBoostingClassifier
ebm = ExplainableBoostingClassifier(validation_size=0.15)
ebm.fit(X, y)  # Internally calls SampleWithoutReplacementStratified

Related Pages

• Environment:Interpretml_Interpret_Native_Libebm_Environment