From 4f64c581ea701524c9f4b53ff3b5655f06e504b8 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Mon, 23 Sep 2019 10:18:30 -0400 Subject: [PATCH 01/27] DOC: Restore I/O content via new "tutorials" --- doc/_includes/data_formats.rst | 80 ------- doc/conf.py | 1 + doc/overview/implementation.rst | 62 +---- tutorials/io/README.txt | 5 + tutorials/io/plot_10_reading_meg_data.py | 276 +++++++++++++++++++++++ tutorials/io/plot_20_reading_eeg_data.py | 160 +++++++++++++ 6 files changed, 448 insertions(+), 136 deletions(-) delete mode 100644 doc/_includes/data_formats.rst create mode 100644 tutorials/io/README.txt create mode 100644 tutorials/io/plot_10_reading_meg_data.py create mode 100644 tutorials/io/plot_20_reading_eeg_data.py diff --git a/doc/_includes/data_formats.rst b/doc/_includes/data_formats.rst deleted file mode 100644 index 8fdf86be6f3..00000000000 --- a/doc/_includes/data_formats.rst +++ /dev/null @@ -1,80 +0,0 @@ -:orphan: - -Supported data formats -====================== - -.. NOTE: part of this file is included in doc/manual/io.rst and - doc/overview/implementation.rst. Changes here are reflected there. If you - want to link to this content, link to :ref:`manual-data-formats` for the - manual or :ref:`data-formats` for the implementation page. The next line is - a target for :start-after: so we can omit the title above: - data-formats-begin-content - -When MNE-Python loads sensor data, the data are stored in a Python object of -type :class:`mne.io.Raw`. Specialized loading functions are provided for the -raw data file formats from a variety of equipment manufacturers. All raw data -input/output functions in MNE-Python are found in :mod:`mne.io` and start -with :samp:`read_raw_{*}`; see the documentation for each reader function for -more info on reading specific file types. - -As seen in the table below, there are also a few formats defined by other -neuroimaging analysis software packages that are supported (EEGLAB, -FieldTrip). Like the equipment-specific loading functions, these will also -return an object of class :class:`~mne.io.Raw`; additional functions are -available for reading data that has already been epoched or averaged (see -table). - -.. NOTE: To include only the table, here's a different target for :start-after: - data-formats-begin-table - -.. cssclass:: table-bordered -.. rst-class:: midvalign - -============ ============= ========= =================================== -Data type File format Extension MNE-Python function -============ ============= ========= =================================== -MEG Artemis123 .bin :func:`mne.io.read_raw_artemis123` - -MEG 4-D .dir :func:`mne.io.read_raw_bti` - Neuroimaging - / BTi - -MEG CTF .dir :func:`mne.io.read_raw_ctf` - -MEG Elekta .fif :func:`mne.io.read_raw_fif` - Neuromag - -MEG KIT .sqd :func:`mne.io.read_raw_kit`, - :func:`mne.read_epochs_kit` - - -MEG and EEG FieldTrip .mat :func:`mne.io.read_raw_fieldtrip`, - :func:`mne.read_epochs_fieldtrip`, - :func:`mne.read_evoked_fieldtrip` - -EEG Brainvision .vhdr :func:`mne.io.read_raw_brainvision` - -EEG Biosemi data .bdf :func:`mne.io.read_raw_bdf` - format - -EEG Neuroscan CNT .cnt :func:`mne.io.read_raw_cnt` - -EEG European data .edf :func:`mne.io.read_raw_edf` - format - -EEG EEGLAB .set :func:`mne.io.read_raw_eeglab`, - :func:`mne.read_epochs_eeglab` - -EEG EGI simple .egi :func:`mne.io.read_raw_egi` - binary - -EEG EGI MFF .mff :func:`mne.io.read_raw_egi` - format - -EEG eXimia .nxe :func:`mne.io.read_raw_eximia` - -EEG General data .gdf :func:`mne.io.read_raw_gdf` - format - -EEG Nicolet .data :func:`mne.io.read_raw_nicolet` -============ ============= ========= =================================== diff --git a/doc/conf.py b/doc/conf.py index be930397633..15c1a7bbcdc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -475,6 +475,7 @@ def reset_warnings(gallery_conf, fname): '../examples/datasets/', '../tutorials/intro/', '../tutorials/raw/', + '../tutorials/io/', '../tutorials/preprocessing/', '../tutorials/epochs/', '../tutorials/evoked/', diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index 809c525cba5..032c41940cd 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -3,65 +3,15 @@ Implementation details ====================== -This page describes some of the technical details of MNE-Python implementation. - -.. contents:: Page contents - :local: - :depth: 2 - - -.. _units: - -Internal representation (units) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_includes/units.rst - :start-after: units-begin-content - - -.. _precision: - -Floating-point precision -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_includes/precision.rst - :start-after: precision-begin-content - - -.. _channel-types: - -Supported channel types -^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_includes/channel_types.rst - :start-after: channel-types-begin-content - - -.. _data-formats: - -Supported data formats -^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_includes/data_formats.rst - :start-after: data-formats-begin-content - - -.. _dig-formats: - -Supported formats for digitized 3D locations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_includes/dig_formats.rst - :start-after: dig-formats-begin-content - - -Mathematics and algorithms -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For more detailed information about mathematics and algorithms in MNE, see: +This page links to information about some of the technical details of +MNE-Python implementation. .. toctree:: + ../_includes/units.rst + ../_includes/precision.rst + ../_includes/channel_types.rst + ../_includes/dig_formats.rst algorithms/channel_interpolation.rst algorithms/time_frequency.rst algorithms/maxwell.rst diff --git a/tutorials/io/README.txt b/tutorials/io/README.txt new file mode 100644 index 00000000000..541fd51ad00 --- /dev/null +++ b/tutorials/io/README.txt @@ -0,0 +1,5 @@ +Reading data for different recording systems +============================================ + +These tutorials cover the basics of loading EEG/MEG data into MNE-Python +for various recording devices. diff --git a/tutorials/io/plot_10_reading_meg_data.py b/tutorials/io/plot_10_reading_meg_data.py new file mode 100644 index 00000000000..4b63ff5fa93 --- /dev/null +++ b/tutorials/io/plot_10_reading_meg_data.py @@ -0,0 +1,276 @@ +# -*- coding: utf-8 -*- +r""" +.. _tut-imorting-meg-data: + +=============================== +Importing data from MEG devices +=============================== + +This section describes how to read data for various MEG manufacturers. + +.. contents:: Page contents + :local: + :depth: 2 + +Elekta NeuroMag (.fif) +====================== + +Neuromag Raw FIF files can be loaded using :func:`mne.io.read_raw_fif`. + +If the data were recorded with MaxShield on and have not been processed +with MaxFilter, they may need to be loaded with +``mne.io.read_raw_fif(..., allow_maxshield=True)``. + +Artemis123 (.bin) +================= +MEG data from the Artemis123 system can be read with\ +:func:`mne.io.read_raw_artemis123`. + +4-D Neuroimaging / BTI data (dir) +================================= + +MNE-Python provides :func:`mne.io.read_raw_bti` to read and convert 4D / BTI +data. This reader function will by default replace the original channel names, +typically composed of the letter `A` and the channel number with Neuromag. +To import the data, the following input files are mandatory: + +- A data file (typically c,rfDC) + containing the recorded MEG time series. + +- A hs_file + containing the digitizer data. + +- A config file + containing acquisition information and metadata. + +By default :func:`mne.io.read_raw_bti` assumes that these three files are located +in the same folder. + +.. note:: While reading the reference or compensation channels, + the compensation weights are currently not processed. + As a result, the :class:`mne.io.Raw` object and the corresponding fif + file does not include information about the compensation channels + and the weights to be applied to realize software gradient + compensation. If the data are saved in the Magnes system are already + compensated, there will be a small error in the forward calculations, + whose significance has not been evaluated carefully at this time. + +CTF data (dir) +============== + +The function :func:`mne.io.read_raw_ctf` can be used to read CTF data. + +CTF Polhemus data +----------------- + +The function :func:`mne.channels.read_dig_polhemus_isotrak` can be used to read +Polhemus data. + +Applying software gradient compensation +--------------------------------------- + +Since the software gradient compensation employed in CTF +systems is a reversible operation, it is possible to change the +compensation status of CTF data in the data files as desired. This +section contains information about the technical details of the +compensation procedure and a description of +:func:`mne.io.Raw.apply_gradient_compensation`. + +The raw instances returned by :func:`mne.io.read_raw_ctf` contain several +compensation matrices which are employed to suppress external disturbances +with help of the reference channel data. The reference sensors are +located further away from the brain than the helmet sensors and +are thus measuring mainly the external disturbances rather than magnetic +fields originating in the brain. Most often, a compensation matrix +corresponding to a scheme nicknamed *Third-order gradient +compensation* is employed. + +Let us assume that the data contain :math:`n_1` MEG +sensor channels, :math:`n_2` reference sensor +channels, and :math:`n_3` other channels. +The data from all channels can be concatenated into a single vector + +.. math:: x = [x_1^T x_2^T x_3^T]^T\ , + +where :math:`x_1`, :math:`x_2`, +and :math:`x_3` are the data vectors corresponding +to the MEG sensor channels, reference sensor channels, and other +channels, respectively. The data before and after compensation, +denoted here by :math:`x_{(0)}` and :math:`x_{(k)}`, respectively, +are related by + +.. math:: x_{(k)} = M_{(k)} x_{(0)}\ , + +where the composite compensation matrix is + +.. math:: M_{(k)} = \begin{bmatrix} + I_{n_1} & C_{(k)} & 0 \\ + 0 & I_{n_2} & 0 \\ + 0 & 0 & I_{n_3} + \end{bmatrix}\ . + +In the above, :math:`C_{(k)}` is a :math:`n_1` by :math:`n_2` compensation +data matrix corresponding to compensation "grade" :math:`k`. +It is easy to see that + +.. math:: M_{(k)}^{-1} = \begin{bmatrix} + I_{n_1} & -C_{(k)} & 0 \\ + 0 & I_{n_2} & 0 \\ + 0 & 0 & I_{n_3} + \end{bmatrix}\ . + +To convert from compensation grade :math:`k` to :math:`p` one +can simply multiply the inverse of one compensate compensation matrix +by another and apply the product to the data: + +.. math:: x_{(k)} = M_{(k)} M_{(p)}^{-1} x_{(p)}\ . + +This operation is performed by :meth:`mne.io.Raw.apply_gradient_compensation`. + +KIT MEG system data (.sqd) +========================== + +MNE-Python includes the :func:`mne.io.read_raw_kit` and +:func:`mne.read_epochs_kit` to read and convert KIT MEG data. +This reader function will by default replace the original channel names, +which typically with index starting with zero, with ones with an index starting +with one. + +To import continuous data, only the input .sqd or .con file is needed. For +epochs, an Nx3 matrix containing the event number/corresponding trigger value +in the third column is needed. + +The following input files are optional: + +- A KIT marker file (mrk file) or an array-like containing the locations of + the HPI coils in the MEG device coordinate system. + These data are used together with the elp file to establish the coordinate + transformation between the head and device coordinate systems. + +- A Polhemus points file (elp file) or an array-like + containing the locations of the fiducials and the head-position + indicator (HPI) coils. These data are usually given in the Polhemus + head coordinate system. + +- A Polhemus head shape data file (hsp file) or an array-like + containing locations of additional points from the head surface. + These points must be given in the same coordinate system as that + used for the elp file. + + +.. note:: + The output fif file will use the Neuromag head coordinate system convention, + see :ref:`coordinate_systems`. A coordinate transformation between the + Polhemus head coordinates and the Neuromag head coordinates is included. + +By default, KIT-157 systems assume the first 157 channels are the MEG channels, +the next 3 channels are the reference compensation channels, and channels 160 +onwards are designated as miscellaneous input channels (MISC 001, MISC 002, +etc.). +By default, KIT-208 systems assume the first 208 channels are the MEG channels, +the next 16 channels are the reference compensation channels, and channels 224 +onwards are designated as miscellaneous input channels (MISC 001, MISC 002, +etc.). + +In addition, it is possible to synthesize the digital trigger channel (STI 014) +from available analog trigger channel data by specifying the following +parameters: + +- A list of trigger channels (stim) or default triggers with order: '<' | '>' + Channel-value correspondence when converting KIT trigger channels to a + Neuromag-style stim channel. By default, we assume the first eight + miscellaneous channels are trigger channels. For '<', the largest values are + assigned to the first channel (little endian; default). For '>', the largest + values are assigned to the last channel (big endian). Can also be specified + as a list of trigger channel indexes. +- The trigger channel slope (slope) : '+' | '-' + How to interpret values on KIT trigger channels when synthesizing a + Neuromag-style stim channel. With '+', a positive slope (low-to-high) + is interpreted as an event. With '-', a negative slope (high-to-low) + is interpreted as an event. +- A stimulus threshold (stimthresh) : float + The threshold level for accepting voltage changes in KIT trigger + channels as a trigger event. + +The synthesized trigger channel data value at sample :math:`k` will +be: + +.. math:: s(k) = \sum_{p = 1}^n {t_p(k) 2^{p - 1}}\ , + +where :math:`t_p(k)` are the thresholded +from the input channel data d_p(k): + +.. math:: t_p(k) = \Bigg\{ \begin{array}{l} + 0 \text{ if } d_p(k) \leq t\\ + 1 \text{ if } d_p(k) > t + \end{array}\ . + +The threshold value :math:`t` can +be adjusted with the ``stimthresh`` parameter. + +FieldTrip MEG/EEG data (.mat) +============================= + +MNE-Python includes :func:`mne.io.read_raw_fieldtrip`, :func:`mne.read_epochs_fieldtrip` and :func:`mne.read_evoked_fieldtrip` to read data coming from FieldTrip. + +The data is imported directly from a ``.mat`` file. + +The ``info`` parameter can be explicitly set to ``None``. The import functions will still work but: + +#. All channel locations will be in head coordinates. +#. Channel orientations cannot be guaranteed to be accurate. +#. All channel types will be set to generic types. + +This is probably fine for anything that does not need that information, but if you intent to do things like interpolation of missing channels, source analysis or look at the RMS pairs of planar gradiometers, you most likely run into problems. + +It is **highly recommended** to provide the ``info`` parameter as well. The ``info`` dictionary can be extracted by loading the original raw data file with the corresponding MNE-Python functions:: + + original_data = mne.io.read_raw_fiff('original_data.fif', preload=False) + original_info = original_data.info + data_from_ft = mne.read_evoked_fieldtrip('evoked_data.mat', original_info) + +The imported data can have less channels than the original data. Only the information for the present ones is extracted from the ``info`` dictionary. + +As of version 0.17, importing FieldTrip data has been tested on a variety of systems with the following results: + ++----------+-------------------+-------------------+-------------------+ +| System | Read Raw Data | Read Epoched Data | Read Evoked Data | ++==========+===================+===================+===================+ +| BTI | Works | Untested | Untested | ++----------+-------------------+-------------------+-------------------+ +| CNT | Data imported as | Data imported as | Data imported as | +| | microvolts. | microvolts. | microvolts. | +| | Otherwise fine. | Otherwise fine. | Otherwise fine. | ++----------+-------------------+-------------------+-------------------+ +| CTF | Works | Works | Works | ++----------+-------------------+-------------------+-------------------+ +| EGI | Mostly Ok. Data | Mostly Ok. Data | Mostly Ok. Data | +| | imported as | imported as | imported as | +| | microvolts. | microvolts. | microvolts. | +| | FieldTrip does | FieldTrip does | FieldTrip does | +| | not apply | not apply | not apply | +| | calibration. | calibration. | calibration. | ++----------+-------------------+-------------------+-------------------+ +| KIT | Does not work. | Does not work. | Does not work. | +| | Channel names are | Channel names are | Channel names are | +| | different in | different in | different in | +| | MNE-Python and | MNE-Python and | MNE-Python and | +| | FieldTrip. | FieldTrip. | FieldTrip. | ++----------+-------------------+-------------------+-------------------+ +| Neuromag | Works | Works | Works | ++----------+-------------------+-------------------+-------------------+ +| eximia | Works | Untested | Untested | ++----------+-------------------+-------------------+-------------------+ + +Creating MNE data structures from arbitrary data (from memory) +============================================================== + +Arbitrary (e.g., simulated or manually read in) raw data can be constructed +from memory by making use of :class:`mne.io.RawArray`, :class:`mne.EpochsArray` +or :class:`mne.EvokedArray` in combination with :func:`mne.create_info`. + +This functionality is illustrated in :ref:`ex-array-classes`. Using 3rd party +libraries such as `NEO `__ in +combination with these functions abundant electrophysiological file formats can +be easily loaded into MNE. +""" # noqa:E501 diff --git a/tutorials/io/plot_20_reading_eeg_data.py b/tutorials/io/plot_20_reading_eeg_data.py new file mode 100644 index 00000000000..283c872d399 --- /dev/null +++ b/tutorials/io/plot_20_reading_eeg_data.py @@ -0,0 +1,160 @@ +# -*- coding: utf-8 -*- +r""" +.. _tut-imorting-eeg-data: + +=============================== +Importing data from EEG devices +=============================== + +MNE includes various functions and utilities for reading EEG +data and electrode locations. + +.. contents:: Page contents + :local: + :depth: 2 + + +BrainVision (.vhdr, .vmrk, .eeg) +================================ + +The BrainVision file format consists of three separate files: + +1. A text header file (``.vhdr``) containing meta data +2. A text marker file (``.vmrk``) containing information about events in the + data +3. A binary data file (``.eeg``) containing the voltage values of the EEG + +Both text files are based on the +`Microsoft Windows INI format `_ +consisting of: + +* sections marked as ``[square brackets]`` +* comments marked as ``; comment`` +* key-value pairs marked as ``key=value`` + +A documentation for core BrainVision file format is provided by Brain Products. +You can view the specification +`here `_ + +BrainVision EEG files can be read in using :func:`mne.io.read_raw_brainvision` +with the .vhdr header file as an input. + +.. warning:: Renaming BrainVision files can be problematic due to their + multifile structure. See this + `example `_ + for an instruction. + +European data format (.edf) +=========================== + +EDF and EDF+ files can be read using :func:`mne.io.read_raw_edf`. + +`EDF (European Data Format) `_ and +`EDF+ `_ are 16-bit formats. + +The EDF+ files may contain an annotation channel which can be used to store +trigger information. These annotations are available in ``raw.annotations``. + +Saving EDF files is not supported natively yet. This +`gist `__ +can be used to save any mne.io.Raw into EDF/EDF+/BDF/BDF+. + +BioSemi data format (.bdf) +========================== + +The `BDF format `_ is a 24-bit +variant of the EDF format used by EEG systems manufactured by BioSemi. It can +be imported with :func:`mne.io.read_raw_bdf`. + +BioSemi amplifiers do not perform "common mode noise rejection" automatically. +The signals in the EEG file are the voltages between each electrode and CMS +active electrode, which still contain some CM noise (50 Hz, ADC reference +noise, etc., see `the BioSemi FAQ `__ +for further detail). +Thus, it is advisable to choose a reference (e.g., a single channel like Cz, +average of linked mastoids, average of all electrodes, etc.) on import of +BioSemi data to avoid losing signal information. The data can be re-referenced +later after cleaning if desired. + +.. warning:: The data samples in a BDF file are represented in a 3-byte + (24-bit) format. Since 3-byte raw data buffers are not presently + supported in the fif format these data will be changed to 4-byte + integers in the conversion. + +General data format (.gdf) +========================== + +GDF files can be read in using :func:`mne.io.read_raw_gdf`. + +`GDF (General Data Format) `_ is a flexible +format for biomedical signals that overcomes some of the limitations of the +EDF format. The original specification (GDF v1) includes a binary header +and uses an event table. An updated specification (GDF v2) was released in +2011 and adds fields for additional subject-specific information (gender, +age, etc.) and allows storing several physical units and other properties. +Both specifications are supported in MNE. + +Neuroscan CNT data format (.cnt) +================================ + +CNT files can be read in using :func:`mne.io.read_raw_cnt`. +The channel locations can be read from a montage or the file header. If read +from the header, the data channels (channels that are not assigned to EOG, ECG, +EMG or misc) are fit to a sphere and assigned a z-value accordingly. If a +non-data channel does not fit to the sphere, it is assigned a z-value of 0. + +.. warning:: + Reading channel locations from the file header may be dangerous, as the + x_coord and y_coord in ELECTLOC section of the header do not necessarily + translate to absolute locations. Furthermore, EEG-electrode locations that + do not fit to a sphere will distort the layout when computing the z-values. + If you are not sure about the channel locations in the header, use of a + montage is encouraged. + +EGI simple binary (.egi) +======================== + +EGI simple binary files can be read in using :func:`mne.io.read_raw_egi`. +The EGI raw files are simple binary files with a header and can be exported +from using the EGI Netstation acquisition software. + +EGI MFF (.mff) +============== +These files can also be read with :func:`mne.io.read_raw_egi`. + +EEGLAB set files (.set) +======================= + +EEGLAB .set files can be read in using :func:`mne.io.read_raw_eeglab` +and :func:`mne.read_epochs_eeglab`. + +Nicolet (.data) +=============== +These files can be read with :func:`mne.io.read_raw_nicolet`. + +eXimia EEG data (.nxe) +====================== + +EEG data from the Nexstim eXimia system can be read in using the +:func:`mne.io.read_raw_eximia` function. + +Setting EEG references +====================== + +The preferred method for applying an EEG reference in MNE is +:func:`mne.set_eeg_reference`, or equivalent instance methods like +:meth:`raw.set_eeg_reference() `. By default, +an average reference is used. See :ref:`tut-set-eeg-ref` for more information. + +Reading electrode locations and head shapes for EEG recordings +============================================================== + +Some EEG formats (EGI, EDF/EDF+, BDF) neither contain electrode location +information nor head shape digitization information. Therefore, this +information has to be provided separately. For that purpose all raw instances +have a :meth:`mne.io.Raw.set_montage` method to set electrode locations. + +When using the locations of the fiducial points the digitization data +are converted to the MEG head coordinate system employed in the +MNE software, see :ref:`coordinate_systems`. +""" # noqa:E501 From db1783254d77170f0691471be5895743b4605d80 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Mon, 23 Sep 2019 11:18:47 -0400 Subject: [PATCH 02/27] FIX: Links --- doc/_includes/precision.rst | 2 +- doc/_includes/units.rst | 2 +- tutorials/io/README.txt | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/_includes/precision.rst b/doc/_includes/precision.rst index 0956bc954e9..e4e1887f062 100644 --- a/doc/_includes/precision.rst +++ b/doc/_includes/precision.rst @@ -1,4 +1,4 @@ -:orphan: +.. _precision: Floating-point precision ======================== diff --git a/doc/_includes/units.rst b/doc/_includes/units.rst index 38905989bef..77484fe9331 100644 --- a/doc/_includes/units.rst +++ b/doc/_includes/units.rst @@ -1,4 +1,4 @@ -:orphan: +.. _units: Internal representation (units) =============================== diff --git a/tutorials/io/README.txt b/tutorials/io/README.txt index 541fd51ad00..7b8cbfa1555 100644 --- a/tutorials/io/README.txt +++ b/tutorials/io/README.txt @@ -1,3 +1,5 @@ +.. _data-formats: + Reading data for different recording systems ============================================ From 1eac65d46e6692b5463054cab216cc27dc51b58d Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Mon, 23 Sep 2019 13:29:25 -0400 Subject: [PATCH 03/27] FIX: Fixes after rebase --- doc/_includes/dig_formats.rst | 2 +- doc/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/_includes/dig_formats.rst b/doc/_includes/dig_formats.rst index 9354b873ade..98c6ac7eb36 100644 --- a/doc/_includes/dig_formats.rst +++ b/doc/_includes/dig_formats.rst @@ -1,4 +1,4 @@ -:orphan: +.. _dig-formats: Supported formats for digitized 3D locations ============================================ diff --git a/doc/conf.py b/doc/conf.py index 15c1a7bbcdc..2a8b858d5f1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -474,8 +474,8 @@ def reset_warnings(gallery_conf, fname): '../examples/realtime/', '../examples/datasets/', '../tutorials/intro/', - '../tutorials/raw/', '../tutorials/io/', + '../tutorials/raw/', '../tutorials/preprocessing/', '../tutorials/epochs/', '../tutorials/evoked/', From 646d39f3976a80468f8c5da2828cfb612b3eb913 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 10:39:50 -0700 Subject: [PATCH 04/27] update README --- README.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 4e3cb8ac8ee..7388653d85f 100644 --- a/README.rst +++ b/README.rst @@ -48,10 +48,12 @@ To install the latest stable version of MNE-Python, you can use pip_ in a termin pip install -U mne -**Note** that MNE-Python 0.17 will be the last release to support Python 2. From MNE-Python 0.18, only Python 3 will be supported. +**Note** that MNE-Python 0.17 was the last release to support Python 2. +MNE-Python 0.18 only works under Python 3, and MNE-Python 0.19 requires +Python 3.5 or higher. For more complete instructions and more advanced installation methods (e.g. for -the latest development version), see the `getting started page`_. +the latest development version), see the `installation guide`_. Get the latest code @@ -101,7 +103,7 @@ Contributing to MNE-Python Please see the documentation on the MNE-Python homepage: -https://mne.tools/dev/contributing.html +https://mne.tools/dev/install/contributing.html Mailing list @@ -151,5 +153,5 @@ MNE-Python is **BSD-licenced** (3 clause): .. _MNE-Python software: https://mne.tools/dev/ .. _MNE documentation: https://mne.tools/dev/overview/index.html -.. _getting started page: https://mne.tools/dev/install/index.html +.. _installation guide: https://mne.tools/dev/install/index.html .. _pip: https://pip.pypa.io/en/stable/ From ac91c7800f83d6bf763a61f7fa1b1ece5caadef7 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 10:56:04 -0700 Subject: [PATCH 05/27] move algorithms pages into _includes --- .../algorithms => _includes}/bem_model.rst | 0 .../channel_interpolation.rst | 0 doc/{overview/algorithms => _includes}/forward.rst | 0 .../images/CoordinateSystems.png | Bin .../algorithms => _includes}/images/HeadCS.png | Bin doc/{overview/algorithms => _includes}/inverse.rst | 0 doc/{overview/algorithms => _includes}/maxwell.rst | 0 doc/{overview/algorithms => _includes}/memory.rst | 0 doc/{overview/algorithms => _includes}/morph.rst | 0 doc/{overview/algorithms => _includes}/ssp.rst | 0 .../algorithms => _includes}/time_frequency.rst | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename doc/{overview/algorithms => _includes}/bem_model.rst (100%) rename doc/{overview/algorithms => _includes}/channel_interpolation.rst (100%) rename doc/{overview/algorithms => _includes}/forward.rst (100%) rename doc/{overview/algorithms => _includes}/images/CoordinateSystems.png (100%) rename doc/{overview/algorithms => _includes}/images/HeadCS.png (100%) rename doc/{overview/algorithms => _includes}/inverse.rst (100%) rename doc/{overview/algorithms => _includes}/maxwell.rst (100%) rename doc/{overview/algorithms => _includes}/memory.rst (100%) rename doc/{overview/algorithms => _includes}/morph.rst (100%) rename doc/{overview/algorithms => _includes}/ssp.rst (100%) rename doc/{overview/algorithms => _includes}/time_frequency.rst (100%) diff --git a/doc/overview/algorithms/bem_model.rst b/doc/_includes/bem_model.rst similarity index 100% rename from doc/overview/algorithms/bem_model.rst rename to doc/_includes/bem_model.rst diff --git a/doc/overview/algorithms/channel_interpolation.rst b/doc/_includes/channel_interpolation.rst similarity index 100% rename from doc/overview/algorithms/channel_interpolation.rst rename to doc/_includes/channel_interpolation.rst diff --git a/doc/overview/algorithms/forward.rst b/doc/_includes/forward.rst similarity index 100% rename from doc/overview/algorithms/forward.rst rename to doc/_includes/forward.rst diff --git a/doc/overview/algorithms/images/CoordinateSystems.png b/doc/_includes/images/CoordinateSystems.png similarity index 100% rename from doc/overview/algorithms/images/CoordinateSystems.png rename to doc/_includes/images/CoordinateSystems.png diff --git a/doc/overview/algorithms/images/HeadCS.png b/doc/_includes/images/HeadCS.png similarity index 100% rename from doc/overview/algorithms/images/HeadCS.png rename to doc/_includes/images/HeadCS.png diff --git a/doc/overview/algorithms/inverse.rst b/doc/_includes/inverse.rst similarity index 100% rename from doc/overview/algorithms/inverse.rst rename to doc/_includes/inverse.rst diff --git a/doc/overview/algorithms/maxwell.rst b/doc/_includes/maxwell.rst similarity index 100% rename from doc/overview/algorithms/maxwell.rst rename to doc/_includes/maxwell.rst diff --git a/doc/overview/algorithms/memory.rst b/doc/_includes/memory.rst similarity index 100% rename from doc/overview/algorithms/memory.rst rename to doc/_includes/memory.rst diff --git a/doc/overview/algorithms/morph.rst b/doc/_includes/morph.rst similarity index 100% rename from doc/overview/algorithms/morph.rst rename to doc/_includes/morph.rst diff --git a/doc/overview/algorithms/ssp.rst b/doc/_includes/ssp.rst similarity index 100% rename from doc/overview/algorithms/ssp.rst rename to doc/_includes/ssp.rst diff --git a/doc/overview/algorithms/time_frequency.rst b/doc/_includes/time_frequency.rst similarity index 100% rename from doc/overview/algorithms/time_frequency.rst rename to doc/_includes/time_frequency.rst From fc495c7d02064028bd95911042afd6929a9a5d05 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 11:19:20 -0700 Subject: [PATCH 06/27] merge maxfilter/sss content into tutorial --- doc/_includes/maxwell.rst | 76 ------------------- .../plot_60_maxwell_filtering_sss.py | 29 ++++++- 2 files changed, 28 insertions(+), 77 deletions(-) delete mode 100644 doc/_includes/maxwell.rst diff --git a/doc/_includes/maxwell.rst b/doc/_includes/maxwell.rst deleted file mode 100644 index eb2e3b93504..00000000000 --- a/doc/_includes/maxwell.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _maxwell: - -Maxwell filtering -################# - -.. contents:: Contents - :local: - :depth: 2 - -Maxwell filtering in mne-python can be used to suppress sources of external -interference and compensate for subject head movements. - -About Maxwell filtering ------------------------ -The principles behind Maxwell filtering are covered in relevant references -[1]_ [2]_ as well as the Elekta MaxFilter manual; see those materials -for basic principles and algorithm descriptions. - -In mne-python Maxwell filtering of raw data can be done using the -:func:`mne.preprocessing.maxwell_filter` function. - -.. warning:: Automatic bad channel detection is not currently implemented. - It is critical to mark bad channels before running Maxwell - filtering, so data should be inspected and marked accordingly - prior to running this algorithm. - -Our Maxwell filtering algorithm currently provides multiple features, -including: - - * Bad channel reconstruction - * Cross-talk cancellation - * Fine calibration correction - * tSSS - * Coordinate frame translation - * Regularization of internal components using information theory - * Raw movement compensation - (using head positions estimated by MaxFilter) - * cHPI subtraction (see :func:`mne.chpi.filter_chpi`) - * Handling of 3D (in addition to 1D) fine calibration files - * Epoch-based movement compensation as described in [1]_ through - :func:`mne.epochs.average_movements` - * **Experimental** processing of data from (un-compensated) - non-Elekta systems - -Movement compensation ---------------------- -When subject head movements are recorded continuously using continuous HPI -(cHPI) and subjects are expected to move during the recording (e.g., when -recording data in children), movement compensation can be performed to -correct for head movements. Movement compensation can be performed two ways: - -1. Raw movement compensation: :func:`mne.preprocessing.maxwell_filter` using - the ``pos`` argument. - -2. Evoked movement compensation: :func:`mne.epochs.average_movements`. - -Each of these requires time-varying estimates of head positions, which can -currently be obtained from MaxFilter using the ``-headpos`` and ``-hp`` -arguments (see the MaxFilter manual for details). The resulting -MaxFilter-style head position information can be read using -:func:`mne.chpi.read_head_pos` and passed to mne-python's movement -compensation algorithms. - -References ----------- -.. [1] Taulu S. and Kajola M. "Presentation of electromagnetic - multichannel data: The signal space separation method," - Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005. - - http://lib.tkk.fi/Diss/2008/isbn9789512295654/article2.pdf - -.. [2] Taulu S. and Simola J. "Spatiotemporal signal space separation - method for rejecting nearby interference in MEG measurements," - Physics in Medicine and Biology, vol. 51, pp. 1759-1768, 2006. - - http://lib.tkk.fi/Diss/2008/isbn9789512295654/article3.pdf diff --git a/tutorials/preprocessing/plot_60_maxwell_filtering_sss.py b/tutorials/preprocessing/plot_60_maxwell_filtering_sss.py index 482e28cb12d..e75b342fb23 100644 --- a/tutorials/preprocessing/plot_60_maxwell_filtering_sss.py +++ b/tutorials/preprocessing/plot_60_maxwell_filtering_sss.py @@ -25,6 +25,9 @@ raw.crop(tmax=60).load_data() ############################################################################### +# Background on SSS and Maxwell filtering +# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# # Signal-space separation (SSS) [1]_ [2]_ is a technique based on the physics # of electromagnetic fields. SSS separates the measured signal into components # attributable to sources *inside* the measurement volume of the sensor array @@ -51,6 +54,23 @@ # Notes section of the :func:`~mne.preprocessing.maxwell_filter` docstring # for details. # +# The MNE-Python implementation of SSS / Maxwell filtering currently provides +# the following features: +# +# - Bad channel reconstruction +# - Cross-talk cancellation +# - Fine calibration correction +# - tSSS +# - Coordinate frame translation +# - Regularization of internal components using information theory +# - Raw movement compensation (using head positions estimated by MaxFilter) +# - cHPI subtraction (see :func:`mne.chpi.filter_chpi`) +# - Handling of 3D (in addition to 1D) fine calibration files +# - Epoch-based movement compensation as described in [1]_ through +# :func:`mne.epochs.average_movements` +# - **Experimental** processing of data from (un-compensated) non-Elekta +# systems +# # # Using SSS and Maxwell filtering in MNE-Python # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -172,7 +192,14 @@ # movement within a given recording session, but also would effectively # normalize head position across different measurement sessions and subjects. # See :ref:`here ` for an extended example of applying -# movement compensation during Maxwell filtering / SSS. +# movement compensation during Maxwell filtering / SSS. Another option is to +# apply movement compensation when averaging epochs into an +# :class:`~mne.Evoked` instance, using the :func:`mne.epochs.average_movements` +# function. +# +# Each of these approaches requires time-varying estimates of head position, +# which is obtained from MaxFilter using the ``-headpos`` and ``-hp`` +# arguments (see the MaxFilter manual for details). # # # Caveats to using SSS / Maxwell filtering From 57f8e5970bd46f3dab81d59f1c90b2a96a856c84 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 11:52:11 -0700 Subject: [PATCH 07/27] integrate interpolation docs; kill time-freq (not algorithms; covered in tuts/examples) --- doc/_includes/channel_interpolation.rst | 25 ++++++++++------ doc/_includes/time_frequency.rst | 30 ------------------- .../plot_15_handling_bad_channels.py | 2 +- 3 files changed, 17 insertions(+), 40 deletions(-) delete mode 100644 doc/_includes/time_frequency.rst diff --git a/doc/_includes/channel_interpolation.rst b/doc/_includes/channel_interpolation.rst index 3730bbda0ed..b750de8e2c7 100644 --- a/doc/_includes/channel_interpolation.rst +++ b/doc/_includes/channel_interpolation.rst @@ -1,15 +1,17 @@ - -.. contents:: Contents - :local: - :depth: 2 - -.. _channel_interpolation: +:orphan: Bad channel repair via interpolation -#################################### +==================================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`channel-interpolation` to link to that section of the + implementation.rst page. The next line is a target for :start-after: so we + can omit the title from the include: + channel-interpolation-begin-content Spherical spline interpolation (EEG) -==================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In short, data repair using spherical spline interpolation [1]_ consists of the following steps: @@ -66,6 +68,11 @@ and the bad channel will be fixed. * :ref:`sphx_glr_auto_examples_preprocessing_plot_interpolate_bad_channels.py` + +.. target for :end-before: channel-interpolation-end-content + + References -========== +~~~~~~~~~~ + .. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography Clinical Neurophysiology, Feb; 72(2):184-7. diff --git a/doc/_includes/time_frequency.rst b/doc/_includes/time_frequency.rst deleted file mode 100644 index 74628aeb206..00000000000 --- a/doc/_includes/time_frequency.rst +++ /dev/null @@ -1,30 +0,0 @@ -==================================== -Spectral and Time-frequency Analysis -==================================== - - -Source Space -^^^^^^^^^^^^ - -Currently, MNE-Python provides a set of functions -allowing to compute spectral analyses in the source space. -Many these functions return :func:`mne.SourceEstimate` objects or collections thereof. - -.. note:: - The :func:`mne.SourceEstimate` object was initially designed for classical time-domain analyses. - In this context, the time axis can actually refer to frequencies. This might be improved - in the future. - - -The following functions are based on minimum norm estimates (MNE). - -- :func:`mne.minimum_norm.compute_source_psd_epochs` returns single-trial power spectral density (PSD) esitmates using multi-tapers. - Here, the time axis actually refers to frequencies, even if labeled as time. - -- :func:`mne.minimum_norm.compute_source_psd` returns power spectral density (PSD) esitmates from continuous data using FFT. - Here, the time axis actually refers to frequencies, even if labeled as time. - -- :func:`mne.minimum_norm.source_band_induced_power` returns a collection of time-domain :func:`mne.SourceEstimate` for each - frequency band, based on Morlet-Wavelets. - -- :func:`mne.minimum_norm.source_induced_power` returns power and inter-trial-coherence (ITC) as raw numpy arrays, based on Morlet-Wavelets. diff --git a/tutorials/preprocessing/plot_15_handling_bad_channels.py b/tutorials/preprocessing/plot_15_handling_bad_channels.py index 9d9b262f88b..1d8a0f40c06 100644 --- a/tutorials/preprocessing/plot_15_handling_bad_channels.py +++ b/tutorials/preprocessing/plot_15_handling_bad_channels.py @@ -197,7 +197,7 @@ # spline method [1]_, which projects the sensor locations onto a unit sphere # and interpolates the signal at the bad sensor locations based on the signals # at the good locations. Mathematical details are presented in -# :ref:`channel_interpolation`. Interpolation of MEG channels uses the field +# :ref:`channel-interpolation`. Interpolation of MEG channels uses the field # mapping algorithms used in computing the :ref:`forward solution # `. # From e69266034607c5443bc3c3ecaf31aec003beae70 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 11:52:38 -0700 Subject: [PATCH 08/27] integrate SSP content --- doc/_includes/ssp.rst | 22 +++++--- doc/overview/implementation.rst | 99 +++++++++++++++++++++++++++++---- 2 files changed, 103 insertions(+), 18 deletions(-) diff --git a/doc/_includes/ssp.rst b/doc/_includes/ssp.rst index b2dbb5780fd..823dd1f8167 100644 --- a/doc/_includes/ssp.rst +++ b/doc/_includes/ssp.rst @@ -1,14 +1,22 @@ -.. _ssp-method: +:orphan: The Signal-Space Projection (SSP) method -######################################## +======================================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ssp-method` to link to that section of the implementation.rst + page. The next line is a target for :start-after: so we can omit the title + from the include: + ssp-begin-content The Signal-Space Projection (SSP) is one approach to rejection of external disturbances in software. The section presents some relevant details of this -method. +method. For practical examples of how to use SSP for artifact rejection, see +:ref:`tut-artifact-ssp`. General concepts -================ +~~~~~~~~~~~~~~~~ Unlike many other noise-cancellation approaches, SSP does not require additional reference sensors to record the disturbance fields. Instead, SSP @@ -75,7 +83,7 @@ For more information on SSP, please consult the references listed in :ref:`CEGIEEBB`. Estimation of the noise subspace --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As described above, application of SSP requires the estimation of the signal vectors :math:`b_1 \dotso b_m` constituting the noise subspace. The most common @@ -86,7 +94,7 @@ subspace. It is also customary to use a separate set of vectors for magnetometers and gradiometers in the Vectorview system. EEG average electrode reference -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The EEG average reference is the mean signal over all the sensors. It is typical in EEG analysis to subtract the average reference from all the sensor @@ -107,4 +115,4 @@ Thus, the projector vector :math:`P_{\perp}` will be given by When applying SSP, the signal of interest can also be sometimes removed. Therefore, it's always a good idea to check how much the effect of interest is reduced by applying SSP. SSP might remove *both* the artifact and signal - of interest. \ No newline at end of file + of interest. diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index 032c41940cd..f05c0ae3b5f 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -1,20 +1,97 @@ .. _implementation: -Implementation details -====================== +Algorithms and Other Implementation details +=========================================== -This page links to information about some of the technical details of -MNE-Python implementation. +This page describes some of the technical details of MNE-Python implementation. + +.. contents:: Page contents + :local: + :depth: 2 + + +.. _units: + +Internal representation (units) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/units.rst + :start-after: units-begin-content + + +.. _precision: + +Floating-point precision +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/precision.rst + :start-after: precision-begin-content + + +.. _channel-types: + +Supported channel types +^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/channel_types.rst + :start-after: channel-types-begin-content + + +.. _data-formats: + +Supported data formats +^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/data_formats.rst + :start-after: data-formats-begin-content + + +.. _dig-formats: + +Supported formats for digitized 3D locations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/dig_formats.rst + :start-after: dig-formats-begin-content + + +.. _channel-interpolation: + +Bad channel repair via interpolation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/channel_interpolation.rst + :start-after: channel-interpolation-begin-content + :end-before: channel-interpolation-end-content + + +.. _maxwell: + +Maxwell filtering +^^^^^^^^^^^^^^^^^ + +MNE-Python's implementation of Maxwell filtering is described in the +:ref:`tut-artifact-sss` tutorial. + + +.. _ssp-method: + +Signal-Space Projection (SSP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/ssp.rst + :start-after: ssp-begin-content + + + + +Mathematics and algorithms +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For more detailed information about mathematics and algorithms in MNE, see: .. toctree:: - ../_includes/units.rst - ../_includes/precision.rst - ../_includes/channel_types.rst - ../_includes/dig_formats.rst - algorithms/channel_interpolation.rst - algorithms/time_frequency.rst - algorithms/maxwell.rst algorithms/ssp.rst algorithms/memory.rst algorithms/bem_model.rst From 6af746ccf476cef16c5f6ce4ad0bec7c4c0b2564 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 12:01:49 -0700 Subject: [PATCH 09/27] integrate memory content --- doc/_includes/memory.rst | 61 ++++++++++++++++++++------------- doc/overview/implementation.rst | 12 +++++-- 2 files changed, 48 insertions(+), 25 deletions(-) diff --git a/doc/_includes/memory.rst b/doc/_includes/memory.rst index 70f1477d689..fe39199544d 100644 --- a/doc/_includes/memory.rst +++ b/doc/_includes/memory.rst @@ -1,19 +1,21 @@ +:orphan: -.. contents:: Contents - :local: - :depth: 3 +Memory-efficient I/O +==================== -.. _memory: +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`memory` to link to that section of the implementation.rst + page. The next line is a target for :start-after: so we can omit the title + from the include: + memory-begin-content -Memory-efficient IO -################### -Preloading -========== +Preloading continuous (raw) data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Raw -^^^ -MNE-Python can read data on-demand using the ``preload`` option provided in raw reading functions. For example:: +MNE-Python can read data on-demand using the ``preload`` option provided in +raw reading functions. For example:: from mne import io from mne.datasets import sample @@ -21,33 +23,46 @@ MNE-Python can read data on-demand using the ``preload`` option provided in raw raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif' raw = io.read_raw_fif(raw_fname, preload=False) -.. note:: Filtering, resampling and dropping or selecting channels does not work with ``preload=False``. +.. note:: Filtering, resampling and dropping or selecting channels does not + work with ``preload=False``. + + +Preloading epoched data +~~~~~~~~~~~~~~~~~~~~~~~ -Epochs -^^^^^^ Similarly, epochs can also be be read from disk on-demand. For example:: import mne events = mne.find_events(raw) event_id, tmin, tmax = 1, -0.2, 0.5 picks = mne.pick_types(raw.info, meg=True, eeg=True, stim=False, eog=True) - epochs = mne.Epochs(raw, events, event_id, tmin, tmax, picks=picks, baseline=(None, 0), reject=dict(eeg=80e-6, eog=150e-6), + epochs = mne.Epochs(raw, events, event_id, tmin, tmax, picks=picks, + baseline=(None, 0), reject=dict(eeg=80e-6, eog=150e-6), preload=False) -When ``preload=False``, the epochs data is loaded from the disk on-demand. Note that ``preload=False`` for epochs will work even if the ``raw`` object -has been loaded with ``preload=True``. Preloading is also supported for :func:`mne.read_epochs`. +When ``preload=False``, the epochs data is loaded from the disk on-demand. Note +that ``preload=False`` for epochs will work even if the ``raw`` object has been +loaded with ``preload=True``. Preloading is also supported for +:func:`mne.read_epochs`. -.. warning:: This comes with a caveat. When ``preload=False``, data rejection based on peak-to-peak thresholds is executed when the data is loaded from disk, *not* when the ``Epochs`` object is created. +.. warning:: This comes with a caveat. When ``preload=False``, data rejection + based on peak-to-peak thresholds is executed when the data is + loaded from disk, *not* when the ``Epochs`` object is created. To explicitly reject artifacts with ``preload=False``, use the function :func:`mne.Epochs.drop_bad`. + Loading data explicitly -======================= +~~~~~~~~~~~~~~~~~~~~~~~ + To load the data if ``preload=False`` was initially selected, use the functions :func:`mne.io.Raw.load_data` and :func:`mne.Epochs.load_data`. -Simplest way to access data -=========================== -If you just want your raw data as a numpy array to work with it in a different framework you can use slicing syntax:: + +Accessing data as NumPy arrays +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you just want your raw data as a :class:`Numpy array ` to +work with it in a different framework you can use slicing syntax:: first_channel_data, times = raw[0, :] - channel_3_5, times_3_5 = raw[3:5, :] + channels_3_and_4, times = raw[3:5, :] diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index f05c0ae3b5f..2fd88cb4e42 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -55,6 +55,15 @@ Supported formats for digitized 3D locations :start-after: dig-formats-begin-content +.. _memory: + +Memory-efficient I/O +^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/memory.rst + :start-after: memory-begin-content + + .. _channel-interpolation: Bad channel repair via interpolation @@ -85,6 +94,7 @@ Signal-Space Projection (SSP) + Mathematics and algorithms ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -92,8 +102,6 @@ For more detailed information about mathematics and algorithms in MNE, see: .. toctree:: - algorithms/ssp.rst - algorithms/memory.rst algorithms/bem_model.rst algorithms/forward.rst algorithms/inverse.rst From 922763bb4173b2e81839ef06331c41a27fab8704 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 12:24:23 -0700 Subject: [PATCH 10/27] restore i/o summary table; cross-ref to new tutorials section --- doc/_includes/data_formats.rst | 82 ++++++++++++++++++++++++++++++++++ tutorials/io/README.txt | 2 +- 2 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 doc/_includes/data_formats.rst diff --git a/doc/_includes/data_formats.rst b/doc/_includes/data_formats.rst new file mode 100644 index 00000000000..0d0d00bc9c7 --- /dev/null +++ b/doc/_includes/data_formats.rst @@ -0,0 +1,82 @@ +:orphan: + +Supported data formats +====================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, + link to :ref:`data-formats`. The next line is + a target for :start-after: so we can omit the title above: + data-formats-begin-content + +When MNE-Python loads sensor data, the data are stored in a Python object of +type :class:`mne.io.Raw`. Specialized loading functions are provided for the +raw data file formats from a variety of equipment manufacturers. All raw data +input/output functions in MNE-Python are found in :mod:`mne.io` and start +with :samp:`read_raw_{*}`; see the documentation for each reader function for +more info on reading specific file types. + +As seen in the table below, there are also a few formats defined by other +neuroimaging analysis software packages that are supported (EEGLAB, +FieldTrip). Like the equipment-specific loading functions, these will also +return an object of class :class:`~mne.io.Raw`; additional functions are +available for reading data that has already been epoched or averaged (see +table). + +.. NOTE: To include only the table, here's a different target for :start-after: + data-formats-begin-table + +.. cssclass:: table-bordered +.. rst-class:: midvalign + +============ ============= ========= =================================== +Data type File format Extension MNE-Python function +============ ============= ========= =================================== +MEG Artemis123 .bin :func:`mne.io.read_raw_artemis123` + +MEG 4-D .dir :func:`mne.io.read_raw_bti` + Neuroimaging + / BTi + +MEG CTF .dir :func:`mne.io.read_raw_ctf` + +MEG Elekta .fif :func:`mne.io.read_raw_fif` + Neuromag + +MEG KIT .sqd :func:`mne.io.read_raw_kit`, + :func:`mne.read_epochs_kit` + + +MEG and EEG FieldTrip .mat :func:`mne.io.read_raw_fieldtrip`, + :func:`mne.read_epochs_fieldtrip`, + :func:`mne.read_evoked_fieldtrip` + +EEG Brainvision .vhdr :func:`mne.io.read_raw_brainvision` + +EEG Biosemi data .bdf :func:`mne.io.read_raw_bdf` + format + +EEG Neuroscan CNT .cnt :func:`mne.io.read_raw_cnt` + +EEG European data .edf :func:`mne.io.read_raw_edf` + format + +EEG EEGLAB .set :func:`mne.io.read_raw_eeglab`, + :func:`mne.read_epochs_eeglab` + +EEG EGI simple .egi :func:`mne.io.read_raw_egi` + binary + +EEG EGI MFF .mff :func:`mne.io.read_raw_egi` + format + +EEG eXimia .nxe :func:`mne.io.read_raw_eximia` + +EEG General data .gdf :func:`mne.io.read_raw_gdf` + format + +EEG Nicolet .data :func:`mne.io.read_raw_nicolet` +============ ============= ========= =================================== + +More details are provided in the tutorials in the :ref:`tut-data-formats` +section. diff --git a/tutorials/io/README.txt b/tutorials/io/README.txt index 7b8cbfa1555..d76cc7d9be0 100644 --- a/tutorials/io/README.txt +++ b/tutorials/io/README.txt @@ -1,4 +1,4 @@ -.. _data-formats: +.. _tut-data-formats: Reading data for different recording systems ============================================ From 73ce706988a02da18b43894a0c718e0939bc2270 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 12:25:10 -0700 Subject: [PATCH 11/27] restore orphans --- doc/_includes/dig_formats.rst | 2 +- doc/_includes/precision.rst | 2 +- doc/_includes/units.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/_includes/dig_formats.rst b/doc/_includes/dig_formats.rst index 98c6ac7eb36..9354b873ade 100644 --- a/doc/_includes/dig_formats.rst +++ b/doc/_includes/dig_formats.rst @@ -1,4 +1,4 @@ -.. _dig-formats: +:orphan: Supported formats for digitized 3D locations ============================================ diff --git a/doc/_includes/precision.rst b/doc/_includes/precision.rst index e4e1887f062..0956bc954e9 100644 --- a/doc/_includes/precision.rst +++ b/doc/_includes/precision.rst @@ -1,4 +1,4 @@ -.. _precision: +:orphan: Floating-point precision ======================== diff --git a/doc/_includes/units.rst b/doc/_includes/units.rst index 77484fe9331..38905989bef 100644 --- a/doc/_includes/units.rst +++ b/doc/_includes/units.rst @@ -1,4 +1,4 @@ -.. _units: +:orphan: Internal representation (units) =============================== From 607aff2d398314ee4ae813d467f0586334f9cc4c Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 12:25:36 -0700 Subject: [PATCH 12/27] trim what is included --- doc/_includes/channel_interpolation.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/_includes/channel_interpolation.rst b/doc/_includes/channel_interpolation.rst index b750de8e2c7..4fb2fd66db9 100644 --- a/doc/_includes/channel_interpolation.rst +++ b/doc/_includes/channel_interpolation.rst @@ -3,6 +3,9 @@ Bad channel repair via interpolation ==================================== +Spherical spline interpolation (EEG) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. NOTE: part of this file is included in doc/overview/implementation.rst. Changes here are reflected there. If you want to link to this content, link to :ref:`channel-interpolation` to link to that section of the @@ -10,9 +13,6 @@ Bad channel repair via interpolation can omit the title from the include: channel-interpolation-begin-content -Spherical spline interpolation (EEG) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - In short, data repair using spherical spline interpolation [1]_ consists of the following steps: * Project the good and bad electrodes onto a unit sphere @@ -64,14 +64,13 @@ To interpolate bad channels, one can simply do: and the bad channel will be fixed. +.. target for :end-before: channel-interpolation-end-content + .. topic:: Examples: * :ref:`sphx_glr_auto_examples_preprocessing_plot_interpolate_bad_channels.py` -.. target for :end-before: channel-interpolation-end-content - - References ~~~~~~~~~~ From a346c25a4878ef5de769b76a426c92d461bdd97f Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:16:58 -0700 Subject: [PATCH 13/27] incorporate bem, forward, inverse, and morph --- .../images => _images}/CoordinateSystems.png | Bin doc/{_includes/images => _images}/HeadCS.png | Bin doc/_includes/bem_model.rst | 22 ++++---- doc/_includes/forward.rst | 51 ++++++++++-------- doc/_includes/inverse.rst | 42 +++++++++------ doc/_includes/morph.rst | 17 ++++-- doc/overview/cookbook.rst | 4 +- doc/overview/implementation.rst | 50 ++++++++++++++--- 8 files changed, 125 insertions(+), 61 deletions(-) rename doc/{_includes/images => _images}/CoordinateSystems.png (100%) rename doc/{_includes/images => _images}/HeadCS.png (100%) diff --git a/doc/_includes/images/CoordinateSystems.png b/doc/_images/CoordinateSystems.png similarity index 100% rename from doc/_includes/images/CoordinateSystems.png rename to doc/_images/CoordinateSystems.png diff --git a/doc/_includes/images/HeadCS.png b/doc/_images/HeadCS.png similarity index 100% rename from doc/_includes/images/HeadCS.png rename to doc/_images/HeadCS.png diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index 2eeee669a1d..e11549986fe 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -1,19 +1,23 @@ +:orphan: -.. _create_bem_model: - -======================= Creating the BEM meshes ======================= -.. contents:: Contents +.. contents:: Page contents :local: :depth: 2 +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`bem-model` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + bem-begin-content .. _bem_watershed_algorithm: Using the watershed algorithm -############################# +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The watershed algorithm [Segonne *et al.*, 2004] is part of the FreeSurfer software. @@ -49,7 +53,7 @@ converts the scalp surface to fif format and saves the result to .. _BABFCDJH: Using FLASH images -################## +~~~~~~~~~~~~~~~~~~ This method depends on the availablily of MRI data acquired with a multi-echo FLASH sequence at two flip angles (5 and 30 degrees). @@ -87,7 +91,7 @@ following steps: .. _BABEBJHI: Organizing MRI data into directories -==================================== +------------------------------------ Since all images comprising the multi-echo FLASH data are contained in a single series, it is necessary to organize the images @@ -129,7 +133,7 @@ links pointing to the original image data. .. _BABGICFE: Creating the surface tessellations -================================== +---------------------------------- The BEM surface segmentation and tessellation is automated with the script :ref:`gen_mne_flash_bem`. @@ -198,7 +202,7 @@ echo times in 5-degree flip angle data. .. _BABHJBED: Inspecting the meshes -===================== +--------------------- It is advisable to check the validity of the BEM meshes before using them. This can be done with help of ``tkmedit`` or ``freeview`` diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index af649145986..15ada27c6fa 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -1,4 +1,4 @@ -.. _ch_forward: +:orphan: The forward solution ==================== @@ -11,11 +11,18 @@ solutions, and the associated low-level utilities. :local: :depth: 2 +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_forward` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + forward-begin-content + .. _coordinate_systems: MEG/EEG and MRI coordinate systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. sidebar:: Coordinate systems in MNE-Python @@ -219,7 +226,7 @@ and .. _head_device_coords: The head and device coordinate systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: images/HeadCS.png :alt: Head coordinate system @@ -258,13 +265,13 @@ to the :math:`xy` plane with positive direction up. all coordinate information to the MNE software head coordinate frame. Creating a surface-based source space -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The fif format source space files containing the dipole locations and orientations are created with :func:`mne.setup_source_space`. Creating a volumetric or discrete source space -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to source spaces confined to a surface, the MNE software provides some support for three-dimensional source spaces bounded by a surface as well @@ -273,12 +280,12 @@ as source spaces comprised of discrete, arbitrarily located source points. The spaces. Creating the BEM meshes -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ -See :ref:`create_bem_model`. +See :ref:`bem-model`. Topology checks -~~~~~~~~~~~~~~~ +--------------- The following topology checks are performed during the creation of BEM models: @@ -308,7 +315,7 @@ The following topology checks are performed during the creation of BEM models: Computing the BEM geometry data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The utility :func:`mne.make_bem_solution` computes the geometry information for BEM. @@ -316,7 +323,7 @@ BEM. .. _coil_geometry_information: Coil geometry information -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ This Section explains the presentation of MEG detection coil geometry information the approximations used for different detection coils in MNE @@ -336,7 +343,7 @@ software. Two pieces of information are needed to characterize the detectors: The sensor coordinate system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- The sensor coordinate system is completely characterized by the location of its origin and the direction cosines of three @@ -371,7 +378,7 @@ where \end{bmatrix}\ . Calculation of the magnetic field -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- The forward calculation in the MNE software computes the signals detected by each MEG sensor for three orthogonal dipoles @@ -412,7 +419,7 @@ points is given in the next section. .. _implemented_coil_geometries: Implemented coil geometries -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- This section describes the coil geometries currently implemented in MNE. The coil types fall in two general categories: @@ -582,7 +589,7 @@ The columns of the tables contain the following data: .. _coil_definition_file: The coil definition file -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ The coil geometry information is stored in the text file :file:`{$MNE_ROOT}/share/mne/coil_def.dat`. In this file, any lines starting @@ -660,7 +667,7 @@ consisting of seven numbers: tilted with respect to each other. Creating the coil definition file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- The standard coil definition file $MNE_ROOT/share/mne/coil_def.dat is included with the MNE software package. The coil definition file @@ -670,10 +677,10 @@ as follows: mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat Computing the forward solution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Purpose -~~~~~~~ +------- Examples on how to compute the forward solution in MNE-Python using :func:`mne.make_forward_solution` can be found @@ -681,7 +688,7 @@ Examples on how to compute the forward solution in MNE-Python using :ref:`computing_the_forward_solution`. Implementation of software gradient compensation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------ Accounting for noise cancellation in MNE-Python is accomplished in :meth:`mne.io.Raw.apply_gradient_compensation`. @@ -697,7 +704,7 @@ reference sensors in addition to the main MEG sensor array and computes a compensated forward solution`. The EEG sphere model definition file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------ In MNE-Python, different sphere models can be specified through :func:`mne.make_sphere_model`. The default model has the following structure: @@ -722,7 +729,7 @@ as :func:`mne.fit_dipole`, :func:`mne.viz.plot_alignment` or .. _eeg_sphere_model: EEG forward solution in the sphere model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------- .. sidebar:: Sphere-model examples in MNE-Python @@ -754,7 +761,7 @@ those lying just inside the inner skull surface. .. _forward_field_derivatives: Field derivatives -~~~~~~~~~~~~~~~~~ +----------------- If the ``--grad`` option is specified, mne_forward_solution includes the derivatives of the forward solution with respect to the dipole location @@ -786,7 +793,7 @@ respectively. Both :math:`G` and :math:`D` can be read with the mne_read_forward_solution Matlab function, see Table 10.1. Averaging forward solutions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ One possibility to make a grand average over several runs of a experiment is to average the data across runs and average the forward solutions accordingly. For diff --git a/doc/_includes/inverse.rst b/doc/_includes/inverse.rst index e60bed404e8..c26c48c7ec6 100644 --- a/doc/_includes/inverse.rst +++ b/doc/_includes/inverse.rst @@ -11,7 +11,15 @@ minimum-norm estimates needed in order to obtain the linear inverse operator. :depth: 2 Overview -^^^^^^^^ +~~~~~~~~ + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_mne` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + inverse-begin-content + Computing the inverse operator is accomplished using :func:`mne.minimum_norm.make_inverse_operator` and @@ -24,7 +32,7 @@ The page starts with a mathematical description of the method. .. _minimum_norm_estimates: Minimum-norm estimates -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ This section describes the mathematical details of the calculation of minimum-norm estimates. In Bayesian sense, the ensuing current distribution is @@ -41,7 +49,7 @@ the maximum a posteriori (MAP) estimate under the following assumptions: known covariance matrix. The noise is not correlated over time. The linear inverse operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- The measured data in the source estimation procedure consists of MEG and EEG data, recorded on a total of N channels. The task is to estimate a total of M @@ -72,7 +80,7 @@ measured MEG and EEG data values at time *t*. .. _mne_regularization: Regularization -~~~~~~~~~~~~~~ +-------------- The a priori variance of the currents is, in practise, unknown. We can express this by writing :math:`R' = R/ \lambda^2`, which yields the inverse operator @@ -99,7 +107,7 @@ discrepancy between the measured and predicted data is tolerable. .. _whitening_and_scaling: Whitening and scaling -~~~~~~~~~~~~~~~~~~~~~ +--------------------- The MNE software employs data whitening so that a 'whitened' inverse operator assumes the form @@ -139,7 +147,7 @@ and whitening. .. _cov_regularization_math: Regularization of the noise-covariance matrix -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------------- Since finite amount of data is usually available to compute an estimate of the noise-covariance matrix :math:`C`, the smallest eigenvalues of its estimate are @@ -179,7 +187,7 @@ regularizing the channel covariance matrix. .. _mne_solution: Computation of the solution -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- The most straightforward approach to calculate the MNE is to employ expression for the original or whitened inverse operator directly. However, for @@ -226,9 +234,9 @@ independent of :math:`L` and, for fixed :math:`\lambda`, we see directly that .. _noise_normalization: Noise normalization -~~~~~~~~~~~~~~~~~~~ +------------------- -The noise-normalized linear estimates introduced by Dale et al. [1]_ require +The noise-normalized linear estimates introduced by Dale et al. [2]_ require division of the expected current amplitude by its variance. Noise normalization serves three purposes: @@ -270,7 +278,7 @@ correspondingly. to :math:`\sqrt{L}`. Predicted data -~~~~~~~~~~~~~~ +-------------- Under noiseless conditions the SNR is infinite and thus leads to :math:`\lambda^2 = 0` and the minimum-norm estimate explains the measured data @@ -288,7 +296,7 @@ where the diagonal matrix :math:`\Pi` has elements :math:`\pi_k = \lambda_k 'recolored eigenfields' in :math:`C^{^1/_2} U`. Cortical patch statistics -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. sidebar:: Cortical patch statistics in MNE-Python @@ -319,7 +327,7 @@ source location :math:`d`: .. _inverse_orientation_constrains: The orientation constraints -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- .. sidebar:: Orientation constraints in MNE-Python @@ -374,7 +382,7 @@ of the surface normal data: defined above. Depth weighting -~~~~~~~~~~~~~~~ +--------------- .. sidebar:: Adjusting depth weighting in MNE-Python @@ -394,7 +402,7 @@ of :math:`G` corresponding to source location :math:`p` and :math:`\gamma` is the order of the depth weighting, which is specified via the ``depth`` option. Effective number of averages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is often the case that the epoch to be analyzed is a linear combination over conditions rather than one of the original averages computed. As stated above, @@ -441,9 +449,11 @@ Generalizing, for any combination of sums and differences, where :math:`w_i = .. math:: 1 / L_{eff} = \sum_{i = 1}^n {1/{L_i}} +.. target for :end-before: inverse-end-content + References -^^^^^^^^^^ +~~~~~~~~~~ -.. [1] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis. +.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis. I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94. doi: 10.1006/nimg.1998.0395 diff --git a/doc/_includes/morph.rst b/doc/_includes/morph.rst index 32d412e9804..0988c11f6bf 100644 --- a/doc/_includes/morph.rst +++ b/doc/_includes/morph.rst @@ -1,4 +1,4 @@ -.. _ch_morph: +:orphan: Morphing and averaging source estimates ======================================= @@ -15,8 +15,17 @@ compute averages of data computed with the MNE software across subjects. :local: :depth: 2 + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_morph` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + morph-begin-content + + Why morphing? -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ .. sidebar:: Morphing examples in MNE-Python @@ -45,7 +54,7 @@ subject B (and vice-versa). .. _CHDJDHII: The morphing maps -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ The MNE software accomplishes morphing with help of morphing maps. The morphing is performed with help of the registered @@ -83,7 +92,7 @@ even if .. _CHDEBAHH: About smoothing -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ The current estimates are normally defined only in a decimated grid which is a sparse subset of the vertices in the triangular tessellation of the cortical diff --git a/doc/overview/cookbook.rst b/doc/overview/cookbook.rst index 7bfc7907bf3..7a9beb5041a 100644 --- a/doc/overview/cookbook.rst +++ b/doc/overview/cookbook.rst @@ -232,14 +232,14 @@ of the intracranial volume. For EEG, the standard model contains the intracranial space, the skull, and the scalp. At present, no bulletproof method exists for creating the -triangulations. Feasible approaches are described in :ref:`create_bem_model`. +triangulations. Feasible approaches are described in :ref:`bem-model`. .. _BABDBBFC: Setting up the head surface triangulation files ############################################### -The segmentation algorithms described in :ref:`create_bem_model` produce +The segmentation algorithms described in :ref:`bem-model` produce either FreeSurfer surfaces or triangulation data in text. Before proceeding to the creation of the boundary element model, standard files for FreeSurfer surfaces must be present: diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index 2fd88cb4e42..91df0e2d702 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -92,17 +92,51 @@ Signal-Space Projection (SSP) :start-after: ssp-begin-content +.. _bem-model: +The Boundary Element Model (BEM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. include:: ../_includes/bem_model.rst + :start-after: bem-begin-content -Mathematics and algorithms -^^^^^^^^^^^^^^^^^^^^^^^^^^ -For more detailed information about mathematics and algorithms in MNE, see: +.. _ch_forward: -.. toctree:: +The forward solution +^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/forward.rst + :start-after: forward-begin-content + + +.. _ch_mne: + +The minimum-norm current estimates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/inverse.rst + :start-after: inverse-begin-content + :end-before: inverse-end-content + + +.. _ch_morph: + +Morphing and averaging source estimates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/morph.rst + :start-after: morph-begin-content + + +References +^^^^^^^^^^ + +.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). + Spherical splines for scalp potential and current density mapping. + *Electroencephalography Clinical Neurophysiology* 72(2), 184-187. + doi: 10.1016/0013-4694(89)90180-6 - algorithms/bem_model.rst - algorithms/forward.rst - algorithms/inverse.rst - algorithms/morph.rst +.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis. + I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94. + doi: 10.1006/nimg.1998.0395 From 0ea4bf5c4f9ebe53f5b62f2bed810b7c59b03708 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:29:37 -0700 Subject: [PATCH 14/27] remove unused crossref targets --- doc/_includes/bem_model.rst | 7 ++----- doc/_includes/forward.rst | 4 ++-- doc/_includes/morph.rst | 2 -- 3 files changed, 4 insertions(+), 9 deletions(-) diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index e11549986fe..1851be9d4c0 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -50,7 +50,6 @@ contains the brain MRI volume. Furthermore, ``mne watershed_bem`` script converts the scalp surface to fif format and saves the result to :samp:`bem/{}-head.fif`. -.. _BABFCDJH: Using FLASH images ~~~~~~~~~~~~~~~~~~ @@ -75,7 +74,7 @@ following steps: it with the MPRAGE data, and run the segmentation and meshing program. This step is accomplished by running the script :ref:`gen_mne_flash_bem`. -- Inspecting the meshes with tkmedit, see :ref:`BABHJBED`. +- Inspecting the meshes with tkmedit, see :ref:`inspecting-meshes`. .. note:: Different methods can be employed for the creation of the individual surfaces. For example, it may turn out that the @@ -88,7 +87,6 @@ following steps: .. note:: The following sections assume that you have run the appropriate setup scripts to make both MNE and FreeSurfer software available. -.. _BABEBJHI: Organizing MRI data into directories ------------------------------------ @@ -130,7 +128,6 @@ links pointing to the original image data. .. note:: Since mne_organize_dicom processes all images, not only the FLASH data, it may be a useful preprocessing step before FreeSurfer reconstruction process as well. -.. _BABGICFE: Creating the surface tessellations ---------------------------------- @@ -199,7 +196,7 @@ If the ``--noflash30`` option is specified to ``mne flash_bem``, steps 3 and 4 in the above are replaced by averaging over the different echo times in 5-degree flip angle data. -.. _BABHJBED: +.. _inspecting-meshes: Inspecting the meshes --------------------- diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index 15ada27c6fa..21b108ffe8f 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -40,7 +40,7 @@ right, the :math:`y` axis to the front, and the :math:`z` axis up. .. _coordinate_system_figure: -.. figure:: images/CoordinateSystems.png +.. figure:: ../_images/CoordinateSystems.png :alt: MEG/EEG and MRI coordinate systems MEG/EEG and MRI coordinate systems @@ -228,7 +228,7 @@ and The head and device coordinate systems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. figure:: images/HeadCS.png +.. figure:: ../_images/HeadCS.png :alt: Head coordinate system The head coordinate system diff --git a/doc/_includes/morph.rst b/doc/_includes/morph.rst index 0988c11f6bf..f609f9dc743 100644 --- a/doc/_includes/morph.rst +++ b/doc/_includes/morph.rst @@ -51,7 +51,6 @@ functional similar structures are represented at the same spatial location for tell us how the data produced by subject A would be represented on the brain of subject B (and vice-versa). -.. _CHDJDHII: The morphing maps ~~~~~~~~~~~~~~~~~ @@ -89,7 +88,6 @@ even if *i.e.*, the mapping is *almost* a bijection. -.. _CHDEBAHH: About smoothing ~~~~~~~~~~~~~~~ From 6339da7dadc71fb34a3c37ae333a9518e1677999 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:32:12 -0700 Subject: [PATCH 15/27] fix crossref --- tutorials/sample-datasets/plot_brainstorm_auditory.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/sample-datasets/plot_brainstorm_auditory.py b/tutorials/sample-datasets/plot_brainstorm_auditory.py index 7db40c1f05e..951cdf5690e 100644 --- a/tutorials/sample-datasets/plot_brainstorm_auditory.py +++ b/tutorials/sample-datasets/plot_brainstorm_auditory.py @@ -301,7 +301,7 @@ # solution are read from a file. Since the data only contains MEG channels, we # only need the inner skull surface for making the forward solution. For more # information: :ref:`CHDBBCEJ`, :func:`mne.setup_source_space`, -# :ref:`create_bem_model`, :func:`mne.bem.make_watershed_bem`. +# :ref:`bem-model`, :func:`mne.bem.make_watershed_bem`. if use_precomputed: fwd_fname = op.join(data_path, 'MEG', 'bst_auditory', 'bst_auditory-meg-oct-6-fwd.fif') From 85235883c5bf5d1d3a26ab59e49ff50388192af3 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:32:38 -0700 Subject: [PATCH 16/27] reflow text --- doc/_includes/channel_interpolation.rst | 4 +- doc/_includes/forward.rst | 223 ++++++++++++------------ 2 files changed, 110 insertions(+), 117 deletions(-) diff --git a/doc/_includes/channel_interpolation.rst b/doc/_includes/channel_interpolation.rst index 4fb2fd66db9..a68d1fb6ffc 100644 --- a/doc/_includes/channel_interpolation.rst +++ b/doc/_includes/channel_interpolation.rst @@ -74,4 +74,6 @@ and the bad channel will be fixed. References ~~~~~~~~~~ -.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography Clinical Neurophysiology, Feb; 72(2):184-7. +.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). + Spherical splines for scalp potential and current density mapping. + *Electroencephalography Clinical Neurophysiology* 72(2), 184-187. diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index 21b108ffe8f..fee4c59b4b1 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -33,10 +33,10 @@ MEG/EEG and MRI coordinate systems `__. The coordinate systems used in MNE software (and FreeSurfer) and their -relationships are depicted in :ref:`coordinate_system_figure`. Except for the *Sensor -coordinates*, all of the coordinate systems are Cartesian and have the "RAS" -(Right-Anterior-Superior) orientation, *i.e.*, the :math:`x` axis points to the -right, the :math:`y` axis to the front, and the :math:`z` axis up. +relationships are depicted in :ref:`coordinate_system_figure`. Except for the +*sensor coordinates*, all of the coordinate systems are Cartesian and have the +"RAS" (Right-Anterior-Superior) orientation, *i.e.*, the :math:`x` axis points +to the right, the :math:`y` axis to the front, and the :math:`z` axis up. .. _coordinate_system_figure: @@ -73,8 +73,8 @@ The coordinate systems related to MEG/EEG data are: Each MEG sensor has a local coordinate system defining the orientation and location of the sensor. With help of this coordinate system, the numerical integration data needed for the computation of the magnetic field can be - expressed conveniently as discussed in :ref:`coil_geometry_information`. The - channel information data in the fif files contain the information to + expressed conveniently as discussed in :ref:`coil_geometry_information`. + The channel information data in the fif files contain the information to specify the coordinate transformation between the coordinates of each sensor and the MEG device coordinates. @@ -127,11 +127,10 @@ The coordinate systems related to MRI data are: and :math:`T_+` in :ref:`coordinate_system_figure`, are fixed as discussed in http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach (*Approach 2*). -The different coordinate systems are related by coordinate -transformations depicted in :ref:`coordinate_system_figure`. The arrows and -coordinate transformation symbols (:math:`T_x`) -indicate the transformations actually present in the FreeSurfer -files. Generally, +The different coordinate systems are related by coordinate transformations +depicted in :ref:`coordinate_system_figure`. The arrows and coordinate +transformation symbols (:math:`T_x`) indicate the transformations actually +present in the FreeSurfer files. Generally, .. math:: \begin{bmatrix} x_2 \\ @@ -289,29 +288,24 @@ Topology checks The following topology checks are performed during the creation of BEM models: -- The completeness of each surface is - confirmed by calculating the total solid angle subtended by all - triangles from a point inside the triangulation. The result should - be very close to :math:`4 \pi`. If the result - is :math:`-4 \pi` instead, it is conceivable - that the ordering of the triangle vertices is incorrect and the - ``--swap`` option should be specified. - -- The correct ordering of the surfaces is verified by checking - that the surfaces are inside each other as expected. This is accomplished - by checking that the sum solid angles subtended by triangles of - a surface :math:`S_k` at all vertices of another - surface :math:`S_p` which is supposed to be - inside it equals :math:`4 \pi`. Naturally, this - check is applied only if the model has more than one surface. Since - the surface relations are transitive, it is enough to check that - the outer skull surface is inside the skin surface and that the - inner skull surface is inside the outer skull one. - -- The extent of each of the triangulated volumes is checked. - If the extent is smaller than 50mm, an error is reported. This - may indicate that the vertex coordinates have been specified in - meters instead of millimeters. +- The completeness of each surface is confirmed by calculating the total solid + angle subtended by all triangles from a point inside the triangulation. The + result should be very close to :math:`4 \pi`. If the result is :math:`-4 \pi` + instead, it is conceivable that the ordering of the triangle vertices is + incorrect and the ``--swap`` option should be specified. + +- The correct ordering of the surfaces is verified by checking that the + surfaces are inside each other as expected. This is accomplished by checking + that the sum solid angles subtended by triangles of a surface :math:`S_k` at + all vertices of another surface :math:`S_p` which is supposed to be inside it + equals :math:`4 \pi`. Naturally, this check is applied only if the model has + more than one surface. Since the surface relations are transitive, it is + enough to check that the outer skull surface is inside the skin surface and + that the inner skull surface is inside the outer skull one. + +- The extent of each of the triangulated volumes is checked. If the extent is + smaller than 50mm, an error is reported. This may indicate that the vertex + coordinates have been specified in meters instead of millimeters. Computing the BEM geometry data @@ -334,10 +328,9 @@ software. Two pieces of information are needed to characterize the detectors: - A unique identifier, which has an one-to-one correspondence to the geometrical description of the coil. -.. note:: MNE ships with several coil geometry configurations. - They can be found in ``mne/data``. - See :ref:`ex-plot-meg-sensors` - for a comparison between different coil geometries, and +.. note:: MNE ships with several coil geometry configurations. They can be + found in ``mne/data``. See :ref:`ex-plot-meg-sensors` for a + comparison between different coil geometries, and :ref:`implemented_coil_geometries` for detailed information regarding the files describing Neuromag coil geometries. @@ -345,26 +338,23 @@ software. Two pieces of information are needed to characterize the detectors: The sensor coordinate system ---------------------------- -The sensor coordinate system is completely characterized -by the location of its origin and the direction cosines of three -orthogonal unit vectors pointing to the directions of the x, y, -and z axis. In fact, the unit vectors contain redundant information -because the orientation can be uniquely defined with three angles. -The measurement fif files list these data in MEG device coordinates. -Transformation to the MEG head coordinate frame can be easily accomplished -by applying the device-to-head coordinate transformation matrix -available in the data files provided that the head-position indicator -was used. Optionally, the MNE software forward calculation applies -another coordinate transformation to the head-coordinate data to -bring the coil locations and orientations to the MRI coordinate system. - -If :math:`r_0` is a row vector for -the origin of the local sensor coordinate system and :math:`e_x`, :math:`e_y`, -and :math:`e_z` are the row vectors for the -three orthogonal unit vectors, all given in device coordinates, -a location of a point :math:`r_C` in sensor coordinates -is transformed to device coordinates (:math:`r_D`) -by +The sensor coordinate system is completely characterized by the location of its +origin and the direction cosines of three orthogonal unit vectors pointing to +the directions of the x, y, and z axis. In fact, the unit vectors contain +redundant information because the orientation can be uniquely defined with +three angles. The measurement fif files list these data in MEG device +coordinates. Transformation to the MEG head coordinate frame can be easily +accomplished by applying the device-to-head coordinate transformation matrix +available in the data files provided that the head-position indicator was used. +Optionally, the MNE software forward calculation applies another coordinate +transformation to the head-coordinate data to bring the coil locations and +orientations to the MRI coordinate system. + +If :math:`r_0` is a row vector for the origin of the local sensor coordinate +system and :math:`e_x`, :math:`e_y`, and :math:`e_z` are the row vectors for +the three orthogonal unit vectors, all given in device coordinates, a location +of a point :math:`r_C` in sensor coordinates is transformed to device +coordinates (:math:`r_D`) by .. math:: [r_D 1] = [r_C 1] T_{CD}\ , @@ -380,40 +370,37 @@ where Calculation of the magnetic field --------------------------------- -The forward calculation in the MNE software computes the -signals detected by each MEG sensor for three orthogonal dipoles -at each source space location. This requires specification of the -conductor model, the location and orientation of the dipoles, and -the location and orientation of each MEG sensor as well as its coil -geometry. +The forward calculation in the MNE software computes the signals detected by +each MEG sensor for three orthogonal dipoles at each source space location. +This requires specification of the conductor model, the location and +orientation of the dipoles, and the location and orientation of each MEG sensor +as well as its coil geometry. -The output of each SQUID sensor is a weighted sum of the -magnetic fluxes threading the loops comprising the detection coil. -Since the flux threading a coil loop is an integral of the magnetic -field component normal to the coil plane, the output of the k :sup:`th` -MEG channel, :math:`b_k` can be approximated by: +The output of each SQUID sensor is a weighted sum of the magnetic fluxes +threading the loops comprising the detection coil. Since the flux threading a +coil loop is an integral of the magnetic field component normal to the coil +plane, the output of the k :sup:`th` MEG channel, :math:`b_k` can be +approximated by: .. math:: b_k = \sum_{p = 1}^{N_k} {w_{kp} B(r_{kp}) \cdot n_{kp}} -where :math:`r_{kp}` are a set of :math:`N_k` integration -points covering the pickup coil loops of the sensor, :math:`B(r_{kp})` is -the magnetic field due to the current sources calculated at :math:`r_{kp}`, -:math:`n_{kp}` are the coil normal directions at these points, and -:math:`w_{kp}` are the weights associated to the integration points. This -formula essentially presents numerical integration of the magnetic field over -the pickup loops of sensor :math:`k`. - -There are three accuracy levels for the numerical integration -expressed above. The *simple* accuracy means -the simplest description of the coil. This accuracy is not used -in the MNE forward calculations. The *normal* or *recommended* accuracy typically uses -two integration points for planar gradiometers, one in each half -of the pickup coil and four evenly distributed integration points -for magnetometers. This is the default accuracy used by MNE. If -the ``--accurate`` option is specified, the forward calculation typically employs -a total of eight integration points for planar gradiometers and -sixteen for magnetometers. Detailed information about the integration -points is given in the next section. +where :math:`r_{kp}` are a set of :math:`N_k` integration points covering the +pickup coil loops of the sensor, :math:`B(r_{kp})` is the magnetic field due to +the current sources calculated at :math:`r_{kp}`, :math:`n_{kp}` are the coil +normal directions at these points, and :math:`w_{kp}` are the weights +associated to the integration points. This formula essentially presents +numerical integration of the magnetic field over the pickup loops of sensor +:math:`k`. + +There are three accuracy levels for the numerical integration expressed above. +The *simple* accuracy means the simplest description of the coil. This accuracy +is not used in the MNE forward calculations. The *normal* or *recommended* +accuracy typically uses two integration points for planar gradiometers, one in +each half of the pickup coil and four evenly distributed integration points for +magnetometers. This is the default accuracy used by MNE. If the ``--accurate`` +option is specified, the forward calculation typically employs a total of eight +integration points for planar gradiometers and sixteen for magnetometers. +Detailed information about the integration points is given in the next section. .. _implemented_coil_geometries: @@ -429,22 +416,21 @@ in MNE. The coil types fall in two general categories: - Planar magnetometers. -For axial sensors, the *z* axis of the -local coordinate system is parallel to the field component detected, *i.e.*, -normal to the coil plane.For circular coils, the orientation of -the *x* and *y* axes on the -plane normal to the z axis is irrelevant. In the square coils employed -in the Vectorview (TM) system the *x* axis -is chosen to be parallel to one of the sides of the magnetometer -coil. For planar sensors, the *z* axis is likewise -normal to the coil plane and the x axis passes through the centerpoints -of the two coil loops so that the detector gives a positive signal -when the normal field component increases along the *x* axis. +For axial sensors, the *z* axis of the local coordinate system is parallel to +the field component detected, *i.e.*, normal to the coil plane.For circular +coils, the orientation of the *x* and *y* axes on the plane normal to the z +axis is irrelevant. In the square coils employed in the Vectorview (TM) system +the *x* axis is chosen to be parallel to one of the sides of the magnetometer +coil. For planar sensors, the *z* axis is likewise normal to the coil plane and +the x axis passes through the centerpoints of the two coil loops so that the +detector gives a positive signal when the normal field component increases +along the *x* axis. :ref:`normal_coil_descriptions` lists the parameters of the *normal* coil -geometry descriptions :ref:`accurate_coil_descriptions` lists the *accurate* descriptions. For simple accuracy, -please consult the coil definition file, see :ref:`coil_definition_file`. -The columns of the tables contain the following data: +geometry descriptions :ref:`accurate_coil_descriptions` lists the *accurate* +descriptions. For simple accuracy, please consult the coil definition file, see +:ref:`coil_definition_file`. The columns of the tables contain the following +data: - The number identifying the coil id. This number is used in the coil descriptions found in the FIF files. @@ -462,7 +448,9 @@ The columns of the tables contain the following data: of the baseline of the gradiometer to show that the output is in T/m. -.. note:: The coil geometry information is stored in the file mne/data/coil_def.dat, which is automatically created by the MNE-C utility mne_list_coil_def. +.. note:: The coil geometry information is stored in the file + :file:`{$MNE_ROOT}/share/mne/data/coil_def.dat`, which is + automatically created by the MNE-C utility ``mne_list_coil_def``. .. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| .. _normal_coil_descriptions: @@ -523,7 +511,8 @@ The columns of the tables contain the following data: | | diagonal gradients | | | | +------+-------------------------+----+----------------------------------+----------------------+ -.. note:: If a plus-minus sign occurs in several coordinates, all possible combinations have to be included. +.. note:: If a plus-minus sign occurs in several coordinates, all possible + combinations have to be included. .. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.05\linewidth}|p{0.25\linewidth}|p{0.15\linewidth}| .. _accurate_coil_descriptions: @@ -674,7 +663,10 @@ is included with the MNE software package. The coil definition file can be recreated with the MNE-C utility ``mne_list_coil_def`` as follows: -mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat +.. code-block:: console + + mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat + Computing the forward solution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -691,17 +683,16 @@ Implementation of software gradient compensation ------------------------------------------------ Accounting for noise cancellation in MNE-Python is accomplished in -:meth:`mne.io.Raw.apply_gradient_compensation`. -See :ref:`plot_brainstorm_phantom_ctf` for an example. - -CTF and 4D Neuroimaging data may have been -subjected to noise cancellation employing the data from the reference sensor -array. Even though these sensor are rather far away from the brain sources, -:func:`mne.make_forward_solution` takes them into account in the computations. -If the data file has software gradient -compensation activated, it computes the field of at the -reference sensors in addition to the main MEG sensor array and computes a -compensated forward solution`. +:meth:`mne.io.Raw.apply_gradient_compensation`. See +:ref:`plot_brainstorm_phantom_ctf` for an example. + +CTF and 4D Neuroimaging data may have been subjected to noise cancellation +employing the data from the reference sensor array. Even though these sensor +are rather far away from the brain sources, :func:`mne.make_forward_solution` +takes them into account in the computations. If the data file has software +gradient compensation activated, it computes the field of at the reference +sensors in addition to the main MEG sensor array and computes a compensated +forward solution`. The EEG sphere model definition file ------------------------------------ From 61215b17bf1fb56d837273346149bd8518ba0a93 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:43:39 -0700 Subject: [PATCH 17/27] ignore _includes folder when building --- doc/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 2a8b858d5f1..fd07a9ea87e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -84,6 +84,11 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_includes'] + # The suffix of source filenames. source_suffix = '.rst' From 059da2cd0552a70272cb3c0ae03fc3aac116df80 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:54:46 -0700 Subject: [PATCH 18/27] delete obsolete note --- doc/_includes/inverse.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/_includes/inverse.rst b/doc/_includes/inverse.rst index c26c48c7ec6..c49e49e9bb8 100644 --- a/doc/_includes/inverse.rst +++ b/doc/_includes/inverse.rst @@ -267,11 +267,6 @@ sources) are thus proportional to :math:`\sqrt{L}` while the *F*-statistic employed with free-orientation sources is proportional to :math:`L`, correspondingly. -.. note:: - A section discussing statistical considerations related to the noise - normalization procedure will be added to this manual in one of the - subsequent releases. - .. note:: The MNE software usually computes the *square roots* of the F-statistic to be displayed on the inflated cortical surfaces. These are also proportional From 2240fda309387b50343f1580d30280b010864ab4 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:55:12 -0700 Subject: [PATCH 19/27] reduce TOC depth --- doc/overview/implementation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index 91df0e2d702..eae6bd23410 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -7,7 +7,7 @@ This page describes some of the technical details of MNE-Python implementation. .. contents:: Page contents :local: - :depth: 2 + :depth: 1 .. _units: From aef0a9deeb4862fda25202c518c18f3d7d7a5b6b Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 14:55:35 -0700 Subject: [PATCH 20/27] more text reflow; better path formatting --- doc/_includes/bem_model.rst | 188 +++++++++++++++++------------------- 1 file changed, 91 insertions(+), 97 deletions(-) diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index 1851be9d4c0..2f406d013aa 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -25,47 +25,38 @@ The name of the program is mri_watershed . Its use in the MNE environment is facilitated by the script :ref:`gen_mne_watershed_bem`. -After ``mne watershed_bem`` has -completed, the following files appear in the subject's ``bem/watershed`` directory: +After ``mne watershed_bem`` has completed, the following files appear in the +subject's :file:`bem/watershed` directory: -** <*subject*> _brain_surface** +- :file:`{}_brain_surface` contains the brain surface triangulation. - Contains the brain surface triangulation. +- :file:`{}_inner_skull_surface` contains the inner skull + triangulation. -** <*subject*> _inner_skull_surface** +- :file:`{}_outer_skull_surface` contains the outer skull + triangulation. - Contains the inner skull triangulation. +- :file:`{}_outer_skin_surface` contains the scalp triangulation. -** <*subject*> _outer_skull_surface** - - Contains the outer skull triangulation. - -** <*subject*> _outer_skin_surface** - - Contains the scalp triangulation. - -All of these surfaces are in the FreeSurfer format. In addition, -there will be a directory called ``bem/watershed/ws`` which -contains the brain MRI volume. Furthermore, ``mne watershed_bem`` script -converts the scalp surface to fif format and saves the result to -:samp:`bem/{}-head.fif`. +All of these surfaces are in the FreeSurfer format. In addition, there will be +a directory called :file:`bem/watershed/ws` which contains the brain MRI +volume. Furthermore, ``mne watershed_bem`` script converts the scalp surface to +fif format and saves the result to :file:`bem/{}-head.fif`. Using FLASH images ~~~~~~~~~~~~~~~~~~ -This method depends on the availablily of MRI data acquired -with a multi-echo FLASH sequence at two flip angles (5 and 30 degrees). -These data can be acquired separately from the MPRAGE data employed -in FreeSurfer cortical reconstructions but it is strongly recommended -that they are collected at the same time with the MPRAGEs or at -least with the same scanner. For easy co-registration, the images -should have FOV, matrix, slice thickness, gap, and slice orientation -as the MPRAGE data. For information on suitable pulse sequences, -see reference [B. Fischl *et al.* and J. Jovicich *et -al.*, 2006] in :ref:`CEGEGDEI`. At the Martinos -Center, use of the 1.5-T Avanto scanner (Bay 2) is recommended for -best results. +This method depends on the availablily of MRI data acquired with a multi-echo +FLASH sequence at two flip angles (5 and 30 degrees). These data can be +acquired separately from the MPRAGE data employed in FreeSurfer cortical +reconstructions but it is strongly recommended that they are collected at the +same time with the MPRAGEs or at least with the same scanner. For easy +co-registration, the images should have FOV, matrix, slice thickness, gap, and +slice orientation as the MPRAGE data. For information on suitable pulse +sequences, see reference [B. Fischl *et al.* and J. Jovicich *et al.*, 2006] in +:ref:`CEGEGDEI`. At the Martinos Center, use of the 1.5-T Avanto scanner (Bay +2) is recommended for best results. Creation of the BEM meshes using this method involves the following steps: @@ -91,104 +82,107 @@ following steps: Organizing MRI data into directories ------------------------------------ -Since all images comprising the multi-echo FLASH data are -contained in a single series, it is necessary to organize the images -according to the echoes before proceeding to the BEM surface reconstruction. -This is accomplished by the mne_organize_dicom script, -which creates a directory tree with symbolic links to the original -DICOM image files. To run mne_organize_dicom , -proceed as follows: +Since all images comprising the multi-echo FLASH data are contained in a single +series, it is necessary to organize the images according to the echoes before +proceeding to the BEM surface reconstruction. This is accomplished by the +``mne_organize_dicom`` script, which creates a directory tree with symbolic +links to the original DICOM image files. To run ``mne_organize_dicom``, proceed +as follows: -- Copy all of your images or create symbolic - links to them in a single directory. The images must be in DICOM - format. We will refer to this directory as <*source*> . +- Copy all of your images or create symbolic links to them in a single + directory. The images must be in DICOM format. We will refer to this + directory as :file:`{}`. -- Create another directory to hold the output of mne_organize_dicom . We - will refer to this directory as <*dest*> . +- Create another directory to hold the output of ``mne_organize_dicom``. We + will refer to this directory as :file:`{}`. -- Change the working directory to <*dest*> . +- Change the working directory to :file:`{}`. -- Say ``mne_organize_dicom`` <*source*> . - Depending on the total number of images in <*source*> this - script may take quite a while to run. Progress is indicated by - listing the number of images processed at 50-image intervals. +- Say ``mne_organize_dicom`` :file:`{}`. Depending on the total number + of images in :file:`{}` this script may take quite a while to run. + Progress is indicated by listing the number of images processed at 50-image + intervals. -As a result, <*dest*> will -contain several directories named <*three-digit number*> _ <*protocol_name*> corresponding -to the different series of images acquired. Spaces and parenthesis -in protocol names will be replaced by underscores. Under each of -these directories there are one or more directories named <*three-digit*> number -corresponding to one or more subsets of images in this series (protocol). -The only subset division scheme implemented in mne_organize_dicom is -that according to different echoes, typically found in multi-echo -FLASH data. These second level directories will contain symbolic -links pointing to the original image data. +As a result, :file:`{}` will contain several directories named +:file:`{}_{}` corresponding to the different +series of images acquired. Spaces and parenthesis in protocol names will be +replaced by underscores. Under each of these directories there are one or more +directories named :file:`{}` number corresponding to one or +more subsets of images in this series (protocol). The only subset division +scheme implemented in ``mne_organize_dicom`` is that according to different +echoes, typically found in multi-echo FLASH data. These second level +directories will contain symbolic links pointing to the original image data. -.. note:: mne_organize_dicom was developed specifically for Siemens DICOM data. Its correct behavior with DICOM files originating from other MRI scanners has not been verified at this time. +.. note:: ``mne_organize_dicom`` was developed specifically for Siemens DICOM + data. Its correct behavior with DICOM files originating from other MRI + scanners has not been verified at this time. -.. note:: Since mne_organize_dicom processes all images, not only the FLASH data, it may be a useful preprocessing step before FreeSurfer reconstruction process as well. +.. note:: Since ``mne_organize_dicom`` processes all images, not only the FLASH + data, it may be a useful preprocessing step before FreeSurfer reconstruction + process as well. Creating the surface tessellations ---------------------------------- -The BEM surface segmentation and tessellation is automated -with the script :ref:`gen_mne_flash_bem`. -It assumes that a FreeSurfer reconstruction for this subject is -already in place. +The BEM surface segmentation and tessellation is automated with the script +:ref:`gen_mne_flash_bem`. It assumes that a FreeSurfer reconstruction for this +subject is already in place. Before running ``mne flash_bem`` do the following: -- Create symbolic links from the directories containing the - 5-degree and 30-degree flip angle FLASH series to ``flash05`` and ``flash30`` , respectively: +- Create symbolic links from the directories containing the 5-degree and + 30-degree flip angle FLASH series to ``flash05`` and ``flash30``, + respectively: - - ``ln -s`` <*FLASH 5 series dir*> ``flash05`` + - :samp:`ln -s {} flash05` - - ``ln -s`` <*FLASH 30 series dir*> ``flash30`` + - :samp:`ln -s {} flash30` -- Some partition formats (e.g. FAT32) do not support symbolic links. In this case, copy the file to the appropriate series: +- Some partition formats (e.g. FAT32) do not support symbolic links. In this + case, copy the file to the appropriate series: - - ``cp`` <*FLASH 5 series dir*> ``flash05`` + - :samp:`cp {} flash05` - - ``cp`` <*FLASH 30 series dir*> ``flash30`` + - :samp:`cp {} flash30` -- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment - variables +- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment variables -.. note:: If ``mne flash_bem`` is run with the ``--noflash30`` option, the flash30 directory is not needed, *i.e.*, only the 5-degree flip angle flash data are employed. +.. note:: If ``mne flash_bem`` is run with the ``--noflash30`` option, the + :file:`flash30` directory is not needed, *i.e.*, only the 5-degree flip + angle flash data are employed. -It may take a while for mne_flash_bem to -complete. It uses the FreeSurfer directory structure under ``$SUBJECTS_DIR/$SUBJECT`` . -The script encapsulates the following processing steps: +It may take a while for mne_flash_bem to complete. It uses the FreeSurfer +directory structure under ``$SUBJECTS_DIR/$SUBJECT``. The script encapsulates +the following processing steps: -- It creates an mgz file corresponding - to each of the eight echoes in each of the FLASH directories in ``mri/flash`` . - The files will be called ``mef`` <*flip-angle*> _ <*echo-number*> ``.mgz`` . +- It creates an mgz file corresponding to each of the eight echoes in each of + the FLASH directories in ``mri/flash``. The files will be called + :file:`mef {}_{}.mgz`. - If the ``--unwarp`` option is specified, run grad_unwarp and produce - files ``mef`` <*flip-angle*> _ <*echo-number*> ``u.mgz`` . - These files will be then used in the following steps. + files :file:`mef {}_{}u.mgz`. These files will be + then used in the following steps. -- It creates parameter maps in ``mri/flash/parameter_maps`` using mri_ms_fitparms . +- It creates parameter maps in :file:`mri/flash/parameter_maps` using + ``mri_ms_fitparms``. -- It creates a synthetic 5-degree flip angle volume in ``mri/flash/parameter_maps/flash5.mgz`` using mri_synthesize . +- It creates a synthetic 5-degree flip angle volume in + :file:`mri/flash/parameter_maps/flash5.mgz` using ``mri_synthesize``. -- Using fsl_rigid_register , - it creates a registered 5-degree flip angle volume ``mri/flash/parameter_maps/flash5_reg.mgz`` by - registering ``mri/flash/parameter_maps/flash5.mgz`` to - the *T1* volume under ``mri`` . +- Using ``fsl_rigid_register``, it creates a registered 5-degree flip angle + volume ``mri/flash/parameter_maps/flash5_reg.mgz`` by registering + :file:`mri/flash/parameter_maps/flash5.mgz` to the *T1* volume under ``mri``. -- Using mri_convert , it converts - the flash5_reg volume to COR - format under ``mri/flash5`` . If necessary, the T1 and brain volumes - are also converted into the COR format. +- Using ``mri_convert``, it converts the flash5_reg volume to COR format under + ``mri/flash5``. If necessary, the T1 and brain volumes are also converted + into the COR format. -- It runs mri_make_bem_surfaces to - create the BEM surface tessellations. +- It runs ``mri_make_bem_surfaces`` to create the BEM surface tessellations. -- It creates the directory ``bem/flash`` , moves the - tri-format tringulations there and creates the corresponding FreeSurfer - surface files in the same directory. +- It creates the directory :file:`bem/flash`, moves the tri-format + tringulations there and creates the corresponding FreeSurfer surface files + in the same directory. - The COR format volumes created by ``mne flash_bem`` are removed. From ede8bc658c6d000d62cfdb72089ab53877c4025f Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 15:08:37 -0700 Subject: [PATCH 21/27] shuffle tutorial locations a bit --- tutorials/intro/README.txt | 4 ++-- .../plot_40_sensor_locations.py} | 2 ++ .../plot_45_projectors_background.py} | 0 tutorials/raw/plot_40_visualize_raw.py | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) rename tutorials/{misc/plot_sensor_locations.py => intro/plot_40_sensor_locations.py} (99%) rename tutorials/{intro/plot_40_projectors_background.py => preprocessing/plot_45_projectors_background.py} (100%) diff --git a/tutorials/intro/README.txt b/tutorials/intro/README.txt index a2e480265f5..87db17bc27f 100644 --- a/tutorials/intro/README.txt +++ b/tutorials/intro/README.txt @@ -3,5 +3,5 @@ Introductory tutorials These tutorials cover the basic EEG/MEG pipeline for event-related analysis, introduce the :class:`mne.Info`, :term:`events`, and :class:`mne.Annotations` -data structures, provide background information on :term:`projections -`, and introduce some of the configuration options available. +data structures, discuss how sensor locations are handled, and introduce some +of the configuration options available. diff --git a/tutorials/misc/plot_sensor_locations.py b/tutorials/intro/plot_40_sensor_locations.py similarity index 99% rename from tutorials/misc/plot_sensor_locations.py rename to tutorials/intro/plot_40_sensor_locations.py index 6271a59eedb..3ed5ba08b5c 100644 --- a/tutorials/misc/plot_sensor_locations.py +++ b/tutorials/intro/plot_40_sensor_locations.py @@ -1,4 +1,6 @@ """ +.. _tut-sensor-locations: + Working with sensor locations ============================= diff --git a/tutorials/intro/plot_40_projectors_background.py b/tutorials/preprocessing/plot_45_projectors_background.py similarity index 100% rename from tutorials/intro/plot_40_projectors_background.py rename to tutorials/preprocessing/plot_45_projectors_background.py diff --git a/tutorials/raw/plot_40_visualize_raw.py b/tutorials/raw/plot_40_visualize_raw.py index 0b6a1c6319c..09c4fc76e20 100644 --- a/tutorials/raw/plot_40_visualize_raw.py +++ b/tutorials/raw/plot_40_visualize_raw.py @@ -165,7 +165,7 @@ # with the :meth:`~mne.io.Raw.plot_sensors` method. A brief example is shown # here; notice that channels in ``raw.info['bads']`` are plotted in red. More # details and additional examples are given in the tutorial -# :doc:`../misc/plot_sensor_locations`. +# :ref:`tut-sensor-locations`. raw.plot_sensors(ch_type='eeg') From 47b59e03df7ead1ed2aecdd47e47316dae8c6c6b Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 15:32:23 -0700 Subject: [PATCH 22/27] cleanup --- doc/_includes/forward.rst | 75 +++++++++++++++------------------------ doc/_includes/inverse.rst | 11 +++--- 2 files changed, 33 insertions(+), 53 deletions(-) diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index fee4c59b4b1..a2ba55786ac 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -585,42 +585,29 @@ The coil geometry information is stored in the text file with the pound sign (#) are comments. A coil definition starts with a description line containing the following fields: -** <*class*>** +- :samp:`{}`: A number indicating class of this coil. - This is a number indicating class of this coil. +- :samp:`{}`: Coil ID value. This value is listed in the first column of + Tables :ref:`normal_coil_descriptions` and :ref:`accurate_coil_descriptions`. -** <*id*>** +- :samp:`{}`: The coil representation accuracy. Possible values and + their meanings are listed in :ref:`coil_accuracies`. - Coil id value. This value is listed in the first column of Tables - :ref:`normal_coil_descriptions` and :ref:`accurate_coil_descriptions`. +- :samp:`{}`: Number of integration points in this representation. -** <*accuracy*>** +- :samp:`{}`: The size of the coil. For circular coils this is the + diameter of the coil and for square ones the side length of the square. This + information is mainly included to facilitate drawing of the coil geometry. It + should not be employed to infer a coil approximation for the forward + calculations. - The coil representation accuracy. Possible values and their meanings are - listed in :ref:`coil_accuracies`. +- :samp:`{}`: The baseline of a this kind of a coil. This will be + zero for magnetometer coils. This information is mainly included to + facilitate drawing of the coil geometry. It should not be employed to infer + a coil approximation for the forward calculations. -** <*np*>** - - Number of integration points in this representation. - -** <*size/m*>** - - The size of the coil. For circular coils this is the diameter of the coil - and for square ones the side length of the square. This information is - mainly included to facilitate drawing of the coil geometry. It should not - be employed to infer a coil approximation for the forward calculations. - -** <*baseline/m*>** - - The baseline of a this kind of a coil. This will be zero for magnetometer - coils. This information is mainly included to facilitate drawing of the - coil geometry. It should not be employed to infer a coil approximation for - the forward calculations. - -** <*description*>** - - Short description of this kind of a coil. If the description contains - several words, it is enclosed in quotes. +- :samp:`{}`: Short description of this kind of a coil. If the + description contains several words, it is enclosed in quotes. .. tabularcolumns:: |p{0.1\linewidth}|p{0.5\linewidth}| @@ -638,34 +625,30 @@ description line containing the following fields: Each coil description line is followed by one or more integration point lines, consisting of seven numbers: -** <*weight*>** - - Gives the weight for this integration point (last column in Tables - :ref:`normal_coil_descriptions` and :ref:`accurate_coil_descriptions`). - -** <*x/m*> <*y/m*> <*z/m*>** - - Indicates the location of the integration point (fourth column in Tables - :ref:`normal_coil_descriptions` and :ref:`accurate_coil_descriptions`). +- :samp:`{}`: Gives the weight for this integration point (last column + in Tables :ref:`normal_coil_descriptions` and + :ref:`accurate_coil_descriptions`). -** <*nx*> <*ny*> <*nz*>** +- :samp:`{} {} {}`: Indicates the location of the integration + point (fourth column in Tables :ref:`normal_coil_descriptions` and + :ref:`accurate_coil_descriptions`). - Components of a unit vector indicating the field component to be selected. - Note that listing a separate unit vector for each integration points allows - the implementation of curved coils and coils with the gradiometer loops - tilted with respect to each other. +- :samp:`{} {} {}`: Components of a unit vector indicating the + field component to be selected. Note that listing a separate unit vector for + each integration points allows the implementation of curved coils and coils + with the gradiometer loops tilted with respect to each other. Creating the coil definition file --------------------------------- -The standard coil definition file $MNE_ROOT/share/mne/coil_def.dat +The standard coil definition file :file:`{$MNE_ROOT}/share/mne/coil_def.dat` is included with the MNE software package. The coil definition file can be recreated with the MNE-C utility ``mne_list_coil_def`` as follows: .. code-block:: console - mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat + $ mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat Computing the forward solution diff --git a/doc/_includes/inverse.rst b/doc/_includes/inverse.rst index c49e49e9bb8..6252cc6c672 100644 --- a/doc/_includes/inverse.rst +++ b/doc/_includes/inverse.rst @@ -21,13 +21,10 @@ Overview inverse-begin-content -Computing the inverse operator is accomplished -using :func:`mne.minimum_norm.make_inverse_operator` and -:func:`mne.minimum_norm.apply_inverse`. -The use of these functions is presented in the tutorial -:ref:`tut-inverse-methods`. - -The page starts with a mathematical description of the method. +Computing the inverse operator is accomplished using +:func:`mne.minimum_norm.make_inverse_operator` and +:func:`mne.minimum_norm.apply_inverse`. The use of these functions is presented +in the tutorial :ref:`tut-inverse-methods`. .. _minimum_norm_estimates: From 0f51bed8a0a264b4d532df7fcb955deca5be9119 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 16:19:37 -0700 Subject: [PATCH 23/27] remove reference to Martinos Ctr. --- doc/_includes/bem_model.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index 2f406d013aa..794c8c221cd 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -55,8 +55,7 @@ same time with the MPRAGEs or at least with the same scanner. For easy co-registration, the images should have FOV, matrix, slice thickness, gap, and slice orientation as the MPRAGE data. For information on suitable pulse sequences, see reference [B. Fischl *et al.* and J. Jovicich *et al.*, 2006] in -:ref:`CEGEGDEI`. At the Martinos Center, use of the 1.5-T Avanto scanner (Bay -2) is recommended for best results. +:ref:`CEGEGDEI`. Creation of the BEM meshes using this method involves the following steps: From 8cfc30ecc3473ee0cc415f560510c7010127fb21 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 16:20:35 -0700 Subject: [PATCH 24/27] delete unnecessary note --- doc/_includes/bem_model.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index 794c8c221cd..a3957cb0bd5 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -57,8 +57,7 @@ slice orientation as the MPRAGE data. For information on suitable pulse sequences, see reference [B. Fischl *et al.* and J. Jovicich *et al.*, 2006] in :ref:`CEGEGDEI`. -Creation of the BEM meshes using this method involves the -following steps: +Creation of the BEM meshes using this method involves the following steps: - Creating a synthetic 5-degree flip angle FLASH volume, register it with the MPRAGE data, and run the segmentation and meshing program. @@ -74,9 +73,6 @@ following steps: watershed output file while the other surfaces can be picked from the FLASH segmentation data. -.. note:: The following sections assume that you have run the appropriate - setup scripts to make both MNE and FreeSurfer software available. - Organizing MRI data into directories ------------------------------------ From f4a33ac7270d79f2157077197a578c2649caf9d8 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 17:02:33 -0700 Subject: [PATCH 25/27] add crossrefs from summary table to IO tutorial sections --- doc/_includes/data_formats.rst | 57 ++++++++++-------------- tutorials/io/plot_10_reading_meg_data.py | 18 ++++++++ tutorials/io/plot_20_reading_eeg_data.py | 29 ++++++++++++ 3 files changed, 71 insertions(+), 33 deletions(-) diff --git a/doc/_includes/data_formats.rst b/doc/_includes/data_formats.rst index 0d0d00bc9c7..2a85f4e7eb4 100644 --- a/doc/_includes/data_formats.rst +++ b/doc/_includes/data_formats.rst @@ -29,54 +29,45 @@ table). .. cssclass:: table-bordered .. rst-class:: midvalign -============ ============= ========= =================================== -Data type File format Extension MNE-Python function -============ ============= ========= =================================== -MEG Artemis123 .bin :func:`mne.io.read_raw_artemis123` +============ ============================================ ========= =================================== +Data type File format Extension MNE-Python function +============ ============================================ ========= =================================== +MEG :ref:`Artemis123 ` .bin :func:`mne.io.read_raw_artemis123` -MEG 4-D .dir :func:`mne.io.read_raw_bti` - Neuroimaging - / BTi +MEG :ref:`4-D Neuroimaging / BTi ` .dir :func:`mne.io.read_raw_bti` -MEG CTF .dir :func:`mne.io.read_raw_ctf` +MEG :ref:`CTF ` .dir :func:`mne.io.read_raw_ctf` -MEG Elekta .fif :func:`mne.io.read_raw_fif` - Neuromag +MEG :ref:`Elekta Neuromag ` .fif :func:`mne.io.read_raw_fif` -MEG KIT .sqd :func:`mne.io.read_raw_kit`, - :func:`mne.read_epochs_kit` +MEG :ref:`KIT ` .sqd :func:`mne.io.read_raw_kit`, + :func:`mne.read_epochs_kit` +MEG and EEG :ref:`FieldTrip ` .mat :func:`mne.io.read_raw_fieldtrip`, + :func:`mne.read_epochs_fieldtrip`, + :func:`mne.read_evoked_fieldtrip` -MEG and EEG FieldTrip .mat :func:`mne.io.read_raw_fieldtrip`, - :func:`mne.read_epochs_fieldtrip`, - :func:`mne.read_evoked_fieldtrip` +EEG :ref:`Brainvision ` .vhdr :func:`mne.io.read_raw_brainvision` -EEG Brainvision .vhdr :func:`mne.io.read_raw_brainvision` +EEG :ref:`Biosemi data format ` .bdf :func:`mne.io.read_raw_bdf` -EEG Biosemi data .bdf :func:`mne.io.read_raw_bdf` - format +EEG :ref:`Neuroscan CNT ` .cnt :func:`mne.io.read_raw_cnt` -EEG Neuroscan CNT .cnt :func:`mne.io.read_raw_cnt` +EEG :ref:`European data format ` .edf :func:`mne.io.read_raw_edf` -EEG European data .edf :func:`mne.io.read_raw_edf` - format +EEG :ref:`EEGLAB ` .set :func:`mne.io.read_raw_eeglab`, + :func:`mne.read_epochs_eeglab` -EEG EEGLAB .set :func:`mne.io.read_raw_eeglab`, - :func:`mne.read_epochs_eeglab` +EEG :ref:`EGI simple binary ` .egi :func:`mne.io.read_raw_egi` -EEG EGI simple .egi :func:`mne.io.read_raw_egi` - binary +EEG :ref:`EGI MFF format ` .mff :func:`mne.io.read_raw_egi` -EEG EGI MFF .mff :func:`mne.io.read_raw_egi` - format +EEG :ref:`eXimia ` .nxe :func:`mne.io.read_raw_eximia` -EEG eXimia .nxe :func:`mne.io.read_raw_eximia` +EEG :ref:`General data format ` .gdf :func:`mne.io.read_raw_gdf` -EEG General data .gdf :func:`mne.io.read_raw_gdf` - format - -EEG Nicolet .data :func:`mne.io.read_raw_nicolet` -============ ============= ========= =================================== +EEG :ref:`Nicolet ` .data :func:`mne.io.read_raw_nicolet` +============ ============================================ ========= =================================== More details are provided in the tutorials in the :ref:`tut-data-formats` section. diff --git a/tutorials/io/plot_10_reading_meg_data.py b/tutorials/io/plot_10_reading_meg_data.py index 4b63ff5fa93..208f7a0418a 100644 --- a/tutorials/io/plot_10_reading_meg_data.py +++ b/tutorials/io/plot_10_reading_meg_data.py @@ -12,6 +12,9 @@ :local: :depth: 2 + +.. _import-neuromag: + Elekta NeuroMag (.fif) ====================== @@ -21,11 +24,17 @@ with MaxFilter, they may need to be loaded with ``mne.io.read_raw_fif(..., allow_maxshield=True)``. + +.. _import-artemis: + Artemis123 (.bin) ================= MEG data from the Artemis123 system can be read with\ :func:`mne.io.read_raw_artemis123`. + +.. _import-bti: + 4-D Neuroimaging / BTI data (dir) ================================= @@ -55,6 +64,9 @@ compensated, there will be a small error in the forward calculations, whose significance has not been evaluated carefully at this time. + +.. _import-ctf: + CTF data (dir) ============== @@ -127,6 +139,9 @@ This operation is performed by :meth:`mne.io.Raw.apply_gradient_compensation`. + +.. _import-kit: + KIT MEG system data (.sqd) ========================== @@ -208,6 +223,9 @@ The threshold value :math:`t` can be adjusted with the ``stimthresh`` parameter. + +.. _import-fieldtrip: + FieldTrip MEG/EEG data (.mat) ============================= diff --git a/tutorials/io/plot_20_reading_eeg_data.py b/tutorials/io/plot_20_reading_eeg_data.py index 283c872d399..e465f90b176 100644 --- a/tutorials/io/plot_20_reading_eeg_data.py +++ b/tutorials/io/plot_20_reading_eeg_data.py @@ -14,6 +14,8 @@ :depth: 2 +.. _import-bv: + BrainVision (.vhdr, .vmrk, .eeg) ================================ @@ -44,6 +46,9 @@ `example `_ for an instruction. + +.. _import-edf: + European data format (.edf) =========================== @@ -59,6 +64,9 @@ `gist `__ can be used to save any mne.io.Raw into EDF/EDF+/BDF/BDF+. + +.. _import-biosemi: + BioSemi data format (.bdf) ========================== @@ -81,6 +89,9 @@ supported in the fif format these data will be changed to 4-byte integers in the conversion. + +.. _import-gdf: + General data format (.gdf) ========================== @@ -94,6 +105,9 @@ age, etc.) and allows storing several physical units and other properties. Both specifications are supported in MNE. + +.. _import-cnt: + Neuroscan CNT data format (.cnt) ================================ @@ -111,6 +125,9 @@ If you are not sure about the channel locations in the header, use of a montage is encouraged. + +.. _import-egi: + EGI simple binary (.egi) ======================== @@ -118,20 +135,32 @@ The EGI raw files are simple binary files with a header and can be exported from using the EGI Netstation acquisition software. + +.. _import-mff: + EGI MFF (.mff) ============== These files can also be read with :func:`mne.io.read_raw_egi`. + +.. _import-set: + EEGLAB set files (.set) ======================= EEGLAB .set files can be read in using :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab`. + +.. _import-nicolet: + Nicolet (.data) =============== These files can be read with :func:`mne.io.read_raw_nicolet`. + +.. _import-nxe: + eXimia EEG data (.nxe) ====================== From b58471a4d14a893523b3dcb53d6f0d614ae65850 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 23 Sep 2019 17:04:52 -0700 Subject: [PATCH 26/27] fix title capitalization --- doc/overview/implementation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview/implementation.rst b/doc/overview/implementation.rst index eae6bd23410..a7d7407c8b5 100644 --- a/doc/overview/implementation.rst +++ b/doc/overview/implementation.rst @@ -1,6 +1,6 @@ .. _implementation: -Algorithms and Other Implementation details +Algorithms and other implementation details =========================================== This page describes some of the technical details of MNE-Python implementation. From 4a24002fbf74038b20987342234e4277dfb3b773 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Mon, 23 Sep 2019 23:14:08 -0400 Subject: [PATCH 27/27] DOC: Cleanups --- doc/_includes/bem_model.rst | 57 ++++------------- doc/_includes/data_formats.rst | 6 +- doc/_includes/forward.rst | 62 ++---------------- doc/_includes/morph.rst | 9 +-- doc/_includes/ssp.rst | 3 +- doc/overview/command_line.rst | 114 --------------------------------- doc/overview/matlab.rst | 5 +- mne/bem.py | 32 ++++----- mne/channels/channels.py | 2 +- mne/gui/_coreg_gui.py | 2 +- mne/source_estimate.py | 14 ++-- 11 files changed, 57 insertions(+), 249 deletions(-) delete mode 100644 doc/overview/command_line.rst diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index a3957cb0bd5..44cb7ca14b0 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -79,43 +79,10 @@ Organizing MRI data into directories Since all images comprising the multi-echo FLASH data are contained in a single series, it is necessary to organize the images according to the echoes before -proceeding to the BEM surface reconstruction. This is accomplished by the -``mne_organize_dicom`` script, which creates a directory tree with symbolic -links to the original DICOM image files. To run ``mne_organize_dicom``, proceed -as follows: - -- Copy all of your images or create symbolic links to them in a single - directory. The images must be in DICOM format. We will refer to this - directory as :file:`{}`. - -- Create another directory to hold the output of ``mne_organize_dicom``. We - will refer to this directory as :file:`{}`. - -- Change the working directory to :file:`{}`. - -- Say ``mne_organize_dicom`` :file:`{}`. Depending on the total number - of images in :file:`{}` this script may take quite a while to run. - Progress is indicated by listing the number of images processed at 50-image - intervals. - -As a result, :file:`{}` will contain several directories named -:file:`{}_{}` corresponding to the different -series of images acquired. Spaces and parenthesis in protocol names will be -replaced by underscores. Under each of these directories there are one or more -directories named :file:`{}` number corresponding to one or -more subsets of images in this series (protocol). The only subset division -scheme implemented in ``mne_organize_dicom`` is that according to different -echoes, typically found in multi-echo FLASH data. These second level -directories will contain symbolic links pointing to the original image data. - -.. note:: ``mne_organize_dicom`` was developed specifically for Siemens DICOM - data. Its correct behavior with DICOM files originating from other MRI - scanners has not been verified at this time. - -.. note:: Since ``mne_organize_dicom`` processes all images, not only the FLASH - data, it may be a useful preprocessing step before FreeSurfer reconstruction - process as well. - +proceeding to the BEM surface reconstruction. This can be accomplished by using +`dcm2niix `__ +or the MNE-C tool ``mne_organize_dicom`` if necessary, then use +:func:`mne.bem.convert_flash_mris`. Creating the surface tessellations ---------------------------------- @@ -124,7 +91,7 @@ The BEM surface segmentation and tessellation is automated with the script :ref:`gen_mne_flash_bem`. It assumes that a FreeSurfer reconstruction for this subject is already in place. -Before running ``mne flash_bem`` do the following: +Before running :ref:`gen_mne_flash_bem` do the following: - Create symbolic links from the directories containing the 5-degree and 30-degree flip angle FLASH series to ``flash05`` and ``flash30``, @@ -141,13 +108,14 @@ Before running ``mne flash_bem`` do the following: - :samp:`cp {} flash30` -- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment variables +- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment variables or pass + the ``--subjects-dir`` and ``--subject`` options to ``mne flash_bem`` .. note:: If ``mne flash_bem`` is run with the ``--noflash30`` option, the :file:`flash30` directory is not needed, *i.e.*, only the 5-degree flip angle flash data are employed. -It may take a while for mne_flash_bem to complete. It uses the FreeSurfer +It may take a while for ``mne flash_bem`` to complete. It uses the FreeSurfer directory structure under ``$SUBJECTS_DIR/$SUBJECT``. The script encapsulates the following processing steps: @@ -155,7 +123,7 @@ the following processing steps: the FLASH directories in ``mri/flash``. The files will be called :file:`mef {}_{}.mgz`. -- If the ``--unwarp`` option is specified, run grad_unwarp and produce +- If the ``unwarp=True`` option is specified, run grad_unwarp and produce files :file:`mef {}_{}u.mgz`. These files will be then used in the following steps. @@ -191,5 +159,8 @@ Inspecting the meshes --------------------- It is advisable to check the validity of the BEM meshes before -using them. This can be done with help of ``tkmedit`` or ``freeview`` -in PySurfer, or using :func:`mne.viz.plot_bem`. +using them. This can be done with: + +- the ``--view`` option of :ref:`gen_mne_flash_bem` +- calling :func:`mne.viz.plot_bem` directly +- Using FreeSurfer tools ``tkmedit`` or ``freeview`` diff --git a/doc/_includes/data_formats.rst b/doc/_includes/data_formats.rst index 2a85f4e7eb4..3263f00b2ad 100644 --- a/doc/_includes/data_formats.rst +++ b/doc/_includes/data_formats.rst @@ -34,11 +34,11 @@ Data type File format Extension MNE-Pytho ============ ============================================ ========= =================================== MEG :ref:`Artemis123 ` .bin :func:`mne.io.read_raw_artemis123` -MEG :ref:`4-D Neuroimaging / BTi ` .dir :func:`mne.io.read_raw_bti` +MEG :ref:`4-D Neuroimaging / BTi ` :func:`mne.io.read_raw_bti` -MEG :ref:`CTF ` .dir :func:`mne.io.read_raw_ctf` +MEG :ref:`CTF ` :func:`mne.io.read_raw_ctf` -MEG :ref:`Elekta Neuromag ` .fif :func:`mne.io.read_raw_fif` +MEG and EEG :ref:`Elekta Neuromag ` .fif :func:`mne.io.read_raw_fif` MEG :ref:`KIT ` .sqd :func:`mne.io.read_raw_kit`, :func:`mne.read_epochs_kit` diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index a2ba55786ac..e46f28b1b80 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -186,7 +186,7 @@ and coordinate corresponds to the location of the center of a voxel. Detailed information on the FreeSurfer MRI systems can be found at https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems. - + The symbols :math:`T_x` are defined in :ref:`coordinate_system_figure`. .. tabularcolumns:: |p{0.2\linewidth}|p{0.3\linewidth}|p{0.5\linewidth}| .. table:: Coordinate transformations in FreeSurfer and MNE software packages. @@ -216,12 +216,6 @@ and | :math:`T_+` | Hardcoded in software | Hardcoded in software. | +------------------------------+-------------------------------+-------------------------------------------------+ -.. note:: - The symbols :math:`T_x` are defined in :ref:`coordinate_system_figure`. - mne_make_cor_set /mne_setup_mri prior to release 2.6 did not include - transformations :math:`T_3`, :math:`T_4`, :math:`T_-`, and :math:`T_+` in - the fif files produced. - .. _head_device_coords: The head and device coordinate systems @@ -449,7 +443,7 @@ data: T/m. .. note:: The coil geometry information is stored in the file - :file:`{$MNE_ROOT}/share/mne/data/coil_def.dat`, which is + :file:`mne/data/coil_def.dat`, which is automatically created by the MNE-C utility ``mne_list_coil_def``. .. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| @@ -638,18 +632,6 @@ consisting of seven numbers: each integration points allows the implementation of curved coils and coils with the gradiometer loops tilted with respect to each other. -Creating the coil definition file ---------------------------------- - -The standard coil definition file :file:`{$MNE_ROOT}/share/mne/coil_def.dat` -is included with the MNE software package. The coil definition file -can be recreated with the MNE-C utility ``mne_list_coil_def`` -as follows: - -.. code-block:: console - - $ mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat - Computing the forward solution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -717,9 +699,9 @@ EEG forward solution in the sphere model When the sphere model is employed, the computation of the EEG solution can be substantially accelerated by using approximation methods described by Mosher, Zhang, and Berg, see :ref:`CEGEGDEI` (Mosher *et al.* and references therein). -``mne_forward_solution`` approximates the solution with three dipoles in a -homogeneous sphere whose locations and amplitudes are determined by minimizing -the cost function: +:func:`mne.make_forward_solution` approximates the solution with three dipoles +in a homogeneous sphere whose locations and amplitudes are determined by +minimizing the cost function: .. math:: S(r_1,\dotsc,r_m\ ,\ \mu_1,\dotsc,\mu_m) = \int_{scalp} {(V_{true} - V_{approx})}\,dS @@ -732,40 +714,6 @@ expressed in closed form using an expansion of the potentials in spherical harmonics. The formula is evaluated for the most superficial dipoles, *i.e.*, those lying just inside the inner skull surface. -.. _forward_field_derivatives: - -Field derivatives ------------------ - -If the ``--grad`` option is specified, mne_forward_solution includes the -derivatives of the forward solution with respect to the dipole location -coordinates to the output file. Let - -.. math:: G_k = [g_{xk} g_{yk} g_{zk}] - -be the :math:`N_{chan} \times 3` matrix containing the signals produced by -three orthogonal dipoles at location :math:`r_k` making up :math:`N_{chan} -\times 3N_{source}` the gain matrix - -.. math:: G = [G_1 \dotso G_{N_{source}}]\ . - -With the ``--grad`` option, the output from mne_forward_solution also contains -the :math:`N_{chan} \times 9N_{source}` derivative matrix - -.. math:: D = [D_1 \dotso D_{N_{source}}]\ , - -where - -.. math:: - D_k = [\frac{\delta g_{xk}}{\delta x_k} \frac{\delta g_{xk}}{\delta y_k} \frac{\delta g_{xk}}{\delta z_k} \frac{\delta g_{yk}}{\delta x_k} \frac{\delta g_{yk}}{\delta y_k} \frac{\delta g_{yk}}{\delta z_k} \frac{\delta g_{zk}}{\delta x_k} \frac{\delta g_{zk}}{\delta y_k} \frac{\delta g_{zk}}{\delta z_k}]\ , - -where :math:`x_k`, :math:`y_k`, and :math:`z_k` are the location coordinates of -the :math:`k^{th}` dipole. If the dipole orientations are to the cortical -normal with the ``--fixed`` option, the dimensions of :math:`G` and :math:`D` -are :math:`N_{chan} \times N_{source}` and :math:`N_{chan} \times 3N_{source}`, -respectively. Both :math:`G` and :math:`D` can be read with the -mne_read_forward_solution Matlab function, see Table 10.1. - Averaging forward solutions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/_includes/morph.rst b/doc/_includes/morph.rst index f609f9dc743..99aaed321f9 100644 --- a/doc/_includes/morph.rst +++ b/doc/_includes/morph.rst @@ -6,10 +6,11 @@ Morphing and averaging source estimates The spherical morphing of BEM surfaces accomplished by FreeSurfer can be employed to bring data from different subjects into a common anatomical frame. This page describes utilities which make use of the spherical :term:`morphing` -procedure. ``mne_morph_labels`` morphs label files between subjects allowing -the definition of labels in a one brain and transforming them to anatomically -analogous labels in another. ``mne_average_estimates`` offers the capability to -compute averages of data computed with the MNE software across subjects. +procedure. :func:`mne.morph_labels` morphs label files between subjects +allowing the definition of labels in a one brain and transforming them to +anatomically analogous labels in another. :meth:`mne.SourceMorph.apply` offers +the capability to transform all subject data to the same space and, +e.g., compute averages of data across subjects. .. contents:: Page contents :local: diff --git a/doc/_includes/ssp.rst b/doc/_includes/ssp.rst index 823dd1f8167..1421a1963a3 100644 --- a/doc/_includes/ssp.rst +++ b/doc/_includes/ssp.rst @@ -87,7 +87,8 @@ Estimation of the noise subspace As described above, application of SSP requires the estimation of the signal vectors :math:`b_1 \dotso b_m` constituting the noise subspace. The most common -approach, also implemented in mne_browse_raw is to compute a covariance matrix +approach, also implemented in :func:`mne.compute_proj_raw` +is to compute a covariance matrix of empty room data, compute its eigenvalue decomposition, and employ the eigenvectors corresponding to the highest eigenvalues as basis for the noise subspace. It is also customary to use a separate set of vectors for diff --git a/doc/overview/command_line.rst b/doc/overview/command_line.rst deleted file mode 100644 index 0f090ac331e..00000000000 --- a/doc/overview/command_line.rst +++ /dev/null @@ -1,114 +0,0 @@ -:orphan: - -.. _command_line_tutorial: - -Getting started with MNE Unix command line tools -================================================ - -This tutorial is a really short step by step presentation -of an analysis pipeline using the MNE-C command line tools. -These tools are UNIX commands and therefore only run on -Mac OS or Linux. - -See :ref:`install_mne_c` to setup your system for using the -MNE-C tools. - -The quick start guide shows how to run a standard processing of the -sample data set provided with MNE. The sample dataset is further -described in :ref:`datasets`. - -All the following lines are to be run in a terminal and not in a Python -interpreter. - -First define your subject:: - - export SUBJECT=sample - -Build your source space:: - - # MRI (this is not really needed for anything) - mne_setup_mri --overwrite - - # Source space - mne_setup_source_space --ico -6 --overwrite - -Prepare for forward computation:: - - # For homogeneous volume conductor (just inner skull) - mne_setup_forward_model --homog --surf --ico 4 - - # or for a three compartment model (inner and outer skull and skin) - mne_setup_forward_model --surf --ico 4 - -List your bad channels in a file. Example sample_bads.bad contains:: - - MEG 2443 - EEG 053 - -Mark bad channels:: - - mne_mark_bad_channels --bad sample_bads.bad sample_audvis_raw.fif - -Compute averaging:: - - mne_process_raw --raw sample_audvis_raw.fif --lowpass 40 --projoff \ - --saveavetag -ave --ave audvis.ave - -Compute the noise covariance matrix:: - - mne_process_raw --raw sample_audvis_raw.fif --lowpass 40 --projoff \ - --savecovtag -cov --cov audvis.cov - -Compute forward solution a.k.a. lead field:: - - # for MEG only - mne_do_forward_solution --mindist 5 --spacing oct-6 \ - --meas sample_audvis_raw.fif --bem sample-5120 --megonly --overwrite \ - --fwd sample_audvis-meg-oct-6-fwd.fif - - # for EEG only - mne_do_forward_solution --mindist 5 --spacing oct-6 \ - --meas sample_audvis_raw.fif --bem sample-5120-5120-5120 --eegonly \ - --fwd sample_audvis-eeg-oct-6-fwd.fif - - # for both EEG and MEG - mne_do_forward_solution --mindist 5 --spacing oct-6 \ - --meas sample_audvis_raw.fif --bem sample-5120-5120-5120 \ - --fwd sample_audvis-meg-eeg-oct-6-fwd.fif - -Compute MNE inverse operators:: - - # Note: The MEG/EEG forward solution could be used for all - mne_do_inverse_operator --fwd sample_audvis-meg-oct-6-fwd.fif \ - --depth --loose 0.2 --meg - - mne_do_inverse_operator --fwd sample_audvis-eeg-oct-6-fwd.fif \ - --depth --loose 0.2 --eeg - - mne_do_inverse_operator --fwd sample_audvis-meg-eeg-oct-6-fwd.fif \ - --depth --loose 0.2 --eeg --meg - -Produce stc files (activation files):: - - # for MEG - mne_make_movie --inv sample_audvis-meg-oct-6-${mod}-inv.fif \ - --meas sample_audvis-ave.fif \ - --tmin 0 --tmax 250 --tstep 10 --spm \ - --smooth 5 --bmin -100 --bmax 0 --stc sample_audvis-meg - - # for EEG - mne_make_movie --inv sample_audvis-eeg-oct-6-${mod}-inv.fif \ - --meas sample_audvis-ave.fif \ - --tmin 0 --tmax 250 --tstep 10 --spm \ - --smooth 5 --bmin -100 --bmax 0 --stc sample_audvis-eeg - - # for MEG and EEG combined - mne_make_movie --inv sample_audvis-meg-eeg-oct-6-${mod}-inv.fif \ - --meas sample_audvis-ave.fif \ - --tmin 0 --tmax 250 --tstep 10 --spm \ - --smooth 5 --bmin -100 --bmax 0 --stc sample_audvis-meg-eeg - -And, we're done! - -See also :ref:`python_commands` for more command line tools -using MNE-Python. \ No newline at end of file diff --git a/doc/overview/matlab.rst b/doc/overview/matlab.rst index 42296747463..d6fb04c5bfc 100644 --- a/doc/overview/matlab.rst +++ b/doc/overview/matlab.rst @@ -1133,10 +1133,9 @@ The documented structures are: | | matrix | | +-------------------------+-------------+----------------------------------------------------------+ | sol_grad | named | The derivatives of the forward solution with respect to | - | | matrix | the dipole location coordinates, see | - | | | :ref:`forward_field_derivatives`. | + | | matrix | the dipole location coordinates. | | | | This field is present only if the forward solution was | - | | | computed with the ``--grad`` option. | + | | | computed with the ``--grad`` option in MNE-C. | +-------------------------+-------------+----------------------------------------------------------+ | mri_head_t | trans | Transformation from the MRI coordinate frame to the | | | | (Neuromag) head coordinate frame. | diff --git a/mne/bem.py b/mne/bem.py index 317476f0c81..993a5c1a3bb 100644 --- a/mne/bem.py +++ b/mne/bem.py @@ -1609,22 +1609,22 @@ def convert_flash_mris(subject, flash30=True, convert=True, unwarp=False, Before running this script do the following: (unless convert=False is specified) - 1. Copy all of your FLASH images in a single directory and - create a directory to hold the output of mne_organize_dicom - 2. cd to and run - $ mne_organize_dicom - to create an appropriate directory structure - 3. Create symbolic links to make flash05 and flash30 point to the - appropriate series: - $ ln -s flash05 - $ ln -s flash30 - Some partition formats (e.g. FAT32) do not support symbolic links. - In this case, copy the file to the appropriate series: - $ cp flash05 - $ cp flash30 - 4. cd to the directory where flash05 and flash30 links are - 5. Set SUBJECTS_DIR and SUBJECT environment variables appropriately - 6. Run this script + 1. Copy all of your FLASH images in a single directory and + create a directory to hold the output of mne_organize_dicom + 2. cd to and run + $ mne_organize_dicom + to create an appropriate directory structure + 3. Create symbolic links to make flash05 and flash30 point to the + appropriate series: + $ ln -s flash05 + $ ln -s flash30 + Some partition formats (e.g. FAT32) do not support symbolic links. + In this case, copy the file to the appropriate series: + $ cp flash05 + $ cp flash30 + 4. cd to the directory where flash05 and flash30 links are + 5. Set SUBJECTS_DIR and SUBJECT environment variables appropriately + 6. Run this script This function assumes that the Freesurfer segmentation of the subject has been completed. In particular, the T1.mgz and brain.mgz MRI volumes diff --git a/mne/channels/channels.py b/mne/channels/channels.py index 428d34663e7..668a25ac7d3 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -1312,7 +1312,7 @@ def fix_mag_coil_types(info): .. note:: The effect of the difference between the coil sizes on the current estimates computed by the MNE software is very small. - Therefore the use of mne_fix_mag_coil_types is not mandatory. + Therefore the use of ``fix_mag_coil_types`` is not mandatory. """ old_mag_inds = _get_T1T2_mag_inds(info) diff --git a/mne/gui/_coreg_gui.py b/mne/gui/_coreg_gui.py index a9f20685810..cfe42ed8e19 100644 --- a/mne/gui/_coreg_gui.py +++ b/mne/gui/_coreg_gui.py @@ -185,7 +185,7 @@ class CoregModel(HasPrivateTraits): scale_labels = Bool(True, desc="whether to scale *.label files") copy_annot = Bool(True, desc="whether to copy *.annot files for scaled " "subject") - prepare_bem_model = Bool(True, desc="whether to run mne_prepare_bem_model " + prepare_bem_model = Bool(True, desc="whether to run make_bem_solution " "after scaling the MRI") # secondary to parameters diff --git a/mne/source_estimate.py b/mne/source_estimate.py index 2b21464c4fb..73eefd2e769 100644 --- a/mne/source_estimate.py +++ b/mne/source_estimate.py @@ -2335,8 +2335,9 @@ def spatio_temporal_dist_connectivity(src, n_times, dist, verbose=None): ---------- src : instance of SourceSpaces The source space must have distances between vertices computed, such - that src['dist'] exists and is useful. This can be obtained using MNE - with a call to mne_add_patch_info with the --dist option. + that src['dist'] exists and is useful. This can be obtained + with a call to :func:`mne.setup_source_space` with the + ``add_dist=True`` option. n_times : int Number of time points dist : float @@ -2354,8 +2355,8 @@ def spatio_temporal_dist_connectivity(src, n_times, dist, verbose=None): during time 2, etc. """ if src[0]['dist'] is None: - raise RuntimeError('src must have distances included, consider using\n' - 'mne_add_patch_info with --dist argument') + raise RuntimeError('src must have distances included, consider using ' + 'setup_source_space with add_dist=True') edges = sparse_block_diag([s['dist'][s['vertno'], :][:, s['vertno']] for s in src]) edges.data[:] = np.less_equal(edges.data, dist) @@ -2418,8 +2419,9 @@ def spatial_dist_connectivity(src, dist, verbose=None): ---------- src : instance of SourceSpaces The source space must have distances between vertices computed, such - that src['dist'] exists and is useful. This can be obtained using MNE - with a call to mne_add_patch_info with the --dist option. + that src['dist'] exists and is useful. This can be obtained + with a call to :func:`mne.setup_source_space` with the + ``add_dist=True`` option. dist : float Maximal geodesic distance (in m) between vertices in the source space to consider neighbors.