mne-tools / mne-tools/mne-python

ENH: Add support for tracking arbitrary sensor transformation matrices

Open
#13,227 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
3.5k
Forks
1.6k
Avg merge
1d 6h
Merged PRs (30d)
100

Description

In FieldTrip / SPM there is a notion of a tra matrix, which is "whatever transformation has been applied to the sensor space data" (could be ICA, SSP/projections, reference sensor synthetic gradiometry, or really any arbitrary transformation). It is important to keep track of this transformation because during source imaging the forward matrix needs to have the same transformation applied. In MNE we currently have:

  1. comp matrices, which are usually used for CTF systems and have to do with gradient compensation
  2. proj matrices, which are used for SSP vectors and set a null space

So this enhancement proposal is to add support for transformation matrices, which are arbitrary arrays of shape (n_ch, n_ch). Implementation-wise, it would require:

  1. adding a new FIF constant for this matrix
  2. adding an interface for adding them, e.g., raw.apply_transformation(transformation, picks=None) or raw.add_transformation (advantages/disadvantages to both we can discuss later) that applies it (probably no option to delay like projectors in the first iteration) and attaches it as a new info["transformation"] or similar
  3. modifying our channel-picking code to prohibit picking channels when such a transformation has been applied and picking would lead to losing mixed channels (e.g., if your transformation was a fully-nonzero matrix but just for MEG channels, you couldn't .pick(["MEG 0111"]) but you could .pick("eeg") or .pick("meg"))
  4. modifying our forward sol prep code to support applying it just like we do for info["comp"] and info["projs"]

A few good motivations for this:

  1. Facilitate interoperability with FT/SPM
  2. Facilitate use with other preprocessing techniques
  3. Better accounting of our own preprocessing. In particular I'm thinking that ica.apply should set this value. Currently we assume that during source imaging our pre-whitening step takes care of any distortions caused by ica.apply(inst), but this would help ensure it.

@agramfort any thoughts on this, having worked with ICA and source imaging and also understanding a bit our fwd/inv code? I don't forsee this adding too much complexity but maybe I'm missing something.

cc @britta-wstnr @schoffelen in case I (inevitably) missed something from our discussion

Some other details discussed that probably make sense

We could start by allowing transformation to be any matrix (easiest). Then we could look at whether it's actually a projection, and add it as proj; or if it is rank-deficient, decomposing into a projection part and a non-projection-part via SVD, which would have the advantage of working nicely with our existing proj code.

Simple unit tests could be written to start by having transformation just be a permutation of sensors (i.e., transformation = np.eye(n_ch)[rng.permutation(n_ch)] should give identical imaging results as unpermuted data.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the channel-picking code, forward-solution preparation, and ICA application paths mentioned in the issue. Review how info["comp"] and info["projs"] are handled, then determine the interface and FIF representation needed for arbitrary transformations. Done means transformations are stored, applied consistently to data and forward matrices, and protected against channel picks that lose mixed channels, with permutation-based imaging tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.