01. Label Anatomy of Electrodes¶

When working with intracranial electrophysiological data in the BIDS format, we usually have

iEEG (ECoG and SEEG)
the anatomical MRI scan of a study participant
the CT scan of the study participant with iEEG electrodes implanted

In this tutorial, we show how label_elecs_anat can be used to quickly and easily label anatomy of electrodes.

We assume that you have already localized the electrodes and coregistered them over to the T1w image FreeSurfer space.

# Authors: Adam Li <adam2392@gmail.com>
#
# License: BSD (3-clause)

Step 1: Imports¶

We are importing everything we need for this example:

from pathlib import Path

import pandas as pd
from mne_bids import BIDSPath, print_dir_tree, make_report

from seek_localize import label_elecs_anat, fs_lut_fpath

We will be using the testing dataset, which is already stored in BIDS format and stored with the seek-localize repository.

bids_root = Path.cwd() / Path("../data/")
fs_root = bids_root / "derivatives" / "freesurfer"

Step 2: Explore the dataset contents¶

We can use MNE-BIDS to print a tree of all included files and folders. We pass the max_depth parameter to mne_bids.print_dir_tree to the output to three levels of folders, for better readability in this example.

print_dir_tree(bids_root, max_depth=3)

Out:

|data/
|--- .bidsignore
|--- dataset_description.json
|--- participants.json
|--- participants.tsv
|--- derivatives/
|------ fieldtrip/
|--------- stolk/
|------ freesurfer/
|--------- sub-la02/
|--------- sub-test/
|--- sub-la02/
|------ ses-presurgery/
|--------- anat/
|--------- ct/
|--------- ieeg/
|--- sub-test/
|------ anat/
|--------- sub-test_space-fs_T1w.nii
|------ ieeg/
|--------- sub-test_acq-seeg_space-fs_coordsystem.json
|--------- sub-test_acq-seeg_space-fs_electrodes.json
|--------- sub-test_acq-seeg_space-fs_electrodes.tsv

We can even ask MNE-BIDS to produce a human-readable summary report on the dataset contents.

print(make_report(bids_root))

Out:

Summarizing participants.tsv /home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/participants.tsv...
/home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/label_anatomy_channels.py:63: RuntimeWarning: No *scans.tsv files found. Currently, we do not generate a report without the scans.tsv files.
  print(make_report(bids_root))
