| Title: | Conic Adaptive Piecewise Local Explanations |
|---|---|
| Description: | Provides educational, base-R implementations of a ridge-penalized piecewise hinge regression model and local surrogate explanations for numerical prediction functions. Includes simplified variants inspired by local interpretable model-agnostic explanations (LIME) and a simplified bandwidth selection variant (OPTILIME), plus exploratory stability diagnostics. |
| Authors: | Nurgül Gökgöz Küçüksakallı [aut, cre] (affiliation: Department of Biomedical Engineering, Middle East Technical University), Vilda Purutçuoğlu [aut] (affiliation: Department of Statistics, Middle East Technical University) |
| Maintainer: | Nurgül Gökgöz Küçüksakallı <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-10-29 22:00:56 UTC |
| Source: | https://github.com/cran/caplime |
Explain one observation with a local surrogate.
CAP_LIME(x_train, instance, predict_fn, method = "LIME", num_samples = 2000, lambda = 1, kernel_width = NULL, target_r2 = 0.70, seed = 42)CAP_LIME(x_train, instance, predict_fn, method = "LIME", num_samples = 2000, lambda = 1, kernel_width = NULL, target_r2 = 0.70, seed = 42)
x_train |
Numeric predictor matrix with observations in rows. |
instance |
Numeric vector containing one observation to explain. |
predict_fn |
Function accepting a numeric matrix and returning one finite prediction per row. |
method |
Either "LIME" or "OPTILIME". |
num_samples |
Number of simulated neighbors, at least 10. |
lambda |
Nonnegative ridge penalty. |
kernel_width |
Positive neighborhood weighting bandwidth, or NULL for a default. |
target_r2 |
Target local fit for the simplified OPTILIME search. |
seed |
Random seed for repeatability. |
The OPTILIME mode is a simplified educational bandwidth search and not a full reproduction of the published procedure. LIME local coefficients depend on the predictor units. This function is model-agnostic and does not itself fit a conic optimization problem.
A list with method, instance_prediction, local_r2, kernel_width, effects .
x <- matrix(rnorm(120), ncol = 2) colnames(x) <- c("a", "b") f <- function(z) z[, 1] + 0.5 * z[, 2]^2 result <- CAP_LIME(x, x[1, ], f, num_samples = 80) head(result$effects)x <- matrix(rnorm(120), ncol = 2) colnames(x) <- c("a", "b") f <- function(z) z[, 1] + 0.5 * z[, 2]^2 result <- CAP_LIME(x, x[1, ], f, num_samples = 80) head(result$effects)
Explore repeatability of local explanations.
CAP_stability(x_train, instance, predict_fn, method = "LIME", runs = 10, top_k = 4, num_samples = 1000, seed = 42, ...)CAP_stability(x_train, instance, predict_fn, method = "LIME", runs = 10, top_k = 4, num_samples = 1000, seed = 42, ...)
x_train |
Numeric predictor matrix with observations in rows. |
instance |
Numeric vector containing one observation to explain. |
predict_fn |
Function accepting a numeric matrix and returning one finite prediction per row. |
method |
Either "LIME" or "OPTILIME". |
runs |
Number of independent neighborhood draws, at least 2. |
top_k |
Number of top-ranked terms compared between explanations. |
num_samples |
Neighborhood size per run. |
seed |
Starting integer random seed. |
... |
Additional parameters supplied to CAP_LIME. |
VSI here is mean pairwise Jaccard overlap of selected feature terms. CSI is a descriptive table of coefficient mean, standard deviation, and coefficient of variation, not the standard confidence-interval based CSI from published LIME-stability literature.
A list containing VSI, CSI and explanations.
x <- matrix(rnorm(120), ncol = 2) colnames(x) <- c("x1", "x2") f <- function(z) rowSums(z) s <- CAP_stability(x, x[1, ], f, runs = 3, top_k = 2, num_samples = 80) s$VSIx <- matrix(rnorm(120), ncol = 2) colnames(x) <- c("x1", "x2") f <- function(z) rowSums(z) s <- CAP_stability(x, x[1, ], f, runs = 3, top_k = 2, num_samples = 80) s$VSI
Fit ridge-penalized piecewise hinge regression.
fit_CAP_model(x, y, lambda = 5, num_knots = 5, degree = 1)fit_CAP_model(x, y, lambda = 5, num_knots = 5, degree = 1)
x |
Numeric matrix of predictors. |
y |
Numeric outcome vector. |
lambda |
Nonnegative ridge penalty. |
num_knots |
Positive integer number of evenly spaced knots per feature. |
degree |
Either 1 for main-effect hinge terms or 2 for pairwise hinge products. |
A simple piecewise ridge model fitted by linear algebra. Here conic refers to the source project name; this implementation has no explicit conic constraint. Large degrees and knot counts can create very large design matrices.
A CAP_model object with knots, coefficients, predictor names and interaction degree.
x <- matrix(rnorm(80), ncol = 2) colnames(x) <- c("a", "b") y <- x[, 1]^2 + x[, 2] model <- fit_CAP_model(x, y, num_knots = 2) head(predict_CAP_model(model, x))x <- matrix(rnorm(80), ncol = 2) colnames(x) <- c("a", "b") y <- x[, 1]^2 + x[, 2] model <- fit_CAP_model(x, y, num_knots = 2) head(predict_CAP_model(model, x))
Draw ranked local-effect coefficients.
plot_CAP_LIME(explanation, top_n = 15)plot_CAP_LIME(explanation, top_n = 15)
explanation |
Result returned by CAP_LIME. |
top_n |
Number of highest-ranked features to display. |
Signed regression coefficients are shown on their original feature scales.
Draws a base graphics bar plot; returns the result from barplot invisibly or as a graphics side effect.
x <- matrix(rnorm(100), ncol = 2) colnames(x) <- c("a", "b") f <- function(z) rowSums(z) result <- CAP_LIME(x, x[1, ], f, num_samples = 80) plot_CAP_LIME(result)x <- matrix(rnorm(100), ncol = 2) colnames(x) <- c("a", "b") f <- function(z) rowSums(z) result <- CAP_LIME(x, x[1, ], f, num_samples = 80) plot_CAP_LIME(result)
Predict a numeric outcome from a CAP model.
predict_CAP_model(model, newdata, probability = FALSE) ## S3 method for class 'CAP_model' predict(object, newdata, ...)predict_CAP_model(model, newdata, probability = FALSE) ## S3 method for class 'CAP_model' predict(object, newdata, ...)
model |
Fitted CAP_model object. |
object |
Fitted CAP_model object. |
newdata |
Numeric matrix with predictor columns in their training order. |
probability |
If TRUE, clip predictions to the range zero to one. |
... |
Additional arguments forwarded to predict_CAP_model, such as probability. |
Clipping values to zero and one does not guarantee probability calibration.
A numeric vector of predictions.
x <- matrix(rnorm(80), ncol = 2) colnames(x) <- c("a", "b") model <- fit_CAP_model(x, rowSums(x), num_knots = 2) predict(model, x[1:3, , drop = FALSE])x <- matrix(rnorm(80), ncol = 2) colnames(x) <- c("a", "b") model <- fit_CAP_model(x, rowSums(x), num_knots = 2) predict(model, x[1:3, , drop = FALSE])