Patch-level interpretability

PGVL-Gym can turn a completed fold checkpoint into a coordinate-aligned WSI evidence map. The workflow preserves the quantity that the method actually uses—such as class-query attention, prompt evidence, patch probability, or pooling attention—and does not rename every score as generic attention.

Interpretability is an optional adapter capability. The default BaseMethod.interpret_step refuses generation, so a method is supported only after its score semantics and patch ordering have been audited.

Generate an artifact set

Choose a checkpoint directory, fold, split, and slide from the same resolved run configuration:

python scripts/generate_heatmap.py \
  --method pathpt \
  --config benchmarks/camelyon16/configs/pathpt/camelyon16_16shot.yaml \
  --ckpt-dir /path/to/camelyon16/pathpt/16shot \
  --fold 0 \
  --split test \
  --slide-id test_001

The command verifies the method/config fingerprint before loading the fold checkpoint. It defaults to the model's predicted class and to the test split. Use an exact class label or its frozen numeric index to request another class-specific map:

python scripts/generate_heatmap.py \
  --method focus --config run.yaml --ckpt-dir /path/to/results \
  --fold 2 --slide-id slide_123 --target-class LUSC

The default image is drawn on a neutral canvas in the feature file's level-0 coordinate frame. Add the exact source WSI for an overlay:

python scripts/generate_heatmap.py \
  --method focus --config run.yaml --ckpt-dir /path/to/results \
  --fold 2 --slide-id slide_123 --wsi /path/to/slide_123.svs

The WSI level-0 dimensions must equal the geometry recorded in the feature HDF5. This check prevents a visually plausible map from being placed on the wrong slide or coordinate frame. WSI overlays require openslide-python; coordinate-only rendering does not.

Useful rendering options are:

Option	Meaning
--alpha 0.55	Overlay opacity from 0 through 1
--max-size 2048	Longest rendered image dimension in pixels
--percentiles 1 99	Display clipping used only for PNG normalization
--output-dir PATH	Override the default artifact directory
--checkpoint auto|best|final	Select the same checkpoint kinds supported by evaluation
--overwrite	Permit replacement of matching files in a non-empty output directory

Changing the alpha, colormap range, or output dimensions never changes the raw scores written to CSV.

Output contract

By default, artifacts are stored with the checkpoint rather than in the source tree:

<checkpoint-dir>/interpretability/fold<K>/<slide-id>/
├── <scale>_<score-type>.csv
├── <scale>_<score-type>.png
└── manifest.json

Dual-scale methods can emit two CSV/PNG pairs under the same manifest. Each CSV contains patch_index, level-0 x/y, the lossless score, its semantic type, scale, class index when applicable, and whether the signal comes from the native architecture.

The manifest binds the visualization to:

• the resolved run identity, implementation fidelity, and encoder-extension disclosure;
• the selected best/final checkpoint and its SHA-256 digest;
• fold, split, slide, predicted class, class probabilities, and requested target class;
• feature path, feature-space identity, patch size, and level-0 coordinate frame;
• prompt provenance, evidence definition, score summary, and rendering parameters.

The true label is recorded for auditability, but it is not given to the model or used to select, fit, or normalize the explanation. The requested target defaults to the prediction, not the ground truth.

Audited providers

Method	Exact patch signal	Class-specific	Scales
FOCUS	Class-query cross-attention after selection/compression	Yes	Active high-resolution bag
ViLa-MIL	Class-prompt context cross-attention, excluding learned prototype keys	Yes	Low and high
CoD-MIL	Predicted-class prompt evidence used for high-scale selection	Predicted class only	Low
PathPT	Native patch-class probability (upstream_patch_ssl only)	Yes	Patch bag
TOP	Mean instance-prototype pooling attention for attention-producing pooling variants	No	Patch bag
SLIP	Patch-to-tissue-to-slide routing evidence	Yes	Patch bag
MUSE	Label-free class-semantic expert-routing attention	Yes	Patch bag
Libra-MIL	Multimodal transport pooling attention	No	Patch bag
DyKo	Visual prompt-to-patch cross-attention	Yes when prompt rows align with classes	Patch bag
MGPATH	Learned-image-center pooling attention	No	Low and high
HIPSS	Region attention multiplied by within-region patch attention	No; follows the native guidance rule	Patch bag

Provider support describes the score, not the fidelity of the entire run. For example, an encoder-swapped extension can expose the architecture's audited signal while the manifest still identifies the run as an extension. Always report both the evidence semantics and the run provenance.

Deliberate unsupported boundary

MAPLE, MSCPT, WSI-FiVE, ConVLM, SLDPC, HiVE-MIL, MI-VisionShot, and Composite currently fail with a clear diagnostic because their registered paths do not expose an audited patch-aligned native score. This is intentional. A gradient, occlusion, or perturbation map may be added later as a separately named post-hoc extension, but it must not be presented as paper-native attention.

Reading a heatmap responsibly

• Compare score values only within the semantics of one provider. A PathPT probability is not numerically comparable with a TOP pooling weight.
• Use the CSV for quantitative analysis. The PNG is a percentile-clipped rendering intended for inspection and figures.
• Keep the target class, scale, feature space, patch size, and magnification in every caption. A visually similar heatmap can represent a different query.
• A high-evidence region explains the model's internal aggregation or similarity path; it is not a causal claim and is not a pathology annotation.
• Preserve manifest.json with any published figure so its checkpoint, coordinate source, and provenance remain recoverable.

See the method support matrix for the compact capability view and results and reporting for the minimum benchmark reporting checklist.