The participant template found: comprised of 0 men and 2 women;
comprised of 2 right hand, 0 left hand and 0 ambidextrous; ages all unknown
The Test-Dataset dataset was created with BIDS version 1.4.0 by Adam Li. This
report was generated with MNE-BIDS (https://doi.org/10.21105/joss.01896). The
dataset consists of 2 participants (comprised of 0 men and 2 women; comprised of
2 right hand, 0 left hand and 0 ambidextrous; ages all unknown)and 1 recording
sessions: presurgery.

Step 3: Label the anatomy of electrodes¶

Now it’s time to get ready for labeling some of the data! First, we need to create a mne_bids.BIDSPath(), which will point to the corresponding *electrodes.tsv file.

subject = "la02"
session = "presurgery"
acquisition = "seeg"
space = "fs"
suffix = "electrodes"
extension = ".tsv"
datatype = "ieeg"
bids_path = BIDSPath(
    root=bids_root,
    datatype=datatype,
    subject=subject,
    session=session,
    acquisition=acquisition,
    space=space,
    suffix=suffix,
    extension=extension,
)

# the full file path to the electrodes.tsv file
print(bids_path.fpath)

Out:

/home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/ieeg/sub-la02_ses-presurgery_acq-seeg_space-fs_electrodes.tsv

The necessary iEEG files are the sub-la02_ses-presurgery_acq-seeg_space-fs_electrodes.tsv, sub-la02_ses-presurgery_acq-seeg_space-fs_coordsystem.json files. Note these are co-occurring files in iEEG-BIDS (one present requires the other to be present).

coordsystem_fpath = bids_path.copy().update(suffix="coordsystem", extension=".json")
print(coordsystem_fpath.fpath)

Out:

/home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/ieeg/sub-la02_ses-presurgery_acq-seeg_space-fs_coordsystem.json

Let’s explore the contents of the current electrodes.tsv file. Note that the current data already has the atlas labels, so we pretend they are not there and only read in the bare minimum columns.

elec_df = pd.read_csv(
    bids_path, sep="\t", index_col=None, usecols=["name", "x", "y", "z"]
)
print(elec_df)

Out:

    name          x          y          z
  L'1  -1.095576  66.539884  35.287211
  L'2  -3.804778  67.947332  35.308774
  L'3  -7.318944  67.799889  35.474825
  L'4 -10.587486  67.266380  36.440106
  L'5 -13.942345  68.679315  36.434484
..   ...        ...        ...        ...
X'12 -36.646198  31.289810  63.267809
X'13 -40.097632  31.247037  64.402526
X'14 -43.652207  31.929346  65.398302
X'15 -46.536866  32.208883  66.400773
X'16 -50.232055  32.901193  67.544440

[88 rows x 4 columns]

The necessary imaging files are the sub-la02_ses-presurgery_space-fs_T1w.nii file, which the electrode coordinates are assumed to be in.

atlas_img_fpath = fs_root / f"sub-{subject}" / "mri" / "aparc+aseg.mgz"

Now let’s label the anatomy! Note: seek_localize.fs_lut_fpath provides the file path to a local FreeSurferColorLUT.txt file.

elec_df = label_elecs_anat(bids_path, atlas_img_fpath, fs_lut_fpath=fs_lut_fpath)

print(elec_df)

Out:

Loading lookup table for freesurfer labels: ../seek_localize/templates/FreeSurferColorLUT.txt
SETTING COORDINATE SYSTEM AS MRI by default if coordinatesystem is "other".
<Sensors | 9 non-empty values
 ch_names: L'1, L'2, L'3, L'4, L'5, L'6, L'7, L'8, L'11, L'12, L'13, L'14, ...
 coord_system: mri
 coord_unit: mm
 coordsystem_fname: /home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/ieeg/sub-la02_ses-presurgery_acq-seeg_space-fs_coordsystem.json
 elecs_fname: /home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/ieeg/sub-la02_ses-presurgery_acq-seeg_space-fs_electrodes.tsv
 intended_for: /home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/anat/sub-la02_ses-presurgery_space-fs_T1w.nii
 x: 88 items (list)
 y: 88 items (list)
 z: 88 items (list)
>
Converting to voxel mri space because electrodes are in mm space.
Converting coordinates from mm to voxel using /home/docs/checkouts/readthedocs.org/user_builds/seek-localize/checkouts/latest/examples/../data/sub-la02/ses-presurgery/anat/sub-la02_ses-presurgery_space-fs_T1w.nii.
Labeling electrodes...
E0, Vox CRS: [128 124 188], Label #ctx-lh-superiorfrontal
E1, Vox CRS: [131 124 190], Label #ctx-lh-superiorfrontal
E2, Vox CRS: [134 124 189], Label #ctx-lh-superiorfrontal
E3, Vox CRS: [137 123 189], Label #ctx-lh-superiorfrontal
E4, Vox CRS: [141 123 190], Label #ctx-lh-superiorfrontal
E5, Vox CRS: [144 123 190], Label #Left-Cerebral-White-Matter
E6, Vox CRS: [148 123 191], Label #Left-Cerebral-White-Matter
E7, Vox CRS: [152 123 192], Label #Left-Cerebral-White-Matter
E8, Vox CRS: [162 122 193], Label #Left-Cerebral-White-Matter
E9, Vox CRS: [166 122 194], Label #ctx-lh-rostralmiddlefrontal
E10, Vox CRS: [168 122 194], Label #ctx-lh-rostralmiddlefrontal
E11, Vox CRS: [172 121 195], Label #Unknown
E12, Vox CRS: [127 104 177], Label #Unknown
E13, Vox CRS: [130 103 177], Label #ctx-lh-superiorfrontal
E14, Vox CRS: [133 102 177], Label #Unknown
E15, Vox CRS: [136 101 177], Label #ctx-lh-superiorfrontal
E16, Vox CRS: [140 100 178], Label #Left-Cerebral-White-Matter
E17, Vox CRS: [143 100 178], Label #ctx-lh-superiorfrontal
E18, Vox CRS: [147  99 179], Label #ctx-lh-superiorfrontal
E19, Vox CRS: [155 122 192], Label #ctx-lh-rostralmiddlefrontal
E20, Vox CRS: [158 122 193], Label #ctx-lh-rostralmiddlefrontal
E21, Vox CRS: [151  98 179], Label #ctx-lh-rostralmiddlefrontal
E22, Vox CRS: [153  98 180], Label #ctx-lh-rostralmiddlefrontal
E23, Vox CRS: [157  97 180], Label #ctx-lh-rostralmiddlefrontal
E24, Vox CRS: [161  96 180], Label #ctx-lh-rostralmiddlefrontal
E25, Vox CRS: [165  95 181], Label #Unknown
E26, Vox CRS: [126 138 185], Label #ctx-rh-medialorbitofrontal
E27, Vox CRS: [130 138 186], Label #ctx-lh-rostralanteriorcingulate
E28, Vox CRS: [134 138 187], Label #ctx-lh-rostralanteriorcingulate
E29, Vox CRS: [137 138 187], Label #Unknown
E30, Vox CRS: [141 138 187], Label #ctx-lh-medialorbitofrontal
E31, Vox CRS: [144 138 187], Label #Left-Cerebral-White-Matter
E32, Vox CRS: [148 138 187], Label #Left-Cerebral-White-Matter
E33, Vox CRS: [151 137 188], Label #Left-Cerebral-White-Matter
E34, Vox CRS: [155 138 189], Label #Left-Cerebral-White-Matter
E35, Vox CRS: [158 138 189], Label #ctx-lh-rostralmiddlefrontal
E36, Vox CRS: [162 138 190], Label #ctx-lh-rostralmiddlefrontal
E37, Vox CRS: [165 138 191], Label #ctx-lh-rostralmiddlefrontal
E38, Vox CRS: [169 138 191], Label #ctx-lh-rostralmiddlefrontal
E39, Vox CRS: [172 138 191], Label #ctx-lh-rostralmiddlefrontal
E40, Vox CRS: [129 154 165], Label #ctx-rh-medialorbitofrontal
E41, Vox CRS: [133 153 166], Label #ctx-lh-medialorbitofrontal
E42, Vox CRS: [137 152 166], Label #ctx-lh-medialorbitofrontal
E43, Vox CRS: [140 152 167], Label #ctx-lh-lateralorbitofrontal
E44, Vox CRS: [143 151 168], Label #Left-Cerebral-White-Matter
E45, Vox CRS: [147 150 168], Label #ctx-lh-lateralorbitofrontal
E46, Vox CRS: [150 149 168], Label #Unknown
E47, Vox CRS: [153 149 169], Label #ctx-lh-lateralorbitofrontal
E48, Vox CRS: [157 148 169], Label #ctx-lh-lateralorbitofrontal
E49, Vox CRS: [160 147 169], Label #Left-Cerebral-White-Matter
E50, Vox CRS: [164 146 170], Label #ctx-lh-lateralorbitofrontal
E51, Vox CRS: [167 146 170], Label #ctx-lh-lateralorbitofrontal
E52, Vox CRS: [170 145 171], Label #ctx-lh-parsorbitalis
E53, Vox CRS: [174 144 171], Label #ctx-lh-parsorbitalis
E54, Vox CRS: [178 144 171], Label #ctx-lh-parsorbitalis
E55, Vox CRS: [179 144 171], Label #Unknown
E56, Vox CRS: [127 124 175], Label #Unknown
E57, Vox CRS: [130 124 175], Label #ctx-lh-rostralanteriorcingulate
E58, Vox CRS: [133 124 177], Label #ctx-lh-rostralanteriorcingulate
E59, Vox CRS: [137 124 177], Label #ctx-lh-rostralanteriorcingulate
E60, Vox CRS: [140 124 178], Label #Left-Cerebral-White-Matter
E61, Vox CRS: [144 123 178], Label #Left-Cerebral-White-Matter
E62, Vox CRS: [147 123 178], Label #Left-Cerebral-White-Matter
E63, Vox CRS: [151 123 178], Label #Left-Cerebral-White-Matter
E64, Vox CRS: [154 123 179], Label #Left-Cerebral-White-Matter
E65, Vox CRS: [158 123 179], Label #ctx-lh-rostralmiddlefrontal
E66, Vox CRS: [161 123 180], Label #Unknown
E67, Vox CRS: [165 123 180], Label #ctx-lh-parstriangularis
E68, Vox CRS: [168 123 180], Label #Left-Cerebral-White-Matter
E69, Vox CRS: [171 123 181], Label #Left-Cerebral-White-Matter
E70, Vox CRS: [176 123 181], Label #Left-Cerebral-White-Matter
E71, Vox CRS: [178 123 182], Label #ctx-lh-parstriangularis
E72, Vox CRS: [127 109 150], Label #Unknown
E73, Vox CRS: [129 108 150], Label #ctx-lh-caudalanteriorcingulate
E74, Vox CRS: [133 106 150], Label #Left-Cerebral-White-Matter
E75, Vox CRS: [137 105 151], Label #Left-Cerebral-White-Matter
E76, Vox CRS: [141 104 151], Label #Left-Cerebral-White-Matter
E77, Vox CRS: [144 103 151], Label #Left-Cerebral-White-Matter
E78, Vox CRS: [147 102 151], Label #Left-Cerebral-White-Matter
E79, Vox CRS: [150 101 152], Label #Left-Cerebral-White-Matter
E80, Vox CRS: [154  99 152], Label #Left-Cerebral-White-Matter
E81, Vox CRS: [157  98 152], Label #Left-Cerebral-White-Matter
E82, Vox CRS: [159  97 152], Label #ctx-lh-caudalmiddlefrontal
E83, Vox CRS: [163  96 153], Label #ctx-lh-caudalmiddlefrontal
E84, Vox CRS: [167  95 153], Label #ctx-lh-caudalmiddlefrontal
E85, Vox CRS: [170  94 154], Label #ctx-lh-caudalmiddlefrontal
E86, Vox CRS: [173  93 154], Label #ctx-lh-caudalmiddlefrontal
E87, Vox CRS: [177  92 154], Label #Unknown
    name          x  ...                     destrieux            desikan-killiany
0    L'1  -1.095576  ...                       Unknown      ctx-lh-superiorfrontal
1    L'2  -3.804778  ...            ctx_lh_G_front_sup      ctx-lh-superiorfrontal
2    L'3  -7.318944  ...            ctx_lh_G_front_sup      ctx-lh-superiorfrontal
3    L'4 -10.587486  ...    Left-Cerebral-White-Matter      ctx-lh-superiorfrontal
4    L'5 -13.942345  ...            ctx_lh_G_front_sup      ctx-lh-superiorfrontal
..   ...        ...  ...                           ...                         ...
83  X'12 -36.646198  ...  ctx_lh_S_precentral-inf-part  ctx-lh-caudalmiddlefrontal
84  X'13 -40.097632  ...  ctx_lh_S_precentral-inf-part  ctx-lh-caudalmiddlefrontal
85  X'14 -43.652207  ...         ctx_lh_G_front_middle  ctx-lh-caudalmiddlefrontal
86  X'15 -46.536866  ...         ctx_lh_G_front_middle  ctx-lh-caudalmiddlefrontal
87  X'16 -50.232055  ...                       Unknown                     Unknown

[88 rows x 6 columns]

Total running time of the script: ( 0 minutes 0.643 seconds)

Gallery generated by Sphinx-Gallery