| Type: | Package |
| Title: | Adaptive Piecewise Local Model-Agnostic Explanations |
| Version: | 0.1.0 |
| 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. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.1.0) |
| Imports: | earth, stats, utils |
| Suggests: | testthat (≥ 3.0.0), xgboost |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-10-27 23:15:08 UTC; vilda |
| Author: | 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 <vpurutcu@metu.edu.tr> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-12 18:50:09 UTC |
Bootstrap Intervals for Grouped MARS Coefficients
Description
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.
Usage
aplime_bootstrap(explanation, n_boot = 100L, seed = NULL)
Arguments
explanation |
Output from |
n_boot |
Number of bootstrap resamples (at least two). |
seed |
Optional random seed. |
Value
A data frame of coefficient-group names, point estimates, and percentile confidence limits.
Coefficient Stability Index
Description
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.
Usage
aplime_csi(records, ci_method = c("normal", "bootstrap"))
Arguments
records |
List of repeated explanations containing coefficient confidence interval tables. |
ci_method |
Confidence interval type: |
Value
Percentage of overlap averaged across comparable groups, or NA_real_ if none can be compared.
Fit a Local Weighted MARS Explanation
Description
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.
Usage
aplime_explain(explainer, instance, degree = 1L, n_samples = 5000L,
n_features = 6L, seed = NULL, keep_neighborhood = FALSE)
Arguments
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. |
Value
An aplime_explanation object containing an earth fit, contribution table, selected feature indices, and weighted in-sample R-squared.
Create an Adaptive Piecewise Explainer
Description
Stores a reference distribution and a prediction interface for local perturbations.
Usage
aplime_explainer(background, predict_function, kernel_width = NULL)
Arguments
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. |
Value
An object of class aplime_explainer.
Examples
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)
Report Original MARS Hinge Knots
Description
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.
Usage
aplime_knot_report(records)
Arguments
records |
List of repeated |
Value
Data frame with repetition, term_group, original_term, hinges, coefficient, and different_knots.
Adapt XGBoost Predictions for AP-LIME
Description
Creates a prediction function suitable for aplime_explainer(). The optional xgboost package must be installed.
Usage
aplime_predict_xgboost(model)
Arguments
model |
An XGBoost Booster object or a model file path recognized by |
Value
A function taking a numeric matrix and returning numeric predictions.
Repeat Local Explanations and Evaluate Stability
Description
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.
Usage
aplime_repeat(explainer, instance, degree = 1L, n_repeats = 100L,
n_samples = 5000L, n_features = 6L, n_boot = 0L, seed = NULL)
Arguments
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. |
Value
A list with runs, vsi_percent, csi_normal_percent, csi_bootstrap_percent, rank_frequency, knot_report, and different_knot_groups.
Examples
## 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
Variable Stability Index
Description
Measures mean pairwise overlap of selected top-feature sets, normalized by the requested feature count.
Usage
aplime_vsi(records, n_features = NULL)
Arguments
records |
List of repeated explanations. |
n_features |
Number of top features in each explanation; inferred from the first record if omitted. |
Value
VSI on a 0 to 100 scale, or NA_real_ for fewer than two runs.
Print an AP-LIME Explanation
Description
Print the local surrogate type, weighted R-squared and ranked feature contributions.
Usage
## S3 method for class 'aplime_explanation'
print(x, ...)
Arguments
x |
An |
... |
Unused optional arguments. |
Value
Returns x invisibly.