Note

Click here to download the full example code or to run this example in your browser via Binder

08. Convert iEEG data to BIDS format¶

In this example, we use MNE-BIDS to create a BIDS-compatible directory of iEEG data. Specifically, we will follow these steps:

Download some iEEG data.
Load the data, extract information, and save in a new BIDS directory.
Check the result and compare it with the standard.
Cite MNE-BIDS.
Repeat the process for the fsaverage template coordinate frame.

The iEEG data will be written by write_raw_bids() with the addition of extra metadata elements in the following files:

the sidecar file ieeg.json
electrodes.tsv
coordsystem.json
events.tsv
channels.tsv

Compared to EEG data, the main differences are within the coordsystem.json and electrodes.tsv files. For more information on these files, refer to the iEEG part of the BIDS specification.

# Authors: Adam Li <adam2392@gmail.com>
#          Stefan Appelhoff <stefan.appelhoff@mailbox.org>
#          Alex Rockhill <aprockhill@mailbox.org>
#
# License: BSD-3-Clause

import os.path as op
import shutil

from nilearn.plotting import plot_anat

import mne
from mne_bids import (BIDSPath, write_raw_bids, write_anat,
                      get_anat_landmarks, read_raw_bids,
                      search_folder_for_text, print_dir_tree)

Step 1: Download the data¶

First, we need some data to work with. We will use the data downloaded via MNE-Python’s datasets API: mne.datasets.misc.data_path()

misc_path = mne.datasets.misc.data_path()

# The electrode coords data are in the tsv file format
# which is easily read in using numpy
raw = mne.io.read_raw_fif(op.join(
    misc_path, 'seeg', 'sample_seeg_ieeg.fif'))
raw.info['line_freq'] = 60  # specify power line frequency as required by BIDS
subjects_dir = op.join(misc_path, 'seeg')  # Freesurfer recon-all directory

Out:

Opening raw data file /Users/hoechenberger/mne_data/MNE-misc-data/seeg/sample_seeg_ieeg.fif...
    Range : 1310640 ... 1370605 =   1311.411 ...  1371.411 secs
Ready.

When the locations of the channels in this dataset were found in Locating Intracranial Electrode Contacts, the T1 was aligned to ACPC. So, this montage is in an ACPC-aligned coordinate system. We can either save the channel positions in the subject’s anatomical space (from their T1 image) or we can transform to a template space such as fsaverage. To save them in the individual space, it is required that the T1 have been aligned to ACPC and then the channel positions be in terms of that coordinate system. Automated alignment to ACPC has not been implemented in MNE yet, so if the channel positions are not in an ACPC-aligned coordinate system, using a template (like fsaverage) is the best option.

# estimate the transformation from "head" to "mri" space
trans = mne.coreg.estimate_head_mri_t('sample_seeg', subjects_dir)

Now let’s convert the montage to “mri”

montage = raw.get_montage()
montage.apply_trans(trans)  # head->mri

BIDS vs MNE-Python Coordinate Systems¶

BIDS has many acceptable coordinate systems for iEEG, which can be viewed in appendix VIII of the BIDS specification. However, MNE-BIDS depends on MNE-Python and MNE-Python does not support all these coordinate systems (yet).

MNE-Python has a few tutorials on this topic:

Currently, MNE-Python supports the mni_tal and mri coordinate frames, corresponding to the fsaverage and ACPC (for an ACPC-aligned T1) BIDS coordinate systems respectively. All other coordinate coordinate frames in MNE-Python if written with mne_bids.write_raw_bids() are written with coordinate system 'Other'. Note, then we suggest using mne_bids.update_sidecar_json() to update the sidecar *_coordsystem.json file to add additional information.

Step 2: Formatting as BIDS¶

Now, let us format the Raw object into BIDS.

With this step, we have everything to start a new BIDS directory using our data. To do that, we can use write_raw_bids() Generally, write_raw_bids() tries to extract as much meta data as possible from the raw data and then formats it in a BIDS compatible way. write_raw_bids() takes a bunch of inputs, most of which are however optional. The required inputs are:

raw
bids_basename
bids_root

… as you can see in the docstring:

print(write_raw_bids.__doc__)

Out:

