How dylan-slack/modeling-uncertainty-local-explainability works
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)