mne-tools / mne-tools/mne-python
Add laplace reference method to mne/io/reference.py
Open
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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