Save raw data to a BIDS-compliant folder structure.

    .. warning:: * The original file is simply copied over if the original
                   file format is BIDS-supported for that datatype. Otherwise,
                   this function will convert to a BIDS-supported file format
                   while warning the user. For EEG and iEEG data, conversion
                   will be to BrainVision format; for MEG, conversion will be
                   to FIFF.

                 * ``mne-bids`` will infer the manufacturer information
                   from the file extension. If your file format is non-standard
                   for the manufacturer, please update the manufacturer field
                   in the sidecars manually.

    Parameters
    ----------
    raw : mne.io.Raw
        The raw data. It must be an instance of `mne.io.Raw` that is not
        already loaded from disk unless ``allow_preload`` is explicitly set
        to ``True``. See warning for the ``allow_preload`` parameter.
    bids_path : BIDSPath
        The file to write. The `mne_bids.BIDSPath` instance passed here
        **must** have the ``subject``, ``task``, and ``root`` attributes set.
        If the ``datatype`` attribute is not set, it will be inferred from the
        recording data type found in ``raw``. In case of multiple data types,
        the ``.datatype`` attribute must be set.
        Example::

            bids_path = BIDSPath(subject='01', session='01', task='testing',
                                 acquisition='01', run='01', datatype='meg',
                                 root='/data/BIDS')

        This will write the following files in the correct subfolder ``root``::

            sub-01_ses-01_task-testing_acq-01_run-01_meg.fif
            sub-01_ses-01_task-testing_acq-01_run-01_meg.json
            sub-01_ses-01_task-testing_acq-01_run-01_channels.tsv
            sub-01_ses-01_acq-01_coordsystem.json

        and the following one if ``events_data`` is not ``None``::

            sub-01_ses-01_task-testing_acq-01_run-01_events.tsv

        and add a line to the following files::

            participants.tsv
            scans.tsv

        Note that the extension is automatically inferred from the raw
        object.
    events_data : path-like | np.ndarray | None
        Use this parameter to specify events to write to the ``*_events.tsv``
        sidecar file, additionally to the object's `mne.Annotations` (which
        are always written).
        If a path, specifies the location of an MNE events file.
        If an array, the MNE events array (shape: ``(n_events, 3)``).
        If a path or an array and ``raw.annotations`` exist, the union of
        ``event_data`` and ``raw.annotations`` will be written.
        Corresponding descriptions for all event IDs (listed in the third
        column of the MNE events array) must be specified via the ``event_id``
        parameter; otherwise, an exception is raised.
        If ``None``, events will only be inferred from the the raw object's
        `mne.Annotations`.

        .. note::
           If ``not None``, writes the union of ``events_data`` and
           ``raw.annotations``. If you wish to **only** write
           ``raw.annotations``, pass ``events_data=None``. If you want to
           **exclude** the events in ``raw.annotations`` from being written,
           call ``raw.set_annotations(None)`` before invoking this function.

        .. note::
           Descriptions of all event IDs must be specified via the ``event_id``
           parameter.

    event_id : dict | None
        Descriptions of all event IDs, if you passed ``events_data``.
        The descriptions will be written to the ``trial_type`` column in
        ``*_events.tsv``. The dictionary keys correspond to the event
        descriptions and the values to the event IDs. You must specify a
        description for all event IDs in ``events_data``.
    anonymize : dict | None
        If `None` (default), no anonymization is performed.
        If a dictionary, data will be anonymized depending on the dictionary
        keys: ``daysback`` is a required key, ``keep_his`` is optional.

        ``daysback`` : int
            Number of days by which to move back the recording date in time.
            In studies with multiple subjects the relative recording date
            differences between subjects can be kept by using the same number
            of ``daysback`` for all subject anonymizations. ``daysback`` should
            be great enough to shift the date prior to 1925 to conform with
            BIDS anonymization rules.

        ``keep_his`` : bool
            If ``False`` (default), all subject information next to the
            recording date will be overwritten as well. If ``True``, keep
            subject information apart from the recording date.

        ``keep_source`` : bool
            Whether to store the name of the ``raw`` input file in the
            ``source`` column of ``scans.tsv``. By default, this information
            is not stored.

    format : 'auto' | 'BrainVision' | 'EDF' | 'FIF'
        Controls the file format of the data after BIDS conversion. If
        ``'auto'``, MNE-BIDS will attempt to convert the input data to BIDS
        without a change of the original file format. A conversion to a
        different file format (BrainVision, EDF, or FIF) will only take place
        when the original file format lacks some necessary features. Conversion
        can be forced to BrainVision or EDF for (i)EEG, and to FIF for MEG
        data.
    symlink : bool
        Instead of copying the source files, only create symbolic links to
        preserve storage space. This is only allowed when not anonymizing the
        data (i.e., ``anonymize`` must be ``None``).

        .. note::
           Symlinks currently only work with FIFF files. In case of split
           files, only a link to the first file will be created, and
           :func:`mne_bids.read_raw_bids` will correctly handle reading the
           data again.

        .. note::
           Symlinks are currently only supported on macOS and Linux. We will
           add support for Windows 10 at a later time.

    empty_room : BIDSPath | None
        The empty-room recording to be associated with this file. This is
        only supported for MEG data, and only if the ``root`` attributes of
        ``bids_path`` and ``empty_room`` are the same. Pass ``None``
        (default) if you do not wish to specify an associated empty-room
        recording.
    allow_preload : bool
        If ``True``, allow writing of preloaded raw objects (i.e.,
        ``raw.preload`` is ``True``). Because the original file is ignored, you
        must specify what ``format`` to write (not ``auto``).

        .. warning::
            BIDS was originally designed for unprocessed or minimally processed
            data. For this reason, by default, we prevent writing of preloaded
            data that may have been modified. Only use this option when
            absolutely necessary: for example, manually converting from file
            formats not supported by MNE or writing preprocessed derivatives.
            Be aware that these use cases are not fully supported.
    montage : mne.channels.DigMontage | None
        The montage with channel positions if channel position data are
        to be stored in a format other than "head" (the internal MNE
        coordinate frame that the data in ``raw`` is stored in).
    acpc_aligned : bool
        It is difficult to check whether the T1 scan is ACPC aligned which
        means that "mri" coordinate space is "ACPC" BIDS coordinate space.
        So, this flag is required to be True when the digitization data
        is in "mri" for intracranial data to confirm that the T1 is
        ACPC-aligned.
    overwrite : bool
        Whether to overwrite existing files or data in files.
        Defaults to ``False``.

        If ``True``, any existing files with the same BIDS parameters
        will be overwritten with the exception of the ``*_participants.tsv``
        and ``*_scans.tsv`` files. For these files, parts of pre-existing data
        that match the current data will be replaced. For
        ``*_participants.tsv``, specifically, age, sex and hand fields will be
        overwritten, while any manually added fields in ``participants.json``
        and ``participants.tsv`` by a user will be retained.
        If ``False``, no existing data will be overwritten or
        replaced.

    verbose : bool | str | int | None
        Control verbosity of the logging output. If ``None``, use the default
        verbosity level. See the :ref:`logging documentation <tut-logging>` and
        :func:`mne.verbose` for details. Should only be passed as a keyword
        argument.

    Returns
    -------
    bids_path : BIDSPath
        The path of the created data file.

    Notes
    -----
    You should ensure that ``raw.info['subject_info']`` and
    ``raw.info['meas_date']`` are set to proper (not-``None``) values to allow
    for the correct computation of each participant's age when creating
    ``*_participants.tsv``.

    This function will convert existing `mne.Annotations` from
    ``raw.annotations`` to events. Additionally, any events supplied via
    ``events_data`` will be written too. To avoid writing of annotations,
    remove them from the raw file via ``raw.set_annotations(None)`` before
    invoking ``write_raw_bids``.

    To write events encoded in a ``STIM`` channel, you first need to create the
    events array manually and pass it to this function:

    ..
        events = mne.find_events(raw, min_duration=0.002)
        write_raw_bids(..., events_data=events)

    See the documentation of :func:`mne.find_events` for more information on
    event extraction from ``STIM`` channels.

    When anonymizing ``.edf`` files, then the file format for EDF limits
    how far back we can set the recording date. Therefore, all anonymized
    EDF datasets will have an internal recording date of ``01-01-1985``,
    and the actual recording date will be stored in the ``scans.tsv``
    file's ``acq_time`` column.

    ``write_raw_bids`` will generate a ``dataset_description.json`` file
    if it does not already exist. Minimal metadata will be written there.
    If one sets ``overwrite`` to ``True`` here, it will not overwrite an
    existing ``dataset_description.json`` file.
    If you need to add more data there, or overwrite it, then you should
    call :func:`mne_bids.make_dataset_description` directly.

    When writing EDF or BDF files, all file extensions are forced to be
    lower-case, in compliance with the BIDS specification.

    See Also
    --------
    mne.io.Raw.anonymize
    mne.find_events
    mne.Annotations
    mne.events_from_annotations

Let us initialize some of the necessary data for the subject.

# There is a subject, and specific task for the dataset.
subject_id = '1'
task = 'motor'

# get MNE-Python directory w/ example data
mne_data_dir = mne.get_config('MNE_DATASETS_MISC_PATH')

# There is the root directory for where we will write our data.
bids_root = op.join(mne_data_dir, 'ieeg_bids')

To ensure the output path doesn’t contain any leftover files from previous tests and example runs, we simply delete it.

Warning

Do not delete directories that may contain important data!

if op.exists(bids_root):
    shutil.rmtree(bids_root)

Now we just need make a mne_bids.BIDSPath to save the data.

Warning

By passing acpc_aligned=True, we are affirming that the T1 in this dataset is aligned to ACPC. This is very difficult to check with a computer which is why this step is required.

# Now convert our data to be in a new BIDS dataset.
bids_path = BIDSPath(subject=subject_id, task=task, root=bids_root)

# plot T1 to show that it is ACPC-aligned
# note that the origin is centered on the anterior commissure (AC)
# with the y-axis passing through the posterior commissure (PC)
T1_fname = op.join(subjects_dir, 'sample_seeg', 'mri', 'T1.mgz')
fig = plot_anat(T1_fname, cut_coords=(0, 0, 0))
fig.axes['x'].ax.annotate('AC', (2., -2.), (30., -40.), color='w',
                          arrowprops=dict(facecolor='w', alpha=0.5))
