| Type: | Package |
| Title: | Conic Adaptive Piecewise Local Explanations |
| Version: | 0.1.0 |
| 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. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.1.0) |
| NeedsCompilation: | no |
| Packaged: | 2026-10-18 00:19:59 UTC; vilda |
| Author: | 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ı <nurgul.gokgoz@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-10-29 19:20:14 UTC |
Explain one observation with a local surrogate
Description
Explain one observation with a local surrogate.
Usage
CAP_LIME(x_train, instance, predict_fn, method = "LIME",
num_samples = 2000, lambda = 1, kernel_width = NULL,
target_r2 = 0.70, seed = 42)
Arguments
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. |
Details
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.
Value
A list with method, instance_prediction, local_r2, kernel_width, effects .
Examples
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
Description
Explore repeatability of local explanations.
Usage
CAP_stability(x_train, instance, predict_fn, method = "LIME",
runs = 10, top_k = 4, num_samples = 1000, seed = 42, ...)
Arguments
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. |
Details
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.
Value
A list containing VSI, CSI and explanations.
Examples
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$VSI
Fit ridge-penalized piecewise hinge regression
Description
Fit ridge-penalized piecewise hinge regression.
Usage
fit_CAP_model(x, y, lambda = 5, num_knots = 5, degree = 1)
Arguments
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. |
Details
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.
Value
A CAP_model object with knots, coefficients, predictor names and interaction degree.
Examples
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
Description
Draw ranked local-effect coefficients.
Usage
plot_CAP_LIME(explanation, top_n = 15)
Arguments
explanation |
Result returned by CAP_LIME. |
top_n |
Number of highest-ranked features to display. |
Details
Signed regression coefficients are shown on their original feature scales.
Value
Draws a base graphics bar plot; returns the result from barplot invisibly or as a graphics side effect.
Examples
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 from a fitted piecewise model
Description
Predict a numeric outcome from a CAP model.
Usage
predict_CAP_model(model, newdata, probability = FALSE)
## S3 method for class 'CAP_model'
predict(object, newdata, ...)
Arguments
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. |
Details
Clipping values to zero and one does not guarantee probability calibration.
Value
A numeric vector of predictions.
Examples
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])