[BMS] Gradient Interaction Modification

[LogicFan]

Contributor: Yongda Fan (yongdaf2@illinois.edu)

Contribution Type: Interpretability, Tests, Example Script

Description
Implemented Gradient Interaction Modifications (GIM) interpreter for StageNet aligned with PyHealth 2.0 interpretability APIs, including temperature-scaled softmax gradients per https://arxiv.org/pdf/2505.17630.
Wired StageNet-compatible hook context so GIM reuses DeepLIFT hooks or dedicated GIM hooks to manage activation overrides safely.
Added focused unit tests covering gradient equivalence, hook routing, temporal tuple inputs, and temperature-based behavior.
Created a MIMIC-IV example that loads StageNet checkpoints, runs GIM attribution, and prints top-ranked features.

Files to Review
pyhealth/interpret/methods/gim.py
pyhealth/interpret/methods/init.py
tests/core/test_gim.py
examples/gim_stagenet_mimic4.py

[jhnwu3]

Some quick thoughts that I think would be really cool for an extended showcase as I do want to see if creating an attention-based StageNet would improve interpretability here.

1. Can we extend this approach to be able to interpret the transformer class here? https://github.com/sunlabuiuc/PyHealth/blob/master/pyhealth/models/transformer.py. Mainly because GIM was intended to also help interpret attention-based models.
2. Can you update the docs in 2 locations here to incorporate this method? https://github.com/sunlabuiuc/PyHealth/blob/master/docs/api/interpret.rst and add a GIM.rst file in https://github.com/sunlabuiuc/PyHealth/tree/master/docs/api/interpret
3. On the topic of docs, can we add an example initialization and call in the doc strings? This way users can easily know how to directly use this method.

[LogicFan]

Docs has been updated.

The example for transformer has been created, though i cannot test it as i don't have a transformer checkpoint available.

[jhnwu3]

lgtm, I can test the transformer model on my end later, and implement a fix if need be.