fig.axes['x'].ax.annotate('PC', (-31., -2.), (-80., -40.), color='w',
                          arrowprops=dict(facecolor='w', alpha=0.5))

# write ACPC-aligned T1
landmarks = get_anat_landmarks(T1_fname, raw.info, trans,
                               'sample_seeg', subjects_dir)
T1_bids_path = write_anat(T1_fname, bids_path, deface=True,
                          landmarks=landmarks)

# write `raw` to BIDS and anonymize it (converts to BrainVision format)
#
# we need to pass the `montage` argument for coordinate frames other than
# "head" which is what MNE uses internally in the `raw` object
#
# `acpc_aligned=True` affirms that our MRI is aligned to ACPC
# if this is not true, convert to `fsaverage` (see below)!
write_raw_bids(raw, bids_path, anonymize=dict(daysback=30000),
               montage=montage, acpc_aligned=True, overwrite=True)

# check our output
print_dir_tree(bids_root)

Out:

Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/anat/sub-1_T1w.json'...
Opening raw data file /Users/hoechenberger/mne_data/MNE-misc-data/seeg/sample_seeg_ieeg.fif...
    Range : 1310640 ... 1370605 =   1311.411 ...  1371.411 secs
Ready.
/Users/hoechenberger/Development/mne-bids/mne_bids/utils.py:325: RuntimeWarning: `daysback` is too small; the measurement date is after 1925, which is not recommended by BIDS.The minimum `daysback` value for changing the measurement date of this data to before this date is 34624
  warn('`daysback` is too small; the measurement date '
/Users/hoechenberger/Development/mne-bids/mne_bids/write.py:1519: RuntimeWarning: Converting data files to BrainVision format for anonymization
  warn('Converting data files to BrainVision format '
Writing '/Users/hoechenberger/mne_data/ieeg_bids/README'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/participants.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/participants.json'...
/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py:339: RuntimeWarning: Fiducial point nasion not found, assuming identity unknown to head transformation
  raw.set_montage(montage)
Writing electrodes file to... /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_electrodes.tsv
Writing coordsytem file to... /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_coordsystem.json
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-ACPC_electrodes.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-ACPC_coordsystem.json'...
Used Annotations descriptions: ['Fixation', 'Go Cue', 'ISI Onset', 'Response']
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_events.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/dataset_description.json'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_ieeg.json'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_channels.tsv'...
/Users/hoechenberger/Development/mne-bids/mne_bids/write.py:1649: RuntimeWarning: Converting data files to BrainVision format
  warn('Converting data files to BrainVision format')
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/sub-1_scans.tsv'...
Wrote /Users/hoechenberger/mne_data/ieeg_bids/sub-1/sub-1_scans.tsv entry with ieeg/sub-1_task-motor_ieeg.vhdr.
|ieeg_bids/
|--- README
|--- dataset_description.json
|--- participants.json
|--- participants.tsv
|--- sub-1/
|------ sub-1_scans.tsv
|------ anat/
|--------- sub-1_T1w.json
|--------- sub-1_T1w.nii.gz
|------ ieeg/
|--------- sub-1_space-ACPC_coordsystem.json
|--------- sub-1_space-ACPC_electrodes.tsv
|--------- sub-1_task-motor_channels.tsv
|--------- sub-1_task-motor_events.tsv
|--------- sub-1_task-motor_ieeg.eeg
|--------- sub-1_task-motor_ieeg.json
|--------- sub-1_task-motor_ieeg.vhdr
|--------- sub-1_task-motor_ieeg.vmrk

MNE-BIDS has created a suitable directory structure for us, and among other meta data files, it started an events.tsv` and channels.tsv file, and created an initial dataset_description.json file on top!

Now it’s time to manually check the BIDS directory and the meta files to add all the information that MNE-BIDS could not infer. For instance, you must describe iEEGReference and iEEGGround yourself. It’s easy to find these by searching for "n/a" in the sidecar files.

search_folder_for_text('n/a', bids_root)

# Remember that there is a convenient JavaScript tool to validate all your BIDS
# directories called the "BIDS-validator", available as a web version and a
# command line tool:
#
# Web version: https://bids-standard.github.io/bids-validator/
#
# Command line tool: https://www.npmjs.com/package/bids-validator

Out:

sub-1/ieeg/sub-1_task-motor_ieeg.json
      "SoftwareFilters": "n/a",
     "iEEGReference": "n/a",
participants.tsv
  participa age       sex       hand
  sub-1     n/a       n/a       n/a
sub-1/ieeg/sub-1_task-motor_channels.tsv
  name      type      units     low_cutof high_cuto descripti sampling_ status    status_de
  LENT 1    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 2    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 3    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 4    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 5    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 6    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LENT 7    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
  LAMY 1    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
 LAMY 2    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
 LAMY 3    SEEG      V         0.0       499.70605 StereoEEG 999.41210 good      n/a
    ...
sub-1/ieeg/sub-1_space-ACPC_electrodes.tsv
  name      x         y         z         size
  LENT 1    -0.024299 0.0261000 -0.055999 n/a
  LENT 2    -0.026333 0.0271111 -0.054501 n/a
  LENT 3    -0.029499 0.0287999 -0.052000 n/a
  LENT 4    -0.032333 0.0301111 -0.050222 n/a
  LENT 5    -0.034800 0.0309000 -0.048499 n/a
  LENT 6    -0.037222 0.0319999 -0.046777 n/a
  LENT 7    -0.039955 0.0327777 -0.044408 n/a
  LAMY 1    -0.029111 0.0095555 -0.031777 n/a
 LAMY 2    -0.033699 0.0101000 -0.031499 n/a
 LAMY 3    -0.038636 0.0113636 -0.031181 n/a
    ...

Step 3: Load channels from BIDS-formatted dataset and compare¶

Now we have written our BIDS directory. We can use read_raw_bids() to read in the data.

# read in the BIDS dataset to plot the coordinates
raw = read_raw_bids(bids_path=bids_path)

# compare with standard
print('Recovered coordinate: {recovered}\n'
      'Saved coordinate:     {saved}'.format(
          recovered=raw.info['chs'][0]['loc'][:3],
          saved=montage.dig[0]['r']))

Out:

Extracting parameters from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_ieeg.vhdr...
Setting channel info structure...
Reading events from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_events.tsv.
Reading channel info from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_channels.tsv.
Reading in coordinate system frame ACPC: None.
Reading electrode coords from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-ACPC_electrodes.tsv.
--- Logging error ---
Traceback (most recent call last):
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 1083, in emit
    msg = self.format(record)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 927, in format
    return fmt.format(record)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 663, in format
    record.message = record.getMessage()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 367, in getMessage
    msg = msg % self.args
TypeError: not all arguments converted during string formatting
Call stack:
  File "/Users/hoechenberger/miniforge3/envs/mne/bin/sphinx-build", line 10, in <module>
    sys.exit(main())
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 292, in main
    return make_main(argv)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 199, in make_main
    return make_mode.run_make_mode(argv[1:])
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/make_mode.py", line 167, in run_make_mode
    return make.run_generic_build(args[0])
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/make_mode.py", line 155, in run_generic_build
    return build_main(args + opts)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/application.py", line 270, in __init__
    self._init_builder()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/application.py", line 328, in _init_builder
    self.events.emit('builder-inited')
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/events.py", line 101, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_gallery.py", line 438, in generate_gallery_rst
    this_fhindex, this_costs = generate_dir_rst(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 381, in generate_dir_rst
    intro, title, cost = generate_file_rst(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 930, in generate_file_rst
    output_blocks, time_elapsed = execute_script(script_blocks,
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 852, in execute_script
    output_blocks.append(execute_code_block(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 720, in execute_code_block
    is_last_expr, mem_max = _exec_and_get_memory(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 577, in _exec_and_get_memory
    mem_body, _ = gallery_conf['call_memory'](
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_gallery.py", line 206, in call_memory
    return 0., func()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 516, in __call__
    exec(self.code, self.fake_main.__dict__)
  File "/Users/hoechenberger/Development/mne-bids/examples/convert_ieeg_to_bids.py", line 232, in <module>
    raw = read_raw_bids(bids_path=bids_path)
  File "<decorator-gen-586>", line 24, in read_raw_bids
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/read.py", line 722, in read_raw_bids
    _read_dig_bids(electrodes_fname, coordsystem_fname,
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py", line 519, in _read_dig_bids
    montage = _handle_electrodes_reading(electrodes_fpath, coord_frame,
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py", line 42, in _handle_electrodes_reading
    logger.info("The read in electrodes file is: \n", summary_str)
Message: 'The read in electrodes file is: \n'
Arguments: ([('name', ['LENT 1', 'LENT 2', 'LENT 3', 'LENT 4', 'LENT 5', 'LENT 6', 'LENT 7', 'LAMY 1', 'LAMY 2', 'LAMY 3', 'LAMY 4', 'LAMY 5', 'LAMY 6', 'LAMY 7', 'LPHG 1', 'LPHG 2', 'LPHG 3', 'LPHG 4', 'LPHG 5', 'LPHG 6', 'LPHG 7', 'LPLI 1', 'LPLI 2', 'LPLI 3', 'LPLI 4', 'LPLI 5', 'LPLI 6', 'LPLI 7', 'LPLI 8', 'LPLI 9', 'LSTG 1', 'LSTG 2', 'LSTG 3', 'LSTG 4', 'LPIT 1', 'LPIT 2', 'LPIT 3', 'LPIT 4', 'LPIT 5', 'LPIT 6', 'LPIT 7', 'LTPO 3', 'LTPO 4', 'LTPO 5', 'LTPO 6', 'LTPO 7', 'LTPO 8', 'LBRI 1', 'LBRI 2', 'LBRI 3', 'LBRI 4', 'LBRI 5', 'LBRI 6', 'LBRI 7', 'LBRI 8', 'LACN 1', 'LACN 2', 'LACN 3', 'LACN 4', 'LACN 5', 'LACN 6', 'LACN 7', 'LACN 8', 'LOFC 1', 'LOFC 2', 'LOFC 3', 'LOFC 4', 'LOFC 5', 'LOFC 6', 'LOFC 7', 'LOFC 8', 'LOFC 9', 'LPCN 1', 'LPCN 2', 'LPCN 3', 'LPCN 4', 'LPCN 5', 'LPCN 6', 'LPCN 7', 'LSMA 1', 'LSMA 2', 'LSMA 3', 'LSMA 4', 'LSMA 5', 'LSMA 6', 'LSMA 7', 'LSMA 8', 'LSMA 9', 'LSMA 10', 'LSMA 11', 'LSMA 12', 'LSMA 13', 'LSMA 14', 'LSMA 15', 'LSMA 16', 'LPM 1', 'LPM 2', 'LPM 3', 'LPM 5', 'LPM 6', 'LPM 7', 'LPM 8', 'LPM 9', 'LPM 10', 'RAHP 1', 'RAHP 2', 'RAHP 3', 'RAHP 4', 'RAHP 5', 'RAHP 6', 'RAHP 7', 'RAHP 8', 'RPHP 1', 'RPHP 2', 'RPHP 3', 'RPHP 4', 'RPHP 5', 'RPHP 6', 'RPHP 8']), ('x', ['-0.024299999882191146', '-0.026333333104779033', '-0.029499999335220604', '-0.03233333316468336', '-0.034800000710160664', '-0.037222221420963576', '-0.03995555733302174', '-0.02911111162825681', '-0.03369999875821255', '-0.03863636330106878', '-0.044111110610851025', '-0.04910000158453417', '-0.05509999821410432', '-0.06085713921358042', '-0.03588889030183063', '-0.04271428392131963', '-0.048888890475827014', '-0.05588888939857391', '-0.06200000085088368', '-0.06859999899873996', '-0.07255984499528893', '-0.03727272871864064', '-0.04049999965314151', '-0.04390000021908837', '-0.04709091084904533', '-0.050699999447783056', '-0.05455555670977703', '-0.05770000059178943', '-0.061300000166289975', '-0.06450000251580887', '-0.03833333153077167', '-0.0420000018117685', '-0.04499999882985546', '-0.048272727614594085', '-0.02872727256739837', '-0.03266666785746726', '-0.038000000290975756', '-0.04300000101221667', '-0.04841666500366202', '-0.053600000654716255', '-0.05899999830199016', '-0.04283333460949099', '-0.04579999849751943', '-0.048909090700501145', '-0.052333333346339266', '-0.05579999826770925', '-0.05899999888471112', '-0.026475214352481857', '-0.029908604205167402', '-0.03349004816553985', '-0.03669502417835313', '-0.04088888783983187', '-0.04387499947223597', '-0.04749999976098824', '-0.050777776563195355', '-0.007999999641204217', '-0.014111110263399843', '-0.019999999563215694', '-0.02669999917722429', '-0.033777779035282805', '-0.03988888741652198', '-0.046799999089319436', '-0.055090907776706444', '-0.018499999279026656', '-0.022999999248653192', '-0.029200000826516248', '-0.033888890130068905', '-0.039399999100188716', '-0.04322222348544918', '-0.04811111279118807', '-0.05222222268407905', '-0.05709999827845647', '-0.013999999561457116', '-0.01963636352171578', '-0.025499999944969726', '-0.03189999976198406', '-0.03799999870917839', '-0.045000001209483394', '-0.05044444411978344', '-0.03422222045154909', '-0.03412500168323115', '-0.032333332423068004', '-0.031000001110408383', '-0.03044444540711245', '-0.029700001627495455', '-0.02866666738520295', '-0.0281111110346892', '-0.020999999883576138', '-0.01989999988801092', '-0.018700000367011027', '-0.017799999645472346', '-0.0170909096652889', '-0.01655555508579334', '-0.015111110416597406', '-0.015000000122794604', '-0.02999999971687395', '-0.032000000019973426', '-0.03355555659594103', '-0.037000001700679686', '-0.04010000114982487', '-0.04311110944729015', '-0.04416666728935881', '-0.04554545628108573', '-0.04723333518207441', '0.017300000106759514', '0.02188888797404015', '0.027000000705939414', '0.03190000069215284', '0.03688888703209712', '0.042500001021112906', '0.04799999903754554', '0.0528888893587579', '0.01509090873744214', '0.02119999985583394', '0.028199999202244856', '0.03542857087120939', '0.042400000309896636', '0.04966666816729859', '0.06377777729320894']), ('y', ['0.026100000569330768', '0.02711111041783227', '0.02879999917295631', '0.03011111031629913', '0.03090000145109586', '0.031999998824647234', '0.03277777894353416', '0.009555554869889314', '0.010100000470660904', '0.011363636944289483', '0.012000000453194836', '0.013299999828236129', '0.014100000890876131', '0.014571428463699052', '-0.006222222189909598', '-0.007999999935172575', '-0.009555555474586433', '-0.012333333343858558', '-0.014555555532939116', '-0.016100000152251312', '-0.0177830706331854', '0.008727273589759891', '0.007800000838469847', '0.007799999468229589', '0.007454546412764714', '0.006900000649951991', '0.0061111116126119636', '0.006100000350932753', '0.0060000002079887635', '0.005500000053004151', '-0.024666667220420525', '-0.024333333457081812', '-0.023999999566425952', '-0.024000000210152615', '-0.021818181807756087', '-0.02299999996610265', '-0.02409999982053179', '-0.025333333506411385', '-0.026916667276272982', '-0.027999999570054862', '-0.02966666649930827', '-0.038833333336420126', '-0.040399999913512355', '-0.041636363562717466', '-0.04255555568850993', '-0.04309999905641573', '-0.04463636309358276', '0.022777777701310446', '0.022777452044812872', '0.02306618324546316', '0.023015514620540793', '0.02333333253091968', '0.02300000155403975', '0.023900000592756612', '0.02411111131309377', '0.01709999955483449', '0.01833333467232098', '0.02080000028634929', '0.022999998192130167', '0.025333333104252967', '0.028222220642418187', '0.03020000037696042', '0.031454547327689174', '0.06689999819322551', '0.0643000008574873', '0.05969999969449861', '0.05500000261580213', '0.05109999844993053', '0.04688889214065941', '0.04211110815234412', '0.03811110744442094', '0.03409999951363634', '-0.03929999928672145', '-0.04218181814240653', '-0.045833334381780506', '-0.04930000054729992', '-0.052555555626968675', '-0.05622222294774318', '-0.05955555554956268', '0.016888887379338455', '0.01712500098729449', '0.01733333147370198', '0.017099997762264507', '0.01722222120092591', '0.01709999936402537', '0.017111111194514805', '0.016777777090574358', '0.016444446863045813', '0.01630000150081693', '0.015999999016405864', '0.0161999996137319', '0.015727274436139808', '0.015888889874310325', '0.015999998930424718', '0.01509090880838996', '-0.00044444303146437894', '-0.00016666714530336538', '0.0008888888078755451', '0.001111112967201528', '0.0018999988824567222', '0.002888890222141831', '0.003083332502528322', '0.0037272706617296376', '0.004100001694158511', '-0.0011000003662318784', '0.0005555559568463653', '0.0016666665862043219', '0.002800000699788023', '0.004000000489196659', '0.004999999833212435', '0.005699999648874292', '0.006999999991566381', '-0.01945454564465711', '-0.019499999977674216', '-0.020000000127331337', '-0.020571428569710365', '-0.02110000018953696', '-0.021166666605042177', '-0.02277777780597981']), ('z', ['-0.05599999973516251', '-0.054501502018083486', '-0.05200000007140222', '-0.05022222264468077', '-0.04849999954763293', '-0.04677777808705062', '-0.044408408211422216', '-0.03177777834838271', '-0.031499998943250763', '-0.031181818149092617', '-0.030888889246147612', '-0.031000000427943833', '-0.03030000040202633', '-0.030571427888510146', '-0.03411111072032755', '-0.03442857077548962', '-0.033666666597853986', '-0.032333333271199576', '-0.02955555580891328', '-0.02699999946520054', '-0.0250165310272801', '-0.024272727429326735', '-0.023999999582187473', '-0.02419999942907739', '-0.023727273172821355', '-0.023699998897917234', '-0.02322222166322611', '-0.023300000406836132', '-0.02289999907469964', '-0.02260000053306984', '-0.02377777602412823', '-0.021999999998977636', '-0.02085714360828004', '-0.019636362826393014', '-0.03463636414910813', '-0.03411111158520931', '-0.033499999954334184', '-0.03322222284765333', '-0.033083332630675824', '-0.03289999999155021', '-0.03222222235987605', '-0.004500000986147681', '-0.004300000392791291', '-0.0041818185908553615', '-0.004222223122070538', '-0.004399999939586077', '-0.004090908435151898', '-0.006726726345637479', '-0.0053976567767587275', '-0.005229775782218074', '-0.004834376859873063', '-0.003777777867858642', '-0.003124999085773336', '-0.001900001330390949', '-0.0012222209840609954', '0.012500000076540327', '0.014111113306733841', '0.015799999316332747', '0.01790000092526993', '0.019666666556448248', '0.021111111937582264', '0.023100001365817885', '0.024363634226044387', '-0.008899999538957037', '-0.008099999073276618', '-0.006800000139898774', '-0.005111110097082559', '-0.0029000022285921995', '0.0010000015356187233', '0.004888889783726438', '0.008111111813010677', '0.012399998427868889', '-0.009900001139670378', '-0.009909092282012685', '-0.010083331726425983', '-0.010299999140778997', '-0.01033333300129749', '-0.01044444459102313', '-0.010333334366077432', '-0.02300000112814219', '-0.021124999854839725', '-0.01733333341750562', '-0.012999998686169821', '-0.010222224400544308', '-0.006799999313836597', '-0.003666667239758045', '0.00044444365596097574', '0.02788888699796775', '0.03199999941427052', '0.03619999972333955', '0.039100003474433195', '0.041818181384180836', '0.04611111220720475', '0.050000003565436546', '0.05254545425137738', '0.0161111089750767', '0.01833333612131828', '0.02077777546052742', '0.025444441355561925', '0.029599999532890622', '0.033444445829329164', '0.035166665011990256', '0.03772727410737402', '0.04011711509875188', '-0.03550000032253288', '-0.03666666669104199', '-0.03722222182157961', '-0.0380999994132359', '-0.038999999444595125', '-0.03999999983631346', '-0.04089999987812269', '-0.04144444447863954', '-0.03199999950126767', '-0.03110000028481771', '-0.030199999436887767', '-0.02957142821451967', '-0.028599999178362395', '-0.0273333337256656', '-0.026111111402001123']), ('size', ['n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a'])],)
/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py:539: RuntimeWarning: Fiducial point nasion not found, assuming identity unknown to head transformation
  raw.set_montage(montage, on_missing='warn')
Recovered coordinate: [-0.0243  0.0261 -0.056 ]
Saved coordinate:     [-0.0243  0.0261 -0.056 ]

Now we have to go back to “head” coordinates with the head->mri transform.

Note

If you were downloading this from OpenNeuro, you would have to run the Freesurfer recon-all to get the transforms.

montage = raw.get_montage()
# this uses Freesurfer recon-all subject directory
montage.add_estimated_fiducials('sample_seeg', subjects_dir=subjects_dir)
# now the montage is properly in "head" and ready for analysis in MNE
raw.set_montage(montage)

Measurement date	August 29, 1937 11:09:44 GMT
Experimenter	mne_anonymize
Participant	sub-1
Digitized points	122 points
Good channels	119 sEEG
Bad channels	None
EOG channels	Not available
ECG channels	Not available
Sampling frequency	999.41 Hz
Highpass	0.00 Hz
Lowpass	499.71 Hz
Filenames	sub-1_task-motor_ieeg.eeg
Duration	00:01:00 (HH:MM:SS)

Step 4: Cite mne-bids¶

We can see that the appropriate citations are already written in the README. If you are preparing a manuscript, please make sure to also cite MNE-BIDS there.

readme = op.join(bids_root, 'README')
with open(readme, 'r', encoding='utf-8-sig') as fid:
    text = fid.read()
print(text)

Out:

References
----------
Appelhoff, S., Sanderson, M., Brooks, T., Vliet, M., Quentin, R., Holdgraf, C., Chaumon, M., Mikulan, E., Tavabi, K., Höchenberger, R., Welke, D., Brunner, C., Rockhill, A., Larson, E., Gramfort, A. and Jas, M. (2019). MNE-BIDS: Organizing electrophysiological data into the BIDS format and facilitating their analysis. Journal of Open Source Software 4: (1896). https://doi.org/10.21105/joss.01896

Holdgraf, C., Appelhoff, S., Bickel, S., Bouchard, K., D'Ambrosio, S., David, O., … Hermes, D. (2019). iEEG-BIDS, extending the Brain Imaging Data Structure specification to human intracranial electrophysiology. Scientific Data, 6, 102. https://doi.org/10.1038/s41597-019-0105-7

Step 5: Store coordinates in a template space¶

Alternatively, if your T1 is not aligned to ACPC-space or you prefer to store the coordinates in a template space (e.g. fsaverage) for another reason, you can also do that.

Here we’ll use the MNI Talairach transform to get to fsaverage space from “mri” aka surface RAS space. fsaverage is very useful for group analysis as shown in Working with SEEG.

# ensure the output path doesn't contain any leftover files from previous
# tests and example runs
if op.exists(bids_root):
    shutil.rmtree(bids_root)

# load our raw data again
raw = mne.io.read_raw_fif(op.join(
    misc_path, 'seeg', 'sample_seeg_ieeg.fif'))
raw.info['line_freq'] = 60  # specify power line frequency as required by BIDS

# get Talairach transform
mri_mni_t = mne.read_talxfm('sample_seeg', subjects_dir)

Out:

Opening raw data file /Users/hoechenberger/mne_data/MNE-misc-data/seeg/sample_seeg_ieeg.fif...
    Range : 1310640 ... 1370605 =   1311.411 ...  1371.411 secs
Ready.

Now let’s convert the montage to MNI Talairach (“mni_tal”).

montage = raw.get_montage()
montage.apply_trans(trans)  # head->mri
montage.apply_trans(mri_mni_t)

# write to BIDS, this time with a template coordinate system
write_raw_bids(raw, bids_path, anonymize=dict(daysback=30000),
               montage=montage, overwrite=True)

# read in the BIDS dataset
raw = read_raw_bids(bids_path=bids_path)

# check that we can recover the coordinates
print('Recovered coordinate: {recovered}\n'
      'Saved coordinate:     {saved}'.format(
          recovered=raw.info['chs'][0]['loc'][:3],
          saved=montage.dig[0]['r']))

Out:

Opening raw data file /Users/hoechenberger/mne_data/MNE-misc-data/seeg/sample_seeg_ieeg.fif...
    Range : 1310640 ... 1370605 =   1311.411 ...  1371.411 secs
Ready.
/Users/hoechenberger/Development/mne-bids/mne_bids/utils.py:325: RuntimeWarning: `daysback` is too small; the measurement date is after 1925, which is not recommended by BIDS.The minimum `daysback` value for changing the measurement date of this data to before this date is 34624
  warn('`daysback` is too small; the measurement date '
/Users/hoechenberger/Development/mne-bids/mne_bids/write.py:1519: RuntimeWarning: Converting data files to BrainVision format for anonymization
  warn('Converting data files to BrainVision format '
Writing '/Users/hoechenberger/mne_data/ieeg_bids/README'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/participants.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/participants.json'...
/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py:339: RuntimeWarning: Fiducial point nasion not found, assuming identity unknown to head transformation
  raw.set_montage(montage)
Writing electrodes file to... /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_electrodes.tsv
Writing coordsytem file to... /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_coordsystem.json
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-fsaverage_electrodes.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-fsaverage_coordsystem.json'...
Used Annotations descriptions: ['Fixation', 'Go Cue', 'ISI Onset', 'Response']
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_events.tsv'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/dataset_description.json'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_ieeg.json'...
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_channels.tsv'...
/Users/hoechenberger/Development/mne-bids/mne_bids/write.py:1649: RuntimeWarning: Converting data files to BrainVision format
  warn('Converting data files to BrainVision format')
Writing '/Users/hoechenberger/mne_data/ieeg_bids/sub-1/sub-1_scans.tsv'...
Wrote /Users/hoechenberger/mne_data/ieeg_bids/sub-1/sub-1_scans.tsv entry with ieeg/sub-1_task-motor_ieeg.vhdr.
Extracting parameters from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_ieeg.vhdr...
Setting channel info structure...
Reading events from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_events.tsv.
Reading channel info from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_task-motor_channels.tsv.
Reading in coordinate system frame fsaverage: None.
Reading electrode coords from /Users/hoechenberger/mne_data/ieeg_bids/sub-1/ieeg/sub-1_space-fsaverage_electrodes.tsv.
--- Logging error ---
Traceback (most recent call last):
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 1083, in emit
    msg = self.format(record)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 927, in format
    return fmt.format(record)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 663, in format
    record.message = record.getMessage()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/logging/__init__.py", line 367, in getMessage
    msg = msg % self.args
TypeError: not all arguments converted during string formatting
Call stack:
  File "/Users/hoechenberger/miniforge3/envs/mne/bin/sphinx-build", line 10, in <module>
    sys.exit(main())
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 292, in main
    return make_main(argv)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 199, in make_main
    return make_mode.run_make_mode(argv[1:])
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/make_mode.py", line 167, in run_make_mode
    return make.run_generic_build(args[0])
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/make_mode.py", line 155, in run_generic_build
    return build_main(args + opts)
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/application.py", line 270, in __init__
    self._init_builder()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/application.py", line 328, in _init_builder
    self.events.emit('builder-inited')
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx/events.py", line 101, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_gallery.py", line 438, in generate_gallery_rst
    this_fhindex, this_costs = generate_dir_rst(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 381, in generate_dir_rst
    intro, title, cost = generate_file_rst(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 930, in generate_file_rst
    output_blocks, time_elapsed = execute_script(script_blocks,
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 852, in execute_script
    output_blocks.append(execute_code_block(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 720, in execute_code_block
    is_last_expr, mem_max = _exec_and_get_memory(
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 577, in _exec_and_get_memory
    mem_body, _ = gallery_conf['call_memory'](
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_gallery.py", line 206, in call_memory
    return 0., func()
  File "/Users/hoechenberger/miniforge3/envs/mne/lib/python3.9/site-packages/sphinx_gallery/gen_rst.py", line 516, in __call__
    exec(self.code, self.fake_main.__dict__)
  File "/Users/hoechenberger/Development/mne-bids/examples/convert_ieeg_to_bids.py", line 300, in <module>
    raw = read_raw_bids(bids_path=bids_path)
  File "<decorator-gen-586>", line 24, in read_raw_bids
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/read.py", line 722, in read_raw_bids
    _read_dig_bids(electrodes_fname, coordsystem_fname,
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py", line 519, in _read_dig_bids
    montage = _handle_electrodes_reading(electrodes_fpath, coord_frame,
  File "/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py", line 42, in _handle_electrodes_reading
    logger.info("The read in electrodes file is: \n", summary_str)
Message: 'The read in electrodes file is: \n'
Arguments: ([('name', ['LENT 1', 'LENT 2', 'LENT 3', 'LENT 4', 'LENT 5', 'LENT 6', 'LENT 7', 'LAMY 1', 'LAMY 2', 'LAMY 3', 'LAMY 4', 'LAMY 5', 'LAMY 6', 'LAMY 7', 'LPHG 1', 'LPHG 2', 'LPHG 3', 'LPHG 4', 'LPHG 5', 'LPHG 6', 'LPHG 7', 'LPLI 1', 'LPLI 2', 'LPLI 3', 'LPLI 4', 'LPLI 5', 'LPLI 6', 'LPLI 7', 'LPLI 8', 'LPLI 9', 'LSTG 1', 'LSTG 2', 'LSTG 3', 'LSTG 4', 'LPIT 1', 'LPIT 2', 'LPIT 3', 'LPIT 4', 'LPIT 5', 'LPIT 6', 'LPIT 7', 'LTPO 3', 'LTPO 4', 'LTPO 5', 'LTPO 6', 'LTPO 7', 'LTPO 8', 'LBRI 1', 'LBRI 2', 'LBRI 3', 'LBRI 4', 'LBRI 5', 'LBRI 6', 'LBRI 7', 'LBRI 8', 'LACN 1', 'LACN 2', 'LACN 3', 'LACN 4', 'LACN 5', 'LACN 6', 'LACN 7', 'LACN 8', 'LOFC 1', 'LOFC 2', 'LOFC 3', 'LOFC 4', 'LOFC 5', 'LOFC 6', 'LOFC 7', 'LOFC 8', 'LOFC 9', 'LPCN 1', 'LPCN 2', 'LPCN 3', 'LPCN 4', 'LPCN 5', 'LPCN 6', 'LPCN 7', 'LSMA 1', 'LSMA 2', 'LSMA 3', 'LSMA 4', 'LSMA 5', 'LSMA 6', 'LSMA 7', 'LSMA 8', 'LSMA 9', 'LSMA 10', 'LSMA 11', 'LSMA 12', 'LSMA 13', 'LSMA 14', 'LSMA 15', 'LSMA 16', 'LPM 1', 'LPM 2', 'LPM 3', 'LPM 5', 'LPM 6', 'LPM 7', 'LPM 8', 'LPM 9', 'LPM 10', 'RAHP 1', 'RAHP 2', 'RAHP 3', 'RAHP 4', 'RAHP 5', 'RAHP 6', 'RAHP 7', 'RAHP 8', 'RPHP 1', 'RPHP 2', 'RPHP 3', 'RPHP 4', 'RPHP 5', 'RPHP 6', 'RPHP 8']), ('x', ['-0.023147703651886363', '-0.025283839857033755', '-0.028614249041294178', '-0.03158772841125824', '-0.034165115736783463', '-0.03670646385562226', '-0.03955937066836593', '-0.027594791235471997', '-0.03236035538567651', '-0.03750845772723121', '-0.04319356988582661', '-0.04839721798966959', '-0.054631013836234234', '-0.060603089996348766', '-0.034103376629696265', '-0.04110885048813111', '-0.047447972255757705', '-0.0546020010270751', '-0.06085394582564585', '-0.06763344221466984', '-0.0716767543722731', '-0.03601263657929571', '-0.03932225042348255', '-0.04284028376523644', '-0.046130868723622105', '-0.049847493704913655', '-0.053811612599211335', '-0.05706485387918199', '-0.06078658383423852', '-0.06408164636046684', '-0.036041944061507604', '-0.03984641259296081', '-0.04296111585875924', '-0.046347350311635775', '-0.02619439125418094', '-0.030232687177739442', '-0.03571591546240781', '-0.04085000287523732', '-0.04640403264864777', '-0.051732623646788226', '-0.05726670174845377', '-0.0402435557093603', '-0.04326307180375869', '-0.04644053075124318', '-0.049954235953758544', '-0.05352383249335005', '-0.05678574546435808', '-0.02528836997339358', '-0.02884082346710147', '-0.03255580478066743', '-0.03587037768484493', '-0.04021989827780043', '-0.04329894930914616', '-0.047078468227348465', '-0.050476719916329585', '-0.005988783570101388', '-0.01235133988778301', '-0.018523402212861112', '-0.025526168546366163', '-0.032924118571653484', '-0.039339636592640184', '-0.046553744025255736', '-0.0551724665740325', '-0.018447699651772974', '-0.023020679205523104', '-0.029288662501040466', '-0.03398985309011042', '-0.03956735017514494', '-0.04338725946655661', '-0.04829273492150963', '-0.05241836141615427', '-0.057336827958860574', '-0.010394876724731508', '-0.016134713120152435', '-0.022085105548331038', '-0.028596394591746684', '-0.03480400749543622', '-0.04192972095053406', '-0.04745652405326962', '-0.03311718517526583', '-0.03302399932881963', '-0.031176510720928544', '-0.02978910153287427', '-0.02921795724140338', '-0.028443500419189', '-0.027374412246228948', '-0.026788594065713118', '-0.01941787467929916', '-0.018274756087766294', '-0.017023184703907773', '-0.016098117576139805', '-0.015349085431875058', '-0.014799986712071698', '-0.013308658191379483', '-0.013164418810002514', '-0.028191006141332322', '-0.030269141727405392', '-0.03191226590745878', '-0.03548301943046597', '-0.03871553470962431', '-0.04186249426544656', '-0.04296077800679008', '-0.04440782469439238', '-0.04616602897149815', '0.020767817266558568', '0.025462948873852673', '0.030715892899674458', '0.03574966063824592', '0.040873266118669135', '0.04664708650630849', '0.052315536859782165', '0.05733250431973923', '0.01906936740296921', '0.025392034294498392', '0.0326510719230745', '0.040148879510525634', '0.04737927487118347', '0.05490040582845708', '0.06955294955500661']), ('y', ['0.009494448243235221', '0.010747561820092998', '0.012841087433091316', '0.014443892464251854', '0.015491525092333145', '0.01686626363628834', '0.017986047085988714', '-0.004743373108852899', '-0.00414692605407342', '-0.0027902085655197462', '-0.002097503659082017', '-0.0007587796306668792', '0.00015770659848042545', '0.0006025950383560519', '-0.021649274342110378', '-0.023577244360474085', '-0.025128946555706157', '-0.027892800983241976', '-0.02988172265718285', '-0.03118857767759784', '-0.03270891363962837', '-0.0046551047532606485', '-0.0056025877533007334', '-0.0056376621749860455', '-0.005947402145751195', '-0.006536195661522422', '-0.007313099937426751', '-0.007343214175915011', '-0.007405546251031804', '-0.007900309210606554', '-0.0396920468827263', '-0.03911913122476624', '-0.038627394586533026', '-0.03847654947877443', '-0.03809121423657051', '-0.03927512723060957', '-0.04036549869623533', '-0.04163867424522669', '-0.0432989566346347', '-0.04442729173878937', '-0.04610472781656266', '-0.052075725558813166', '-0.05370405914651417', '-0.05499628897462972', '-0.055976698902935974', '-0.05658128338585721', '-0.05816413197643698', '0.012433015010061202', '0.012597240441886702', '0.012913214659407984', '0.012903171154947357', '0.013364190390883718', '0.013091249039119414', '0.0141876651598057', '0.014489458953822783', '0.009025410252984574', '0.010516071606307595', '0.013313772322751596', '0.01588275663279321', '0.018547350207008352', '0.02175631458352921', '0.02407666658694179', '0.02553849723931654', '0.05854492287303875', '0.05590484073422668', '0.05122348446838773', '0.04649180178846831', '0.0426670025919972', '0.03874026896942184', '0.034213667690354464', '0.030419524368738737', '0.02675101769791878', '-0.05319568028808208', '-0.056240647045853756', '-0.0601167765653312', '-0.06380557255244745', '-0.06724774278502235', '-0.07113454198606671', '-0.07463786766225418', '0.004097457625063281', '0.004590795962164553', '0.005309749280098372', '0.005634037026647614', '0.006126798216096763', '0.006447310426835736', '0.006870988254181082', '0.0070590960848564265', '0.01031228542754786', '0.010700358511159318', '0.010936806639021796', '0.011528188058713805', '0.011388246284207095', '0.012120268645629971', '0.012748822808859089', '0.01212610266516566', '-0.009000946105436052', '-0.008423983395687396', '-0.006999337258411951', '-0.006165269102720269', '-0.00480146422870285', '-0.003267846836804627', '-0.0028412979310595146', '-0.0018336444489945973', '-0.0011341634562997676', '-0.016306972716842692', '-0.01470720845165668', '-0.013598487009333709', '-0.01250905217608524', '-0.011352216952677366', '-0.010417017241299103', '-0.009784363245730175', '-0.008476242324381307', '-0.03514721331657693', '-0.03506135030418204', '-0.03545089395244239', '-0.03595036532882054', '-0.036360684281139616', '-0.03624617523925823', '-0.037742750158978565']), ('z', ['-0.05183359460588243', '-0.05047501573015003', '-0.048207655257041376', '-0.046619435510000265', '-0.04497682699889046', '-0.04340181075387471', '-0.04107624234755524', '-0.022778390466105705', '-0.022597526253922827', '-0.02252975600716557', '-0.02235155104618733', '-0.02274276777050384', '-0.02217144447910572', '-0.022550131439274167', '-0.02179582027681986', '-0.021733072933795443', '-0.020585174736606454', '-0.01857017372543246', '-0.01515904517478371', '-0.012127814066912808', '-0.009671826145326854', '-0.014698376355467642', '-0.014205506103876468', '-0.014410448044692702', '-0.01383371722489623', '-0.013679119044125927', '-0.012999810424485966', '-0.013074284363298957', '-0.01262662633288726', '-0.012197871728333242', '-0.0069288010555816505', '-0.005127080429740321', '-0.003993675774381358', '-0.002705606744890508', '-0.018973998365500927', '-0.01815938418647786', '-0.017270138150980253', '-0.016702795523101874', '-0.0162048127589235', '-0.015769001843894473', '-0.014686600088534117', '0.016413354505750974', '0.016968160205620843', '0.017365508002423844', '0.017527833844906478', '0.017464515395551505', '0.01812775683645915', '0.0006758917544064189', '0.002078088569855221', '0.0021973953224466124', '0.0026288992006117014', '0.003676861395166214', '0.004439875912258013', '0.0055375870122976205', '0.00620916368398131', '0.022086488416033508', '0.023521492444044854', '0.024770210958185823', '0.026510132703070573', '0.02787137047535286', '0.028771892637621657', '0.03044359399174934', '0.03151216815712135', '-0.011196688584901743', '-0.009784655773775306', '-0.007410432739920125', '-0.004608125849451155', '-0.0014293385676374826', '0.003589351116288433', '0.008720997235853276', '0.012981982295955083', '0.018367602490153866', '0.010794815286274437', '0.011419433087887725', '0.012037888539151746', '0.012572462360966548', '0.013253432901994967', '0.013943278322589112', '0.014791924119001982', '-0.01513686365456282', '-0.013217676269591831', '-0.009280705813397601', '-0.004677888392277592', '-0.0017858969711355335', '0.0018361595012149883', '0.005125211253563735', '0.009517382082103308', '0.03842221947154943', '0.04277255469803235', '0.04724991636280847', '0.05025295537436438', '0.05321120162249208', '0.057687069365786305', '0.061747858184451825', '0.06462020374651212', '0.029723481543052613', '0.03200179324021583', '0.03434415034556366', '0.03920579944852436', '0.04340676679293252', '0.04723721659196162', '0.049006658815112694', '0.05156017125914732', '0.05399355014982837', '-0.024449404920125456', '-0.02604195290510526', '-0.026874878467477666', '-0.028050949596746498', '-0.02926498231339321', '-0.030541666753819696', '-0.03164797015468725', '-0.03250987171752812', '-0.016783937712690156', '-0.015837632464431775', '-0.014794048239785832', '-0.01402058079916657', '-0.012895681956291953', '-0.011561203555164297', '-0.009948805314876805']), ('size', ['n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a', 'n/a'])],)
/Users/hoechenberger/Development/mne-bids/mne_bids/dig.py:539: RuntimeWarning: Fiducial point nasion not found, assuming identity unknown to head transformation
  raw.set_montage(montage, on_missing='warn')
Recovered coordinate: [-0.0231477   0.00949445 -0.05183359]
Saved coordinate:     [-0.0231477   0.00949445 -0.05183359]

Now we should go back to “head” coordinates. We do this with fsaverage fiducials which are in MNI space. In this case, you would not need to run the Freesurfer recon-all for the subject, you would just need a subjects_dir with fsaverage in it, which is accessible using mne.datasets.fetch_fsaverage().

montage = raw.get_montage()
# add fiducials for "mni_tal" (which is the coordinate frame fsaverage is in)
# so that it can properly be set to "head"
montage.add_mni_fiducials(subjects_dir=subjects_dir)

# Many other templates are included in the Freesurfer installation,
# so, for those, the fiducials can be estimated with
# ``montage.add_estimated_fiducials(template, os.environ['FREESURFER_HOME'])``
# where ``template`` maybe be ``cvs_avg35_inMNI152`` for instance
raw.set_montage(montage)

Measurement date	August 29, 1937 11:09:44 GMT
Experimenter	mne_anonymize
Participant	sub-1
Digitized points	122 points
Good channels	119 sEEG
Bad channels	None
EOG channels	Not available
ECG channels	Not available
Sampling frequency	999.41 Hz
Highpass	0.00 Hz
Lowpass	499.71 Hz
Filenames	sub-1_task-motor_ieeg.eeg
Duration	00:01:00 (HH:MM:SS)

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

Gallery generated by Sphinx-Gallery

07. Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS

09. Storing empty room data in BIDS format