torch_concepts.nn.functional.tcav_score

tcav_score(embeddings: Tensor, head: Callable, cavs: Tensor, target: int | str | Tuple[str, str] = 0) → Tensor[source]

Compute TCAV scores of concepts for a target output.

The conceptual sensitivity of concept C for target k at an input x is the directional derivative of the target output along the concept activation vector, S_{C,k}(x) = grad(head(x)[k]) . v_C: a positive value means an infinitesimal step towards the concept increases the target output. The TCAV score is the fraction of inputs with positive sensitivity; scores far from 0.5 indicate the concept is relevant to the target. The paper’s statistical significance test against CAVs fit on random labels is experiment protocol and is shown in examples/utilization/0_layer/5_tcav.py.

Main reference: Kim et al. “Interpretability Beyond Feature Attribution: Quantitative Testing with Concept Activation Vectors (TCAV)”, ICML 2018. https://proceedings.mlr.press/v80/kim18d

Note: the sensitivity follows the paper’s definition (gradient of the target output). The official TCAV code differentiates the softmax cross-entropy loss of the target class instead; to reproduce it exactly, pass a head returning minus that loss per sample.

Parameters:

  • embeddings (torch.Tensor) – Activations of shape (batch_size, n_features) of the examples to test, at the layer where the CAVs were fit.

  • head (Callable) – The part of the model downstream of these activations, mapping (batch_size, n_features) embeddings to outputs of shape (batch_size, n_outputs) or (batch_size,). The output is the explanandum (e.g. a task class or a downstream concept) — distinct from the cavs concepts being tested. The head must process samples independently for the per-sample gradients to be exact — put modules that mix the batch (e.g. BatchNorm) in eval mode.

  • cavs (torch.Tensor) – Concept activation vectors of shape (n_concepts, n_features), e.g. CAVEmbeddingToConcept.cavs.

  • target (Union[int, str, Tuple[str, str]]) – Which column of the head output to differentiate. An integer indexes it directly; ignored if the head output is 1-dimensional. A string names a single-column (binary/continuous) concept; a (concept, state) pair names one state logit of a categorical concept. Names are resolved against the head output’s annotation, which requires head to return an AnnotatedTensor (e.g. via a Sequential with out_concepts). Default is 0.

Returns:

TCAV scores in [0, 1] of shape (n_concepts,).

Return type:

torch.Tensor