mne-tools / mne-tools/mne-python

Add laplace reference method to mne/io/reference.py

Open
#10,163 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Add Laplace reference method to mne/io/reference.py

@verbose
def set_laplace_reference(inst, central_ch, adjacent_chs, copy=True,
verbose=None):
"""Re-reference selected seeg channels using a laplace referencing scheme.

A Laplace reference takes the difference between one central channel with 
the average of adjacent channels. The exception, however, is for the top 
and bottom electrodes in the seeg-shaft, where only one adjacent electrode 
is subtracted (actually, the average of two same adjacent channels).  

Multiple central channels and adjacent channels can be specified.    

Parameters
----------
inst : instance of Raw | Epochs | Evoked
    Data containing the unreferenced channels.
central_ch : str | list of str
    The name(s) of the channel(s) to use as central channel(s) in the 
    laplace reference.
adjacent_chs : list of strs
    The name(s) of the channel(s) to use as adjacent channels in the 
    laplace reference.    
copy : bool
    Whether to operate on a copy of the data (True) or modify it in-place
    (False). Defaults to True.
%(verbose)s

Returns
-------
inst : instance of Raw | Epochs | Evoked
    Data with the specified channels re-referenced.

For example,
-----------
central_ch=['A1','A2','A3']
adjacent_chs = [['A1','A1'],['A1','A3'],['A2','A2']]

See Also
--------
set_eeg_reference : Convenience function for creating an EEG reference.

Reference
---------
Li, G., Jiang, S., Paraskevopoulou, S.E., Wang, M., Xu, Y., Wu, Z., ...
& Schalk,G.(2018).Optimal referencing for stereo-electroencephalographic
(SEEG) recordings. NeuroImage, 183, 327-335.

"""
_check_can_reref(inst)
if not isinstance(central_ch, list):
    central_ch = [central_ch]

if not isinstance(adjacent_chs, list):
    raise ValueError('Adjacent channels are a list of at least two' 
                     'adjacent channels! ')

if len(central_ch) != len(adjacent_chs):
    raise ValueError('Number of central channels (got %d) must equal '
                     'the number of adjacent groups of channels (got %d).' 
                     % (len(central_ch), len(adjacent_chs)))
if copy:
    inst = inst.copy()

# Do laplace reference by multiplying the data(channels x time) with
# a matrix (n_central_channels x channels).
multiplier = np.zeros((len(central_ch), len(inst.ch_names)))
for idx, (a, c) in enumerate(zip(central_ch, adjacent_chs)):
    multiplier[idx, inst.ch_names.index(a)] = 1
    adjacent_ch_n = len(c)
    for i in range(adjacent_ch_n):
        multiplier[idx, inst.ch_names.index(c[i])] += -1/adjacent_ch_n        

# Rereferencing of data.
data = multiplier @ inst._data
inst._data = data

return inst

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 in mne/io/reference.py at the proposed set_laplace_reference entry point and compare it with the existing set_eeg_reference API. Confirm the documented central and adjacent-channel cases, then verify that the returned Raw, Epochs, or Evoked data has the requested Laplace reference applied.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.