# persimune/explainer architecture

> Architecture diagram of the GitHub repository persimune/explainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/persimune/explainer
- Repository: https://github.com/persimune/explainer

## Overview

##### Project type and purpose
- ExplaineR is an R package (library) for interpreting complex machine‐learning models (classification & regression) via Shapley values, multi‐measure evaluation, fairness, and decision‐curve analysis, with enhanced interactive visualizations.
- The user installs it from CRAN or GitHub, loads it in an R session, and calls high‐level functions (e.g., eSHAP_plot, SHAPclust) that internally assemble mlr3 tasks, train or accept pre‐trained models, compute Shapley values, and produce static or interactive plots.

##### File‐structure analysis
- Top-level files: DESCRIPTION, NAMESPACE, Rproj, LICENSE, README.
- R/ : all core R functions (grouped by functionality: SHAP computation, clustering, evaluation, plotting).
- man/ & Rd files: auto‐generated docs for each function.
- inst/ : package‐level assets (e.g., CITATION).
- vignettes/ : .Rmd tutorials for binary, multiclass, regression, and summary‐plot demos.
- docs/ & pkgdown.yml : pkgdown‐generated website (HTML, assets).
- .github/workflows/pkgdown.yaml : GitHub Actions pipeline to build & deploy the pkgdown site.
- .Rbuildignore, .gitignore, _pkgdown.yml: ignore rules and pkgdown configuration.

##### README insights
- Key external dependencies: mlbench (datasets), mlr3 & mlr3learners (task abstraction + learners), ranger (random forest), interactive widgets (htmlwidgets, plotly, crosstalk).
- Provides usage example chaining: data → TaskClassif → partition → lrn("classif.ranger") → train → eSHAP_plot (computes SHAP & returns multiple objects) → SHAPclust.

a. Main components
- User / R session (entry point)
- ExplaineR Public API (exported functions: e.g., eSHAP_plot, SHAPclust, eFairness, eDecisionCurve, ePerformance)
- Core computation modules (under R/):
– SHAP computation module (eSHAP_plot, eSHAP_plot_multiclass, eSHAP_plot_reg, shapPartialPlot)
– Clustering module (SHAPclust)
– Evaluation modules (eCM_plot, eROC_plot, eDecisionCurve, eFairness, eperformance, regressmdl_eval)
– Utility module (range01, explainer‐package setup)
- External ML framework: mlr3 (Task abstraction), mlr3learners, ranger (model training + prediction)
- Visualization layer: ggplot2, plotly/htmlwidgets, crosstalk (interactive elements)
- Documentation pipeline: pkgdown + vignettes (.Rmd), man/Rd → docs/
- CI/CD: GitHub Actions (pkgdown.yaml)

b. Relationships & interactions
- User → calls ⇒ Public API functions
- Public API → invokes ⇒ Core modules
- Core modules ↔ mlr3 / ranger (for fitting & predicting models)
- Core modules → compute SHAP values (likely via fastshap or custom code in shapPartialPlot)
- Core modules → send data structures (data frames, arrays) → Visualization layer → renders plots/widgets back to user
- vignettes (.Rmd) & man/Rd ← source code & roxygen2 comments ← R/
- pkgdown & GitHub Actions → generate docs/ from vignettes, man, README, pkgdown.yml

c. Architectural patterns / design principles
- Modular separation: each analysis or plot is its own function/module
- Layered architecture: API → computation → external ML libs → visualization
- Reuse via mlr3 abstractions (TaskClassif, partition, learner interface)
- Documentation‐as‐code: vignettes + pkgdown build from source

