pulsatrix 1.1.0
Loading...
Searching...
No Matches
protein_explanations.hpp File Reference

Explaining a protein language model residue by residue (PLM-6): AttnLRP from a masked residue's prediction, a mutation's log-odds or a head on the representations back to the input residues, and the checks that keep such explanations honest. More...

#include <cstdint>
#include <functional>
#include <string>
#include <string_view>
#include <vector>
#include "pulsatrix/attnlrp_parity.hpp"
#include "pulsatrix/encoder_lm.hpp"
#include "pulsatrix/explainer_capabilities.hpp"
#include "pulsatrix/protein_sequences.hpp"
#include "pulsatrix/proteingym.hpp"
#include "pulsatrix/relevance_graph.hpp"
#include "pulsatrix/text_tokenizer.hpp"
#include "pulsatrix/variant_scoring.hpp"
Include dependency graph for protein_explanations.hpp:

Go to the source code of this file.

Classes

struct  pulsatrix::LinearHead
 A linear head on the model's representations (last_hidden_state): weight . h + bias. More...
 
struct  pulsatrix::EncoderTarget
 What an explanation explains. Residues are numbered from 0 here. More...
 
struct  pulsatrix::ResidueRelevance
 Relevance per residue for one explained value. More...
 
class  pulsatrix::EncoderExplainer
 AttnLRP for an ESM-2 EncoderLM: explains a target (EncoderTarget) as relevance on the input residues, with LXT's rules by default (the identity rule on LayerNorm and GELU, the uniform rule at attention's matmuls, epsilon elsewhere), so it matches LXT's AttnLRP. More...
 
struct  pulsatrix::ResidueAgreement
 How a per-residue explanation agrees with an independent per-residue signal. More...
 
struct  pulsatrix::ResidueDeletionCurve
 A deletion curve against its random baseline. More...
 
struct  pulsatrix::RandomizationCheckResult
 The randomization check's result: after randomizing layers[0..i], how similar the explanation stays (Spearman of |relevance| per residue with the original). More...
 

Namespaces

namespace  pulsatrix
 

Functions

ResidueAgreement pulsatrix::CompareResidueSignals (const std::vector< float > &relevance, const std::vector< float > &signal, double top_fraction=0.1)
 Compares |relevance| with signal over the residues where both are finite; top_fraction picks k (at least 1).
 
std::vector< float > pulsatrix::DmsPositionSensitivity (const DmsVariants &variants, std::string_view sequence, int64_t offset=1)
 Each residue's sensitivity in a deep mutational scan: minus the mean score of its single mutants (higher scores being fitter, as in ProteinGym), so residues that tolerate no change rank highest. NaN where no single mutant was measured. Multiple mutants are skipped.
 
std::vector< float > pulsatrix::AlignmentConservation (const std::vector< FastaRecord > &alignment)
 Conservation of each query residue in a multiple sequence alignment whose first record is the query: log2(20) - entropy of the column's amino acids, in bits, times the share of sequences without a gap there. NaN for query residues outside the alignment's focus columns (lowercase).
 
std::string pulsatrix::AlignmentQuery (const std::vector< FastaRecord > &alignment)
 The query's residues in alignment's first record: its letters, uppercased.
 
std::vector< float > pulsatrix::RelevanceProfile (EncoderExplainer &explainer, std::string_view sequence, const std::function< void(int64_t done, int64_t total)> &progress={})
 How much the model draws on each residue when it predicts the others: the mean, over every residue's masked wild-type logit (EncoderTarget::MaskedToken), of each residue's share of the explanation's total |relevance|. A per-protein explanation to compare with per-residue signals such as DMS sensitivity or conservation.
 
ResidueDeletionCurve pulsatrix::DeletionCheck (EncoderExplainer &explainer, std::string_view sequence, const EncoderTarget &target, const std::vector< float > &relevance, int64_t steps=20, int64_t random_orders=5, uint64_t seed=0)
 Masks residues (<mask>) in order of how much they support the explained value (relevance of the value's own sign, largest first) and records the value, beside random_orders random orders. A faithful explanation moves the value toward zero faster than random. The explained residue itself is never masked twice: a masked target's residue stays masked throughout, and isn't counted.
 
RandomizationCheckResult pulsatrix::RandomizationCheck (EncoderExplainer &explainer, std::string_view sequence, const EncoderTarget &target, uint64_t seed=0)
 Cascading model randomization (Adebayo et al. 2018) over the encoder's own layers, top down: the LM head, then each layer from the last to the first, then the embeddings. Each step redraws the group's weight matrices (Gaussian, each with its own standard deviation) and re-explains. Norm gains and biases are kept: redrawn from their own small spread, a pre-LN block's gains shrink toward zero and the block becomes its residual connection, which would hide the randomization. The model's parameters are restored before returning.
 

Detailed Description

Explaining a protein language model residue by residue (PLM-6): AttnLRP from a masked residue's prediction, a mutation's log-odds or a head on the representations back to the input residues, and the checks that keep such explanations honest.

Residue-level explanations can look plausible and still not explain the model: a 2026 study (arXiv 2606.22181) found integrated gradients on a well-performing ESM-2 classifier missed the annotated epitopes. So every explanation here comes with checks against something independent of how it looks:

  • Randomization (Adebayo et al. 2018): randomize the model's layers from the top down; an explanation that barely changes isn't explaining the model.
  • Deletion: mask residues most relevant first; a faithful explanation makes the explained value fall faster than masking them in random order.
  • Agreement with an independent per-residue signal: a deep mutational scan's per-position sensitivity, or conservation in a multiple sequence alignment.