Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
c3cd407
Add unified cebra datasets and session masking
CeliaBenquet Dec 9, 2025
17e0c6c
Fix matplotlib colormap deprecation warnings for 3.11 compatibility (…
vovw Sep 15, 2025
aa00659
Remove pkg resources (#272)
vovw Sep 24, 2025
994cbbe
Update README.md (#261)
MMathisLab Sep 24, 2025
eaa3291
Merge remote-tracking branch 'origin/main' into celia/unfied-xcebra
CeliaBenquet Oct 1, 2026
68b3ce7
Enhance Jacobian computation and multi-objective training support
CeliaBenquet Oct 1, 2026
d869d70
Add random tie-breaking option to UnifiedSampler and related classes
CeliaBenquet Oct 2, 2026
da1822f
Update UnifiedSampler and related classes to enable random tie-breaki…
CeliaBenquet Oct 23, 2026
1e8c6d8
Refactor code by removing prints, cleaning dataset class methods, upd…
CeliaBenquet Nov 12, 2026
f0dd150
Modify checkpoint loading to support numpy scalars
CeliaBenquet Nov 12, 2026
e1281ee
Optimize Jacobian regularization and add masking functionalities
CeliaBenquet Nov 12, 2026
8a9a52e
Add feature map attribution and update documentation
CeliaBenquet Nov 13, 2026
e578253
Refactor documentation and type hints
CeliaBenquet Nov 13, 2026
73f996a
Remove dataset classes; update documentation for clarity
CeliaBenquet Nov 13, 2026
f5f12c1
Remove MLPDecoder class and related imports from sklearn decoder
CeliaBenquet Nov 13, 2026
4e3cd77
Refactor attribution models to import Captum classes only when needed…
CeliaBenquet Nov 13, 2026
c31391f
Handle masks so that instance owned
CeliaBenquet Nov 13, 2026
fb82865
Refactor dtype handling in safe globals to support NumPy<1.25
CeliaBenquet Nov 13, 2026
4e21ca9
Add scheduler state handling in checkpointing and loading
CeliaBenquet Nov 13, 2026
592a2e7
Add scheduler step handling in solver classes and tests
CeliaBenquet Nov 13, 2026
cd8a6bc
Add tests for resampling models to ignore batch size in transformations
CeliaBenquet Nov 13, 2026
e502c92
Remove unified_time_delta distribution handling from ContrastiveMulti…
CeliaBenquet Nov 13, 2026
659097b
Enhance Jacobian computation tests with dropout and training mode han…
CeliaBenquet Nov 13, 2026
4e8edf3
Update UnifiedContrastiveMultiObjectiveLoader to utilize time_delta f…
CeliaBenquet Nov 13, 2026
a3593e0
Refactor jacobian test to use local keys and update learning rate sch…
CeliaBenquet Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cebra/attribution/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,4 @@

from cebra.attribution.attribution_models import *
from cebra.attribution.jacobian_attribution import *
from cebra.attribution.feature_map import *
89 changes: 62 additions & 27 deletions cebra/attribution/_jacobian.py
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ def compute_jacobian(
double_precision: bool = False,
convert_to_numpy: bool = True,
hybrid_solver: bool = False,
output_batch_size: int | None = None,
) -> Union[torch.Tensor, np.ndarray]:
"""Compute the Jacobian matrix for a given model and input.

Expand All @@ -97,42 +98,76 @@ def compute_jacobian(
double_precision: If True, use double precision
convert_to_numpy: If True, convert output to numpy array
hybrid_solver: If True, concatenate multiple outputs along dimension 1
output_batch_size: Optional number of output/latent dimensions to process
per autograd chunk. If ``None``, process all outputs in one retained
graph as before. Smaller values reduce peak GPU memory for
deterministic evaluation-mode models.

Returns:
Jacobian matrix as either PyTorch tensor or numpy array
"""
if double_precision:
model = model.to("cpu").double()
input_vars = tensors_to_cpu_and_double(input_vars)
if hybrid_solver:
output = model(*input_vars)
output_vars = torch.cat(output, dim=1).to("cpu").double()
if output_batch_size is not None and int(output_batch_size) <= 0:
raise ValueError(
f"output_batch_size must be positive when provided, got {output_batch_size}."
)

def _prepare_model_and_inputs():
if double_precision:
prepared_model = model.to("cpu").double()
prepared_inputs = tensors_to_cpu_and_double(input_vars)
else:
output_vars = model(*input_vars).to("cpu").double()
else:
model = model.to(cuda_device).float()
input_vars = tensors_to_cuda(input_vars, cuda_device=cuda_device)
prepared_model = model.to(cuda_device).float()
prepared_inputs = tensors_to_cuda(input_vars, cuda_device=cuda_device)
return prepared_model, prepared_inputs

def _forward_outputs(prepared_model, prepared_inputs):
if hybrid_solver:
output = model(*input_vars)
output_vars = torch.cat(output, dim=1)
else:
output_vars = model(*input_vars)
output = prepared_model(*prepared_inputs)
if double_precision:
return torch.cat(output, dim=1).to("cpu").double()
return torch.cat(output, dim=1)
if double_precision:
return prepared_model(*prepared_inputs).to("cpu").double()
return prepared_model(*prepared_inputs)

if mode == "autograd":
jacob = []
for i in range(output_vars.shape[1]):
grads = torch.autograd.grad(
output_vars[:, i:i + 1],
input_vars,
retain_graph=True,
create_graph=False,
grad_outputs=torch.ones(output_vars[:, i:i + 1].shape).to(
output_vars.device),
)
jacob.append(torch.cat(grads, dim=1))

jacobian = torch.stack(jacob, dim=1)
prepared_model, prepared_inputs = _prepare_model_and_inputs()
output_vars = _forward_outputs(prepared_model, prepared_inputs)
n_outputs = int(output_vars.shape[1])
effective_output_batch_size = (
n_outputs
if output_batch_size is None or any(
module.training for module in prepared_model.modules())
else min(int(output_batch_size), n_outputs)
)

jacob_chunks = []
for output_start in range(0, n_outputs, effective_output_batch_size):
output_end = min(output_start + effective_output_batch_size, n_outputs)
if output_start > 0:
output_vars = _forward_outputs(prepared_model, prepared_inputs)

chunk_rows = []
for local_idx, output_idx in enumerate(range(output_start, output_end)):
is_last_in_chunk = local_idx == (output_end - output_start - 1)
grads = torch.autograd.grad(
output_vars[:, output_idx : output_idx + 1],
prepared_inputs,
retain_graph=not is_last_in_chunk,
create_graph=False,
grad_outputs=torch.ones(
output_vars[:, output_idx : output_idx + 1].shape,
device=output_vars.device,
),
)
chunk_rows.append(torch.cat(grads, dim=1).detach().cpu())
del grads

jacob_chunks.append(torch.stack(chunk_rows, dim=1))
del chunk_rows
del output_vars

jacobian = torch.cat(jacob_chunks, dim=1)

jacobian = jacobian.detach().cpu()

Expand Down
176 changes: 160 additions & 16 deletions cebra/attribution/attribution_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,46 @@
import dataclasses
import time

import cvxpy as cp
import numpy as np
import scipy.linalg
import sklearn.metrics
import torch
import torch.nn as nn
import tqdm
from captum.attr import NeuronFeatureAblation
from captum.attr import NeuronGradient
from captum.attr import NeuronGradientShap
from captum.attr import NeuronIntegratedGradients

import cebra
import cebra.attribution._jacobian
from cebra.attribution import register


_VALID_ATTRIBUTION_RESULT_KEYS = {
"jf",
"jf-convabs",
"jf-inv-lsq",
"jf-inv-svd",
"jf-convabs-inv-lsq",
"jf-convabs-inv-svd",
}


def _normalize_selected_result_keys(selected_keys):
"""Map names as a set (``_`` read as ``-``), or ``None``; raise on unknown names."""
if selected_keys is None:
return None
normalized = []
for key in selected_keys:
key_str = str(key).strip().replace("_", "-")
if not key_str:
continue
if key_str not in _VALID_ATTRIBUTION_RESULT_KEYS:
raise ValueError(
f"Unknown attribution result key {key!r}. "
f"Valid keys: {sorted(_VALID_ATTRIBUTION_RESULT_KEYS)}"
)
normalized.append(key_str)
return set(normalized)


@dataclasses.dataclass
class AttributionMap:
"""Base class for computing attribution maps for CEBRA models.
Expand Down Expand Up @@ -255,6 +278,7 @@ def _inverse_lsq_cvxpy(matrix: np.ndarray,
Returns:
np.ndarray: Least squares inverse matrix
"""
import cvxpy as cp

matrix_param = cp.Parameter((matrix.shape[0], matrix.shape[1]))
matrix_param.value = matrix
Expand Down Expand Up @@ -324,7 +348,7 @@ def _reduce(full_jacobian):
class JFMethodBased(AttributionMap):
"""Compute the attribution map using the Jacobian of the model encoder."""

def _compute_jacobian(self, input_data):
def _compute_jacobian(self, input_data, output_batch_size=None):
return cebra.attribution._jacobian.compute_jacobian(
self.model,
input_vars=[input_data],
Expand All @@ -333,22 +357,28 @@ def _compute_jacobian(self, input_data):
double_precision=False,
convert_to_numpy=True,
hybrid_solver=False,
output_batch_size=output_batch_size,
)

def compute_attribution_map(self):
def compute_attribution_map(self, selected_keys=None):
selected_keys = _normalize_selected_result_keys(selected_keys)

full_jacobian = self._compute_jacobian(self.input_data)

result = {}
for key, value in self._reduce_attribution_map({
'jf': full_jacobian
}).items():
result[key] = value
if selected_keys is None or key in selected_keys:
result[key] = value
for method in ['lsq', 'svd']:
inv_key = f"{key}-inv-{method}"
if selected_keys is not None and inv_key not in selected_keys:
continue
print(f"Computing inverse for {key} with method {method}")
result[f"{key}-inv-{method}"], result[
f'time_inversion_{method}'] = self._inverse(value,
method=method)
result[inv_key], result[f'time_inversion_{method}'] = self._inverse(
value, method=method
)
# result[f"{key}-inv-{method}-conditions"] = self.check_moores_penrose_conditions(value, result[f"{key}-inv-{method}"])

return result
Expand All @@ -363,7 +393,8 @@ class JFMethodBasedBatched(JFMethodBased):
:py:class:`JFMethodBased`
"""

def compute_attribution_map(self, batch_size=1024):
def compute_attribution_map(self, batch_size=1024, selected_keys=None):
selected_keys = _normalize_selected_result_keys(selected_keys)
if batch_size > self.input_data.shape[0]:
raise ValueError(
f"Batch size ({batch_size}) is bigger than data ({self.input_data.shape[0]})"
Expand All @@ -380,12 +411,117 @@ def compute_attribution_map(self, batch_size=1024):
for key, value in self._reduce_attribution_map({
'jf': full_jacobian
}).items():
result[key] = value
if selected_keys is None or key in selected_keys:
result[key] = value
for method in ['lsq', 'svd']:
inv_key = f"{key}-inv-{method}"
if selected_keys is not None and inv_key not in selected_keys:
continue
result[inv_key], result[f'time_inversion_{method}'] = self._inverse(
value, method=method
)

return result

result[f"{key}-inv-{method}"], result[
f'time_inversion_{method}'] = self._inverse(value,
method=method)

@dataclasses.dataclass
@register("jacobian-based-batched-optimized")
class JFMethodBasedBatchedOptimized(JFMethodBased):
"""Jacobian-based attribution computed in mini-batches, with an optional running mean.

Same results as ``jacobian-based-batched``, with less memory.
"""

def compute_attribution_map(
self,
batch_size=1024,
return_full=True,
selected_keys=None,
latent_batch_size=None,
):
"""Compute the attribution maps.

Args:
batch_size: Samples per Jacobian batch.
return_full: Return one map per sample. If ``False``, return the mean over samples.
selected_keys: Maps to compute, e.g. ``["jf"]``. ``None``: all of them.
latent_batch_size: Embedding dimensions per autograd pass. ``None``: all at once.

Returns:
Dict from map name to array, ``(T, D, N)`` per sample or ``(D, N)`` averaged.
"""
selected_keys = _normalize_selected_result_keys(selected_keys)
if batch_size > self.input_data.shape[0]:
raise ValueError(
f"Batch size ({batch_size}) is bigger than data ({self.input_data.shape[0]})"
)

input_data_batches = torch.split(self.input_data, batch_size)
keys = sorted(_VALID_ATTRIBUTION_RESULT_KEYS if selected_keys is None else selected_keys)

if return_full:
per_key_chunks = {key: [] for key in keys}
running_sums = None
total_samples = None
else:
per_key_chunks = None
running_sums = {key: None for key in keys}
total_samples = 0

time_inversion = {'lsq': 0.0, 'svd': 0.0}

for input_data_batch in input_data_batches:
jacobian_batch = self._compute_jacobian(
input_data_batch, output_batch_size=latent_batch_size
)
reduced_batch = self._reduce_attribution_map({'jf': jacobian_batch})
batch_samples = next(iter(reduced_batch.values())).shape[0]

for key, value in reduced_batch.items():
if selected_keys is None or key in selected_keys:
if return_full:
per_key_chunks[key].append(value)
else:
if running_sums[key] is None:
running_sums[key] = value.sum(axis=0)
else:
running_sums[key] += value.sum(axis=0)

for method in ['lsq', 'svd']:
inv_key = f"{key}-inv-{method}"
if selected_keys is not None and inv_key not in selected_keys:
continue
inv_value, dt = self._inverse(value, method=method)
if return_full:
per_key_chunks[inv_key].append(inv_value)
else:
if running_sums[inv_key] is None:
running_sums[inv_key] = inv_value.sum(axis=0)
else:
running_sums[inv_key] += inv_value.sum(axis=0)

time_inversion[method] += dt

if not return_full:
total_samples += batch_samples

del jacobian_batch
del reduced_batch

if return_full:
result = {
key: np.concatenate(chunks, axis=0)
for key, chunks in per_key_chunks.items()
}
else:
result = {
key: value / float(total_samples)
for key, value in running_sums.items()
}
result['num_samples'] = int(total_samples)

result['time_inversion_lsq'] = time_inversion['lsq']
result['time_inversion_svd'] = time_inversion['svd']

return result

Expand All @@ -402,6 +538,8 @@ class NeuronGradientMethod(AttributionMap):

def __post_init__(self):
super().__post_init__()
from captum.attr import NeuronGradient

self.captum_model = NeuronGradient(forward_func=self.model,
layer=self.model)

Expand Down Expand Up @@ -476,6 +614,8 @@ class FeatureAblationMethod(AttributionMap):

def __post_init__(self):
super().__post_init__()
from captum.attr import NeuronFeatureAblation

self.captum_model = NeuronFeatureAblation(forward_func=self.model,
layer=self.model)

Expand Down Expand Up @@ -549,6 +689,8 @@ class IntegratedGradientsMethod(AttributionMap):

def __post_init__(self):
super().__post_init__()
from captum.attr import NeuronIntegratedGradients

self.captum_model = NeuronIntegratedGradients(forward_func=self.model,
layer=self.model)

Expand Down Expand Up @@ -631,6 +773,8 @@ class NeuronGradientShapMethod(AttributionMap):

def __post_init__(self):
super().__post_init__()
from captum.attr import NeuronGradientShap

self.captum_model = NeuronGradientShap(forward_func=self.model,
layer=self.model)

Expand Down
Loading
Loading