Author: Mohamed Amine FARES
Date: 2026-07-28

# Introduction to SAPP

#### Mohamed Amine FARES

#### 2026-07-28

## Overview

SAPP (Sector-Adjusted Points Plot) is an R package that visualizes feature dominance in a two-dimensional space. It combines PCA for dimensionality reduction with a novel sector-adjustment mechanism to show which features drive predictions for which observations.

## Quick Start

Load the package and prepare your data:

    library(sappviz)
    data(iris)
    X <- iris[, 1:4]

Fit a linear model and compute importances:

    model <- lm(Petal.Width ~ Sepal.Length + Sepal.Width + Petal.Length, data = iris)
    imp <- abs(coef(model)[-1])
    names(imp) <- c("Sepal.Length", "Sepal.Width", "Petal.Length")

Compute per-observation influence and plot:

    inf <- influence_feature(X, model)
    plot_sapp(X, imp, inf, alpha = "auto")
    #> Auto-Alpha selected: alpha = 0.54
    #> Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
    #> ℹ Please use `linewidth` instead.
    #> ℹ The deprecated feature was likely used in the sappviz package.
    #>   Please report the issue at <https://github.com/FaresAminu/sappviz/issues>.
    #> This warning is displayed once per session.
    #> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
    #> generated.
    #> Warning: The following aesthetics were dropped during statistical transformation: size.
    #> ℹ This can happen when ggplot fails to infer the correct grouping structure in
    #>   the data.
    #> ℹ Did you forget to specify a `group` aesthetic or to convert a numerical
    #>   variable into a factor?

## Interpretation

- Colors: The feature that most influenced each observation.
- Point size: How strongly that feature dominated.
- Black markers: Sector centers, based on global importances.
- Contours: Where each feature tends to dominate.

## Advanced Usage: Random Forest

SAPP supports tree-based models via SHAP values (requires fastshap):

    library(randomForest)
    rf <- randomForest(Species ~ ., data = iris, importance = TRUE)
    imp_rf <- importance(rf)[, "MeanDecreaseGini"]
    names(imp_rf) <- colnames(X)
    inf_rf <- influence_feature(X, rf)
    plot_sapp(X, imp_rf, inf_rf, alpha = "auto")

## References

Lundberg, S. M., and Lee, S.-I. (2017). A Unified Approach to Interpreting Model Predictions. NIPS.