# bioroboticslab/iba-paper-code architecture

> Architecture diagram of the GitHub repository bioroboticslab/iba-paper-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bioroboticslab/iba-paper-code
- Repository: https://github.com/bioroboticslab/iba-paper-code

## Overview

This is a research implementation for producing image-attribution heatmaps, especially Per-Sample and Readout Information Bottlenecks, alongside gradient, occlusion, Grad-CAM, and LRP methods. The main workflow configures a model and attribution method, computes a heatmap, then evaluates or visualizes it; evaluation scripts cover bounding boxes, degradation, and sensitivity-n. The graph preserves these documented capabilities. Several links rely on the SOURCE INDEX or README rather than sampled implementation excerpts, so unsampled internal behavior is not inferred beyond those references.

Main entry points: [`attribution_bottleneck/evaluate/script_utils.py`](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/script_utils.py) (Model and method setup), [`attribution_bottleneck/attribution/factory.py`](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/factory.py) (Method factory), [`attribution_bottleneck/bottleneck/readout_bottleneck.py`](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/readout_bottleneck.py) (Readout bottleneck), [`attribution_bottleneck/attribution/backprop.py`](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/backprop.py) (Backprop methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_attribution["Attribution methods"]
  node_factory["Method factory<br/>[factory.py]"]
  node_backprop["Backprop methods<br/>[backprop.py]"]
  node_averaging["Averaged gradients"]
  node_guided["Guided backprop<br/>[guided_backprop.py]"]
  node_gradcam["Grad-CAM<br/>[grad_cam.py]"]
  node_occlusion["Occlusion maps<br/>[occlusion.py]"]
  node_lrp["LRP attribution<br/>[lrp.py]"]
  node_sample_reader["Per-sample reader"]
  node_readout_reader["Readout reader"]
end

subgraph group_bottlenecks["Bottleneck internals"]
  node_estimator["Layer estimators<br/>[estimator.py]"]
  node_sample_bottleneck["Per-sample bottleneck"]
  node_readout_bottleneck["Readout bottleneck"]
  node_gaussian["Spatial Gaussian kernel<br/>[gaussian_kernel.py]"]
end

subgraph group_evaluation["Evaluation workflows"]
  node_script_utils["Model and method setup<br/>[script_utils.py]"]
  node_data_provider["ImageNet data provider<br/>[data.py]"]
  node_degradation["Degradation evaluation<br/>[degradation.py]"]
  node_perturber["Image perturbation<br/>[perturber.py]"]
  node_bbox_script["Bounding-box task"]
  node_degradation_script["Degradation task"]
  node_sensitivity_script["Sensitivity-n task"]
end

subgraph group_shared["Shared image utilities"]
  node_baselines["Image baselines<br/>[baselines.py]"]
  node_transforms["Heatmap transforms<br/>[transforms.py]"]
end

node_user(("Research user"))

node_user -->|"runs task"| node_bbox_script
node_user -->|"runs task"| node_degradation_script
node_user -->|"runs task"| node_sensitivity_script
node_bbox_script -->|"configures setup"| node_script_utils
node_degradation_script -->|"configures setup"| node_script_utils
node_sensitivity_script -->|"configures setup"| node_script_utils
node_script_utils -->|"selects methods"| node_factory
node_script_utils -->|"constructs reader"| node_sample_reader
node_script_utils -->|"constructs reader"| node_readout_reader
node_script_utils -->|"loads model"| node_readout_bottleneck
node_script_utils -->|"creates provider"| node_data_provider
node_factory -->|"selects method"| node_backprop
node_factory -->|"selects method"| node_averaging
node_factory -->|"selects method"| node_guided
node_factory -->|"selects method"| node_gradcam
node_factory -->|"selects method"| node_occlusion
node_factory -->|"selects method"| node_lrp
node_averaging -->|"uses gradients"| node_backprop
node_guided -->|"extends method"| node_backprop
node_sample_reader -->|"reads statistics"| node_estimator
node_sample_reader -->|"optimizes bottleneck"| node_sample_bottleneck
node_readout_reader -->|"uses bottleneck"| node_readout_bottleneck
node_sample_bottleneck -->|"uses kernel"| node_gaussian
node_readout_bottleneck -->|"uses kernel"| node_gaussian
node_readout_bottleneck -->|"reuses module"| node_sample_bottleneck
node_degradation -->|"orders perturbations"| node_perturber
node_degradation -->|"builds baseline"| node_baselines
node_baselines -->|"uses grid views"| node_perturber
node_backprop -->|"postprocesses maps"| node_transforms
node_occlusion -->|"applies baseline"| node_baselines

click node_factory "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/factory.py"
click node_backprop "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/backprop.py"
click node_averaging "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/averaging_gradient.py"
click node_guided "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/guided_backprop.py"
click node_gradcam "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/grad_cam.py"
click node_occlusion "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/occlusion.py"
click node_lrp "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/lrp/lrp.py"
click node_sample_reader "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/per_sample_bottleneck.py"
click node_readout_reader "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/readout_bottleneck.py"
click node_estimator "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/estimator.py"
click node_sample_bottleneck "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/per_sample_bottleneck.py"
click node_readout_bottleneck "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/readout_bottleneck.py"
click node_gaussian "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/gaussian_kernel.py"
click node_script_utils "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/script_utils.py"
click node_data_provider "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/data.py"
click node_degradation "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/degradation.py"
click node_perturber "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/perturber.py"
click node_bbox_script "https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_bounding_boxes.py"
click node_degradation_script "https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_degradation.py"
click node_sensitivity_script "https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_sensitivity_n.py"
click node_baselines "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/baselines.py"
click node_transforms "https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/transforms.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_factory,node_backprop,node_averaging,node_guided,node_gradcam,node_occlusion,node_lrp,node_sample_reader,node_readout_reader,node_user toneBlue
class node_estimator,node_sample_bottleneck,node_readout_bottleneck,node_gaussian toneAmber
class node_script_utils,node_data_provider,node_degradation,node_perturber,node_bbox_script,node_degradation_script,node_sensitivity_script toneMint
class node_baselines,node_transforms toneRose
```

## Components

### Attribution methods

- [Method factory](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/factory.py): `attribution_bottleneck/attribution/factory.py`
- [Backprop methods](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/backprop.py): `attribution_bottleneck/attribution/backprop.py`
- [Averaged gradients](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/averaging_gradient.py): `attribution_bottleneck/attribution/averaging_gradient.py`
- [Guided backprop](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/guided_backprop.py): `attribution_bottleneck/attribution/guided_backprop.py`
- [Grad-CAM](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/grad_cam.py): `attribution_bottleneck/attribution/grad_cam.py`
- [Occlusion maps](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/occlusion.py): `attribution_bottleneck/attribution/occlusion.py`
- [LRP attribution](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/lrp/lrp.py): `attribution_bottleneck/attribution/lrp/lrp.py`
- [Per-sample reader](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/per_sample_bottleneck.py): `attribution_bottleneck/attribution/per_sample_bottleneck.py`
- [Readout reader](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/attribution/readout_bottleneck.py): `attribution_bottleneck/attribution/readout_bottleneck.py`

### Bottleneck internals

- [Layer estimators](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/estimator.py): `attribution_bottleneck/bottleneck/estimator.py`
- [Per-sample bottleneck](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/per_sample_bottleneck.py): `attribution_bottleneck/bottleneck/per_sample_bottleneck.py`
- [Readout bottleneck](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/readout_bottleneck.py): `attribution_bottleneck/bottleneck/readout_bottleneck.py`
- [Spatial Gaussian kernel](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/bottleneck/gaussian_kernel.py): `attribution_bottleneck/bottleneck/gaussian_kernel.py`

### Evaluation workflows

- [Model and method setup](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/script_utils.py): `attribution_bottleneck/evaluate/script_utils.py`
- [ImageNet data provider](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/data.py): `attribution_bottleneck/utils/data.py`
- [Degradation evaluation](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/degradation.py): `attribution_bottleneck/evaluate/degradation.py`
- [Image perturbation](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/evaluate/perturber.py): `attribution_bottleneck/evaluate/perturber.py`
- [Bounding-box task](https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_bounding_boxes.py): `scripts/eval_bounding_boxes.py`
- [Degradation task](https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_degradation.py): `scripts/eval_degradation.py`
- [Sensitivity-n task](https://github.com/bioroboticslab/iba-paper-code/blob/master/scripts/eval_sensitivity_n.py): `scripts/eval_sensitivity_n.py`

### Shared image utilities

- [Image baselines](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/baselines.py): `attribution_bottleneck/utils/baselines.py`
- [Heatmap transforms](https://github.com/bioroboticslab/iba-paper-code/blob/master/attribution_bottleneck/utils/transforms.py): `attribution_bottleneck/utils/transforms.py`

### Other components

- **Research user**

## Connections

- Research user → Bounding-box task: runs task (evidence: `README.md`)
- Research user → Degradation task: runs task (evidence: `README.md`)
- Research user → Sensitivity-n task: runs task (evidence: `README.md`)
- Bounding-box task → Model and method setup: configures setup (evidence: `scripts/eval_bounding_boxes.py`)
- Degradation task → Model and method setup: configures setup (evidence: `scripts/eval_degradation.py`)
- Sensitivity-n task → Model and method setup: configures setup (evidence: `scripts/eval_sensitivity_n.py`)
- Model and method setup → Method factory: selects methods (evidence: `attribution_bottleneck/evaluate/script_utils.py`)
- Model and method setup → Per-sample reader: constructs reader (evidence: `attribution_bottleneck/evaluate/script_utils.py`)
- Model and method setup → Readout reader: constructs reader (evidence: `attribution_bottleneck/evaluate/script_utils.py`)
- Model and method setup → Readout bottleneck: loads model (evidence: `attribution_bottleneck/evaluate/script_utils.py`)
- Model and method setup → ImageNet data provider: creates provider (evidence: `attribution_bottleneck/evaluate/script_utils.py`)
- Method factory → Backprop methods: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Method factory → Averaged gradients: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Method factory → Guided backprop: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Method factory → Grad-CAM: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Method factory → Occlusion maps: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Method factory → LRP attribution: selects method (evidence: `attribution_bottleneck/attribution/factory.py`)
- Averaged gradients → Backprop methods: uses gradients (evidence: `attribution_bottleneck/attribution/averaging_gradient.py`)
- Guided backprop → Backprop methods: extends method (evidence: `attribution_bottleneck/attribution/guided_backprop.py`)
- Per-sample reader → Layer estimators: reads statistics (evidence: `attribution_bottleneck/attribution/per_sample_bottleneck.py`)
- Per-sample reader → Per-sample bottleneck: optimizes bottleneck (evidence: `attribution_bottleneck/attribution/per_sample_bottleneck.py`)
- Readout reader → Readout bottleneck: uses bottleneck (evidence: `attribution_bottleneck/attribution/readout_bottleneck.py`)
- Per-sample bottleneck → Spatial Gaussian kernel: uses kernel (evidence: `attribution_bottleneck/bottleneck/per_sample_bottleneck.py`)
- Readout bottleneck → Spatial Gaussian kernel: uses kernel (evidence: `attribution_bottleneck/bottleneck/readout_bottleneck.py`)
- Readout bottleneck → Per-sample bottleneck: reuses module (evidence: `attribution_bottleneck/bottleneck/readout_bottleneck.py`)
- Degradation evaluation → Image perturbation: orders perturbations (evidence: `attribution_bottleneck/evaluate/degradation.py`)
- Degradation evaluation → Image baselines: builds baseline (evidence: `attribution_bottleneck/evaluate/degradation.py`)
- Image baselines → Image perturbation: uses grid views (evidence: `attribution_bottleneck/utils/baselines.py`)
- Backprop methods → Heatmap transforms: postprocesses maps (evidence: `attribution_bottleneck/attribution/backprop.py`)
- Occlusion maps → Image baselines: applies baseline (evidence: `attribution_bottleneck/attribution/occlusion.py`)
