# dylan-slack/modeling-uncertainty-local-explainability architecture

> Architecture diagram of the GitHub repository dylan-slack/modeling-uncertainty-local-explainability, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dylan-slack/modeling-uncertainty-local-explainability
- Repository: https://github.com/dylan-slack/modeling-uncertainty-local-explainability

## Overview

##### Project type and purpose
- This is a research codebase implementing BayesLIME, a post-hoc explainability method that models uncertainty.
- It’s organized as:
– A core Python package (“bayes”) containing model definitions, data routines, and explanation logic
– A data layer with tabular and image datasets
– Experiment scripts to reproduce paper results
– Visualization code for plotting posteriors

##### File structure – main components
- Data Layer (“data/”):
– Tabular CSVs (COMPAS, German Credit)
– Pretrained MNIST model & loaders
– Hook to external ImageNet downloader script
- Core Library (“bayes/”):
– data_routines.py: dataset loading & preprocessing
– models.py & regression.py: define Bayesian models
– explanations.py: BayesLIME explanation routines
- Experiments (“experiments/”):
– ptg.py, calibration.py, stability.py: CLI scripts to run tasks
– plotting notebooks: generate plots for PTG and stability experiments
- Visualization (“visualization/”):
- Config & metadata: requirements.txt, citation.bib, README.md

##### README for stack details
- Python ecosystem, PyTorch for CNNs, scikit-learn for tabular, Jupyter notebooks for plotting
- CLI-driven experiments with flags (–dataset, –n_threads, etc.)
- External downloads: torchvision VGG16, custom ImageNet downloader

1. Data Sources
- Local CSVs (data/*.csv)
- MNIST folder & pretrained model
- External ImageNet downloader
2. Data Module (bayes.data_routines)
3. Bayesian Engine (bayes.models, bayes.regression)
4. Explanation Module (bayes.explanations)
5. Experiment Runner
- Scripts: experiments/ptg.py, calibration.py, stability.py
- CLI interface (argparse flags)
6. Visualization Layer
- Jupyter Notebooks (experiments/plotting)
- image_posterior.py
7. External Services
- PyTorch Hub (download VGG16)
- ImageNet Downloader script

– Data Sources → Data Module → Bayesian Engine → Explanation Module
– Explanation Module → Experiment Runner → Output Metrics (calibration curves, stability scores)
– Experiment Runner → Visualization Notebooks → Figures/GIFs
– Data Sources & Models ↔ Experiment Runner (via CLI flags)
– Experiment Runner fetches pretrained models from External Services

c. Architectural patterns & design principles
- Modular separation:
– “bayes” package handles all core algorithm logic
– “data” package isolates raw data
– “experiments” folder isolates reproducibility scripts
– “visualization” folder isolates plotting concerns
- Reuse of standard ML tools (PyTorch, sklearn)
- Use of CLI wrappers to orchestrate experiments in a uniform way
- Jupyter notebooks for exploratory & publication-ready visuals

d. Key technologies & libraries
– Python 3.x
– PyTorch (MNIST CNN, VGG16)
– scikit-learn (tabular models, regression)
– numpy, pandas (data ops)
– matplotlib, seaborn (plots)
– argparse/click (experiment CLI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources Layer
    subgraph "Data Sources"
        direction TB
        CSV1["COMPAS CSV"]:::data
        CSV2["German Credit CSV"]:::data
        MNIST["MNIST Data & Model"]:::data
        ImageNetDL["ImageNet Downloader"]:::external
    end

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        DataModule["Data Module\n(bayes.data_routines)"]:::core
        BayesianEngine["Bayesian Engine\n(bayes.models & bayes.regression)"]:::core
        ExplanationModule["Explanation Module\n(bayes.explanations)"]:::core
    end

    %% Experiment Runner Layer
    subgraph "Experiment Runner"
        direction TB
        PTG["ptg.py"]:::experiments
        Calib["calibration.py"]:::experiments
        Stability["stability.py"]:::experiments
    end

    %% Visualization Layer
    subgraph "Visualization"
        direction TB
        PTGNotebook["PTG Plots Notebook"]:::viz
        StabilityNotebook["Stability Plots Notebook"]:::viz
        ImgPost["image_posterior.py"]:::viz
        ImgPostExample["image_posterior_example.py"]:::viz
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PyTorchHub["PyTorch Hub (VGG16)"]:::external
    end

    %% Data Flows
    CSV1 -->|load CSV| DataModule
    CSV2 -->|load CSV| DataModule
    MNIST -->|load images/model| DataModule
    DataModule -->|preprocessed data| BayesianEngine
    BayesianEngine -->|model outputs| ExplanationModule
    ExplanationModule -->|explanations| PTG
    ExplanationModule -->|explanations| Calib
    ExplanationModule -->|explanations| Stability
    PTG -->|runs experiments\n--dataset, --n_threads| PTGNotebook
    Calib -->|runs experiments| StabilityNotebook
    Stability -->|runs experiments| StabilityNotebook
    PTG -->|generates posterior| ImgPost
    Stability -->|generates posterior| ImgPost
    ImgPost -->|visualize| ImgPostExample

    %% Bidirectional link for dataset flags
    PTG <-->|--dataset, --model| CSV1
    Calib <-->|--dataset, --model| CSV2
    Stability <-->|--dataset, --model| MNIST

    %% External fetch
    PTG -->|fetch pretrained| PyTorchHub
    Calib -->|fetch pretrained| PyTorchHub
    Stability -->|fetch pretrained| PyTorchHub

    %% Click Events
    click CSV1 "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/data/compas-scores-two-years.csv"
    click CSV2 "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/data/german_processed.csv"
    click MNIST "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/tree/main/data/mnist/"
    click DataModule "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/bayes/data_routines.py"
    click BayesianEngine "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/bayes/models.py"
    click BayesianEngine "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/bayes/regression.py"
    click ExplanationModule "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/bayes/explanations.py"
    click PTG "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/experiments/ptg.py"
    click Calib "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/experiments/calibration.py"
    click Stability "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/experiments/stability.py"
    click PTGNotebook "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/experiments/plotting/PTG Plots.ipynb"
    click StabilityNotebook "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/experiments/plotting/Stability Plots.ipynb"
    click ImgPost "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/visualization/image_posterior.py"
    click ImgPostExample "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/visualization/image_posterior_example.py"
    click PyTorchHub "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/requirements.txt"
    click PyTorchHub "https://github.com/dylan-slack/modeling-uncertainty-local-explainability/blob/main/README.md"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#66A3FF,color:#004085
    classDef core fill:#DFF2BF,stroke:#8AC18E,color:#4F8A10
    classDef experiments fill:#FFE4B2,stroke:#FFB84D,color:#A65E00
    classDef viz fill:#E0D9FF,stroke:#A290FF,color:#3F2E7A
    classDef external fill:#F0F0F0,stroke:#C0C0C0,color:#606060
```
