Implementation:Interpretml Interpret R Bindings

Knowledge Sources	Interpretml Interpret
Domains	R_Language, Native_Bindings, EBM
Last Updated	2026-02-07 12:00 GMT

Overview

C++ source file implementing R language bindings for the InterpretML EBM (Explainable Boosting Machine) library, exposing 21 native functions for data handling, boosting, interaction detection, and quantile discretization.

Description

This file bridges R and the native libebm C++ library using the R C API (Rinternals.h). It provides:

Type conversion utilities:

• ConvertDouble / ConvertIndex / ConvertIndexApprox / ConvertInt / ConvertBool -- Safe conversion functions from R SEXP types to C++ types with bounds checking and NaN validation.
• CountInts / CountDoubles -- Length-safe counting functions for R integer and real vectors.
• ConvertDoublesToIndexes -- Bulk conversion of R double vectors to IntEbm arrays using R_alloc for automatic memory management.

Resource management finalizers:

• RngFinalizer / DataSetFinalizer / BoostingFinalizer / InteractionFinalizer -- R garbage collection callbacks that properly free native handles.

Exposed R functions (21 total):

• RNG: CreateRNG_R -- Creates a random number generator with a seed.
• Discretization: CutQuantile_R, Discretize_R -- Quantile-based binning and feature discretization.
• Data management: MeasureDataSetHeader_R, MeasureFeature_R, MeasureClassificationTarget_R, CreateDataSet_R, FreeDataSet_R, FillDataSetHeader_R, FillFeature_R, FillClassificationTarget_R -- Create and populate EBM dataset structures.
• Sampling: SampleWithoutReplacement_R -- Train/validation split sampling.
• Boosting: CreateBooster_R, FreeBooster_R, GenerateTermUpdate_R, ApplyTermUpdate_R, GetBestTermScores_R, GetCurrentTermScores_R -- Full EBM boosting lifecycle.
• Interaction: CreateInteractionDetector_R, FreeInteractionDetector_R, CalcInteractionStrength_R -- Feature interaction strength calculation.

All functions use R's external pointer mechanism (R_MakeExternalPtr) to wrap native handles and register finalizers for proper cleanup.

Usage

This file is compiled as part of the R package build process. R users interact with these bindings through the interpret R package's high-level API. The bindings are registered via R_init_interpret and called through .Call() from R code.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: R/src/interpret_R.cpp

Signature

// Key exposed functions
SEXP CreateRNG_R(SEXP seed);
SEXP CutQuantile_R(SEXP featureVals, SEXP minSamplesBin, SEXP isRounded, SEXP countCuts);
SEXP Discretize_R(SEXP featureVals, SEXP cutsLowerBoundInclusive, SEXP binIndexesOut);
SEXP CreateBooster_R(SEXP rng, SEXP dataSetWrapped, SEXP bag, SEXP initScores,
                     SEXP dimensionCounts, SEXP featureIndexes, SEXP countInnerBags);
SEXP GenerateTermUpdate_R(SEXP rng, SEXP boosterHandleWrapped, SEXP indexTerm,
                          SEXP learningRate, SEXP minHessian, SEXP leavesMax);
SEXP ApplyTermUpdate_R(SEXP boosterHandleWrapped);
SEXP GetBestTermScores_R(SEXP boosterHandleWrapped, SEXP indexTerm);
SEXP CreateInteractionDetector_R(SEXP dataSetWrapped, SEXP bag, SEXP initScores);
SEXP CalcInteractionStrength_R(SEXP interactionHandleWrapped, SEXP featureIndexes,
                               SEXP maxCardinality, SEXP minHessian);

// Registration table
static const R_CallMethodDef g_exposedFunctions[] = {
   { "CreateRNG_R", (DL_FUNC)&CreateRNG_R, 1 },
   { "CutQuantile_R", (DL_FUNC)&CutQuantile_R, 4 },
   // ... 21 functions total
   { NULL, NULL, 0 }
};

extern "C" {
   void attribute_visible R_init_interpret(DllInfo * info);
}

Import

# From R, functions are called via .Call():
.Call("CreateRNG_R", seed)
.Call("CreateBooster_R", rng, dataset, bag, initScores, dimCounts, featureIdx, nInnerBags)

I/O Contract

Inputs

Name	Type	Required	Description
SEXP parameters	R objects	Yes	R vectors, scalars, and external pointers passed via .Call()
seed	INTSXP	Yes	Random seed for RNG creation
featureVals	REALSXP	Yes	Feature values for discretization
dataSetWrapped	EXTPTRSXP	Yes	External pointer to native dataset handle
boosterHandleWrapped	EXTPTRSXP	Yes	External pointer to native booster handle
interactionHandleWrapped	EXTPTRSXP	Yes	External pointer to native interaction detector handle

Outputs

Name	Type	Description
EXTPTRSXP	R external pointer	Wrapped native handles for RNG, DataSet, Booster, InteractionDetector
REALSXP	R numeric vector	Cut points, scores, metrics, byte counts
R_NilValue	NULL	Void return for mutating operations (Fill*, Discretize, Free*)

Usage Examples

# These functions are typically called through the interpret R package API.
# Low-level usage example:

# Create RNG
rng <- .Call("CreateRNG_R", as.integer(42))

# Create and fill a dataset
headerBytes <- .Call("MeasureDataSetHeader_R",
                     as.numeric(nFeatures), as.numeric(nWeights), as.numeric(nTargets))
dataset <- .Call("CreateDataSet_R", headerBytes)
.Call("FillDataSetHeader_R",
      as.numeric(nFeatures), as.numeric(nWeights), as.numeric(nTargets),
      headerBytes, dataset)

# Create a booster
booster <- .Call("CreateBooster_R", rng, dataset, bag, initScores,
                 dimCounts, featureIndexes, as.numeric(nInnerBags))

# Generate and apply a term update
gain <- .Call("GenerateTermUpdate_R", rng, booster,
              as.numeric(0), as.numeric(0.01), as.numeric(0), leavesMax)
metric <- .Call("ApplyTermUpdate_R", booster)

# Cleanup
.Call("FreeBooster_R", booster)
.Call("FreeDataSet_R", dataset)

Related Pages

• Interpretml_Interpret_Build_Script -- Build script that compiles libebm (which this file links against)
• Interpretml_Interpret_CI_Workflow -- CI workflow that builds and tests the R package