d. Key technologies/frameworks
- R language & S3/S4 objects
- mlr3, mlr3learners, ranger
- htmlwidgets, plotly, crosstalk, ggplot2
- roxygen2 (documentation), pkgdown (site generation)
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        User["User / R Session"]
    end

    %% Public API Layer
    subgraph "Public API" 
        direction TB
        ESHP["eSHAP_plot"]:::core
        ESHPM["eSHAP_plot_multiclass"]:::core
        ESHPR["eSHAP_plot_regression"]:::core
        SHC["SHAPclust"]:::core
        SFP["ShapFeaturePlot"]:::core
        ECM["eCM_plot"]:::core
        EROC["eROC_plot"]:::core
        EDC["eDecisionCurve"]:::core
        EFN["eFairness"]:::core
        EPR["ePerformance"]:::core
        RME["regressmdl_eval"]:::core
    end

    %% Core Modules
    subgraph "Core Computation Modules" 
        direction TB
        subgraph "SHAP Computation Module"
            shapPP["shapPartialPlot"]:::core
        end
        subgraph "Clustering Module"
            SHC_mod["SHAPclust (core)"]:::core
        end
        subgraph "Evaluation Modules"
            ECM_mod["eCM_plot"]:::core
            EROC_mod["eROC_plot"]:::core
            EDC_mod["eDecisionCurve"]:::core
            EFN_mod["eFairness"]:::core
            EPR_mod["ePerformance"]:::core
            RME_mod["regressmdl_eval"]:::core
        end
        subgraph "Utility Module"
            RNG["range01"]:::core
            EXPL["explainer-package"]:::core
        end
    end

    %% External ML Framework
    subgraph "External ML Frameworks" 
        direction TB
        MLR3["mlr3 & mlr3learners"]:::external
        RANGER["ranger"]:::external
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        GG["ggplot2"]:::external
        PLOTLY["plotly/htmlwidgets"]:::external
        CST["crosstalk"]:::external
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        R_SRC["R/ source code"]:::core
        MAN["man/ (Rd)"]:::doc
        VIG["vignettes/articles/*.Rmd"]:::doc
        PKGCFG["_pkgdown.yml & pkgdown/"]:::doc
        DOCS["docs/ (site)"]:::doc
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GH["GitHub Actions"]:::doc
        PKGYAML[".github/workflows/pkgdown.yaml"]:::doc
    end

    %% Connections
    User -->|"calls"| ESHP
    User -->|"calls"| ESHPM
    User -->|"calls"| ESHPR
    User -->|"calls"| SHC
    User -->|"calls"| SFP
    User -->|"calls"| ECM
    User -->|"calls"| EROC
    User -->|"calls"| EDC
    User -->|"calls"| EFN
    User -->|"calls"| EPR
    User -->|"calls"| RME

    ESHP -->|"invokes"| shapPP
    ESHPM -->|"invokes"| shapPP
    ESHPR -->|"invokes"| shapPP
    SHC -->|"invokes"| SHC_mod
    ECM -->|"invokes"| ECM_mod
    EROC -->|"invokes"| EROC_mod
    EDC -->|"invokes"| EDC_mod
    EFN -->|"invokes"| EFN_mod
    EPR -->|"invokes"| EPR_mod
    RME -->|"invokes"| RME_mod

    shapPP -->|"calls"| MLR3
    SHC_mod -->|"calls"| MLR3
    ECM_mod -->|"calls"| MLR3
    EROC_mod -->|"calls"| MLR3
    EDC_mod -->|"calls"| MLR3
    EFN_mod -->|"calls"| MLR3
    EPR_mod -->|"calls"| MLR3
    RME_mod -->|"calls"| MLR3

    MLR3 -->|"uses"| RANGER

    shapPP -->|"sends data frame"| GG
    ECM_mod -->|"sends data frame"| GG
    EROC_mod -->|"sends data frame"| GG
    EDC_mod -->|"sends data frame"| GG
    EFN_mod -->|"sends data frame"| GG
    EPR_mod -->|"sends data frame"| GG
    RME_mod -->|"sends data frame"| GG

    GG -->|"renders"| PLOTLY
    PLOTLY -->|"enables"| CST

    %% Documentation flow
    R_SRC -->|"roxygen2"| MAN
    R_SRC -->|"source"| VIG
    MAN -->|"pkgdown build"| DOCS
    VIG -->|"pkgdown build"| DOCS
    PKGCFG -->|"configures"| DOCS

    %% CI/CD flow
    PKGYAML -->|"triggers"| GH
    GH -->|"builds & deploys"| DOCS

    %% Click events
    click ESHP "https://github.com/persimune/explainer/blob/main/R/eSHAP_plot.R"
    click ESHPM "https://github.com/persimune/explainer/blob/main/R/eSHAP_plot_multiclass.R"
    click ESHPR "https://github.com/persimune/explainer/blob/main/R/eSHAP_plot_reg.R"
    click SHC "https://github.com/persimune/explainer/blob/main/R/SHAPclust.R"
    click SFP "https://github.com/persimune/explainer/blob/main/R/ShapFeaturePlot.R"
    click ECM "https://github.com/persimune/explainer/blob/main/R/eCM_plot.R"
    click EROC "https://github.com/persimune/explainer/blob/main/R/eROC_plot.R"
    click EDC "https://github.com/persimune/explainer/blob/main/R/eDecisionCurve.R"
    click EFN "https://github.com/persimune/explainer/blob/main/R/eFairness.R"
    click EPR "https://github.com/persimune/explainer/blob/main/R/eperformance.R"
    click RME "https://github.com/persimune/explainer/blob/main/R/regressmdl_eval.R"
    click shapPP "https://github.com/persimune/explainer/blob/main/R/shapPartialPlot.R"
    click RNG "https://github.com/persimune/explainer/blob/main/R/range01.R"
    click EXPL "https://github.com/persimune/explainer/blob/main/R/explainer-package.R"
    click R_SRC "https://github.com/persimune/explainer/tree/main/R/"
    click MAN "https://github.com/persimune/explainer/tree/main/man/"
    click VIG "https://github.com/persimune/explainer/tree/main/vignettes/articles"
    click PKGCFG "https://github.com/persimune/explainer/blob/main/_pkgdown.yml"
    click DOCS "https://github.com/persimune/explainer/tree/main/docs/"
    click PKGYAML "https://github.com/persimune/explainer/blob/main/.github/workflows/pkgdown.yaml"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,color:#1B4F72
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#1D8348
    classDef doc fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
```
