cosanlab / cosanlab/nltools

Probabilistic SRM initialises its noise trace from uncentred data (brainiak parity kept for 0.6.0)

Open
#539 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
130
Forks
48
Avg merge
6h 42m
Merged PRs (30d)
34

Description

`_SRM._init_structures` (`nltools/algorithms/alignment/srm.py:274-276`) computes each subject's `trace_xtx` on the raw data and then centres the data for the EM loop, so the noise variance `rho2` is initialised from the uncentred sum of squares while every later step uses the centred data. Adding a constant to every voxel (which the model centres away) changes the estimated noise twenty-fold on a two-subject fixture and rescales the shared response.

This is a byte-for-byte port of BrainIAK's `funcalign/srm.py`; upstream's own docstring describes `trace_xtx` as the squared Frobenius norm of the *demeaned* data while its code uses the raw data. The 0.6.0 hygiene sweep (#535) confirmed the arithmetic, and the decision on 2026-09-13 was to keep numerical parity with brainiak and v0.5.1 for 0.6.0 rather than diverge from the reference implementation published results were produced with.

Fix when taken up: centre once and use the centred array for both the trace and the EM data; the property-based tests in `nltools/tests/core/test_srm.py` pass either way. Add a migration-guide row and a changelog line naming the divergence from brainiak. Reproduction script and analysis: the area H verification report from #535 (`_SRM(n_features=1)._init_structures([np.array([[1.0, 3.0]])], 1)[3]` is `[10.0]` today; the centred value is `[2.0]`).

Contributor guide

Open the contributing guide

Research direction

Read _SRM._init_structures in nltools/algorithms/alignment/srm.py:274-276 and run the reported [1.0, 3.0] reproduction, then inspect nltools/tests/core/test_srm.py. Done means the trace and EM loop use centred data, with a migration-guide row and changelog entry documenting the BrainIAK parity divergence.

Written by the indexing model from the issue text.

Assessment

Tech stack
numpy, python
Domain
machine-learning
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.