| Title: | Adaptive Piecewise Local Model-Agnostic Explanations |
|---|---|
| Description: | Implements Adaptive Piecewise Local Interpretable Model-Agnostic Explanations (AP-LIME) and its second-order interaction extension (AP2-LIME) for interpreting predictions from machine learning models. The methods replace the conventional locally weighted linear surrogate in LIME with Multivariate Adaptive Regression Splines (MARS). AP-LIME uses additive piecewise-linear hinge functions, whereas AP2-LIME allows pairwise interactions between hinge functions. The package generates proximity-weighted local explanations, estimates feature contributions, evaluates local surrogate fit, and assesses explanation stability across repeated runs. Stability is measured using the Variables Stability Index (VSI) and Coefficients Stability Index (CSI), including normal-theory and percentile bootstrap confidence intervals. MARS terms with the same predictors, hinge directions, and interaction structure are matched independently of knot locations. Coefficients within matched groups are summarized by their arithmetic mean, while the original knot thresholds remain available for inspection. The MARS-based local explanation approach is discussed by Somuncuoglu and Purutcuoglu (2027, ISBN:978-1-041-34431-5), "Explainable AI Approaches in Biomedical Signals: A Case Study with Pima Indians Diabetes Dataset", in "Biomedical Data Science: A Focus on Signaling", CRC Press. |
| Authors: | Abdullah Nuri Somuncuoğlu [aut] (affiliation: Department of Biomedical Engineering, Middle East Technical University), Vilda Purutçuoğlu [aut, cre] (affiliation: Department of Statistics, Middle East Technical University) |
| Maintainer: | Vilda Purutçuoğlu <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-12 21:59:12 UTC |
| Source: | https://github.com/cran/aplime |
Fits the local MARS model on resampled neighborhood rows, averaging coefficients with the same variable, hinge direction, and interaction structure while ignoring knot values. A group absent from a refit remains missing rather than becoming zero.
aplime_bootstrap(explanation, n_boot = 100L, seed = NULL)aplime_bootstrap(explanation, n_boot = 100L, seed = NULL)
explanation |
Output from |
n_boot |
Number of bootstrap resamples (at least two). |
seed |
Optional random seed. |
A data frame of coefficient-group names, point estimates, and percentile confidence limits.
Computes pairwise interval overlaps among matching MARS coefficient groups. Knot positions are ignored when matching terms but hinge directions and interaction structure are retained. When multiple coefficients share a group in one fit, their arithmetic mean is used and the normal interval uses their joint covariance. Groups with fewer than two comparable intervals cannot contribute to the index.
aplime_csi(records, ci_method = c("normal", "bootstrap"))aplime_csi(records, ci_method = c("normal", "bootstrap"))
records |
List of repeated explanations containing coefficient confidence interval tables. |
ci_method |
Confidence interval type: |
Percentage of overlap averaged across comparable groups, or NA_real_ if none can be compared.
Samples a Gaussian neighborhood, applies distance weights, and fits a weighted earth surrogate. The displayed variable contributions are prediction differences; CSI is calculated separately from grouped MARS coefficients.
aplime_explain(explainer, instance, degree = 1L, n_samples = 5000L, n_features = 6L, seed = NULL, keep_neighborhood = FALSE)aplime_explain(explainer, instance, degree = 1L, n_samples = 5000L, n_features = 6L, seed = NULL, keep_neighborhood = FALSE)
explainer |
An |
instance |
One numeric observation in background column order. |
degree |
Interaction degree: 1 for additive hinge terms, 2 for two-way interactions. |
n_samples |
Number of Gaussian perturbations including the original observation. |
n_features |
Number of displayed variables, ranked by absolute prediction-difference contribution. Defaults to up to 6, capped at the number of available features. |
seed |
Optional random seed. |
keep_neighborhood |
Whether to retain samples and weights for coefficient interval estimation. |
An aplime_explanation object containing an earth fit, contribution table, selected feature indices, and weighted in-sample R-squared.
Stores a reference distribution and a prediction interface for local perturbations.
aplime_explainer(background, predict_function, kernel_width = NULL)aplime_explainer(background, predict_function, kernel_width = NULL)
background |
Numeric data frame or matrix with finite values. |
predict_function |
Function returning one finite prediction for each numeric matrix row. |
kernel_width |
Positive Gaussian kernel width; default is 0.75 times the square root of the predictor count. |
An object of class aplime_explainer.
set.seed(1) x <- data.frame(a = rnorm(30), b = rnorm(30)) f <- function(z) 2 * z[, 1] + z[, 2] explainer <- aplime_explainer(x, f)set.seed(1) x <- data.frame(a = rnorm(30), b = rnorm(30)) f <- function(z) 2 * z[, 1] + z[, 2] explainer <- aplime_explainer(x, f)
Lists each original hinge basis term and its coefficient, with a knot-insensitive group key and a logical flag indicating whether different original terms were matched in the group. The report retains all original thresholds even though CSI uses grouped coefficient means.
aplime_knot_report(records)aplime_knot_report(records)
records |
List of repeated |
Data frame with repetition, term_group, original_term, hinges, coefficient, and different_knots.
Creates a prediction function suitable for aplime_explainer(). The optional xgboost package must be installed.
aplime_predict_xgboost(model)aplime_predict_xgboost(model)
model |
An XGBoost Booster object or a model file path recognized by |
A function taking a numeric matrix and returning numeric predictions.
Generates repeated weighted MARS explanations and computes normal CSI, optional percentile-bootstrap CSI, variable stability, and rank-position frequencies. Terms are matched ignoring knot values; within-group coefficients are averaged. The knot_report output retains original terms, thresholds, and coefficients; different_knot_groups lists only matched groups containing different original terms. A warning identifies such groups.
aplime_repeat(explainer, instance, degree = 1L, n_repeats = 100L, n_samples = 5000L, n_features = 6L, n_boot = 0L, seed = NULL)aplime_repeat(explainer, instance, degree = 1L, n_repeats = 100L, n_samples = 5000L, n_features = 6L, n_boot = 0L, seed = NULL)
explainer |
An |
instance |
Observation to explain. |
degree |
MARS interaction degree: 1 or 2. |
n_repeats |
Number of explanation repetitions (at least two). |
n_samples |
Number of perturbations per repetition. |
n_features |
Number of displayed features and top coefficient groups. |
n_boot |
Number of bootstrap resamples, or zero to skip bootstrap CSI. |
seed |
Optional random seed. |
A list with runs, vsi_percent, csi_normal_percent, csi_bootstrap_percent, rank_frequency, knot_report, and different_knot_groups.
## Lightweight example; increase repetitions for a stability study. set.seed(1) x <- data.frame(a = rnorm(60), b = rnorm(60), c = rnorm(60)) f <- function(z) 1 + pmax(0, z[, 1] - 0.2) + z[, 2] * z[, 3] e <- aplime_explainer(x, f) out <- aplime_repeat(e, as.numeric(x[1, ]), n_repeats = 3, n_samples = 80, n_features = 2, n_boot = 3) out$csi_normal_percent out$different_knot_groups## Lightweight example; increase repetitions for a stability study. set.seed(1) x <- data.frame(a = rnorm(60), b = rnorm(60), c = rnorm(60)) f <- function(z) 1 + pmax(0, z[, 1] - 0.2) + z[, 2] * z[, 3] e <- aplime_explainer(x, f) out <- aplime_repeat(e, as.numeric(x[1, ]), n_repeats = 3, n_samples = 80, n_features = 2, n_boot = 3) out$csi_normal_percent out$different_knot_groups
Measures mean pairwise overlap of selected top-feature sets, normalized by the requested feature count.
aplime_vsi(records, n_features = NULL)aplime_vsi(records, n_features = NULL)
records |
List of repeated explanations. |
n_features |
Number of top features in each explanation; inferred from the first record if omitted. |
VSI on a 0 to 100 scale, or NA_real_ for fewer than two runs.
Print the local surrogate type, weighted R-squared and ranked feature contributions.
## S3 method for class 'aplime_explanation' print(x, ...)## S3 method for class 'aplime_explanation' print(x, ...)
x |
An |
... |
Unused optional arguments. |
Returns x invisibly.