[MRG] New SourceMorph object and support for volume data in morphing (m…

…ne-tools#5466)
DLyzhou · Aug 30, 2018 · 6104472 · 6104472
1 parent b7c8d9c
commit 6104472
Show file tree

Hide file tree

Showing 35 changed files with 2,543 additions and 885 deletions.
diff --git a/Makefile b/Makefile
@@ -113,7 +113,7 @@ docstring:
 	@$(PYTESTS) --doctest-modules mne/tests/test_docstring_parameters.py
 
 check-manifest:
-	check-manifest --ignore .circleci*,doc,logo,mne/io/*/tests/data*,mne/io/tests/data,mne/preprocessing/tests/data
+	check-manifest --ignore .circleci*,doc,logo,mne/io/*/tests/data*,mne/io/tests/data,mne/preprocessing/tests/data,.DS_Store
 
 pep:
 	@$(MAKE) -k flake pydocstyle docstring codespell-error check-manifest

diff --git a/README.rst b/README.rst
@@ -91,7 +91,7 @@ For full functionality, some functions require:
 - Pandas >= 0.13
 - Picard >= 0.3
 - CuPy >= 4.0 (for NVIDIA CUDA acceleration)
-
+- DIPY >= 0.10.1
 
 Contributing to MNE-Python
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/doc/_templates/class.rst b/doc/_templates/class.rst
@@ -8,5 +8,3 @@
 
    {% block methods %}
    {% endblock %}
-
-
diff --git a/doc/conf.py b/doc/conf.py
@@ -292,6 +292,7 @@
     'surfer': ('https://pysurfer.github.io/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
     'statsmodels': ('http://www.statsmodels.org/stable/', None),
+    'dipy': ('http://nipy.org/dipy', None),
 }
 
 examples_dirs = ['../examples', '../tutorials']

diff --git a/doc/documentation.rst b/doc/documentation.rst
@@ -371,10 +371,10 @@ There are also **examples**, which contain a short use-case to highlight MNE-fun
 .. toctree::
     :maxdepth: 1
 
+    auto_tutorials/plot_background_freesurfer.rst
     manual/source_localization/forward.rst
     manual/source_localization/inverse.rst
-    manual/source_localization/morph.rst
-    auto_tutorials/plot_background_freesurfer.rst
+    auto_tutorials/plot_morph_stc.rst
 
 **Getting data to source space**
 
@@ -390,6 +390,7 @@ There are also **examples**, which contain a short use-case to highlight MNE-fun
     auto_tutorials/plot_point_spread.rst
     auto_tutorials/plot_dipole_orientations.rst
     auto_tutorials/plot_dics.rst
+    auto_tutorials/plot_background_freesurfer.rst
 
 
 .. raw:: html
@@ -433,7 +434,8 @@ There are also **examples**, which contain a short use-case to highlight MNE-fun
     auto_examples/inverse/plot_mixed_norm_inverse.rst
     auto_examples/inverse/plot_mne_crosstalk_function.rst
     auto_examples/inverse/plot_mne_point_spread_function.rst
-    auto_examples/inverse/plot_morph_data.rst
+    auto_examples/inverse/plot_morph_surface_stc.rst
+    auto_examples/inverse/plot_morph_volume_stc.rst
     auto_examples/inverse/plot_rap_music.rst
     auto_examples/inverse/plot_read_stc.rst
     auto_examples/inverse/plot_read_inverse.rst

diff --git a/doc/faq.rst b/doc/faq.rst
@@ -269,32 +269,6 @@ For expert use cases or debugging the alternative estimators can also be compare
 This will plot the whitened evoked for the optimal estimator and display the GFPs
 for all estimators as separate lines in the related panel.
 
-Morphing data
-=============
-
-Should I morph my source estimates using ``morph`` or ``morph_precomputed``?
-----------------------------------------------------------------------------
-The two functions :func:`mne.SourceEstimate.morph` and
-:func:`mne.SourceEstimate.morph_precomputed` perform the same operation:
-taking surface-based source space data from one subject and
-morphing it to another using a smoothing procedure. However, they can
-take different amounts of time to perform the computation.
-
-To use :func:`mne.SourceEstimate.morph_precomputed`, you must first
-precompute a morphing matrix with :func:`mne.compute_morph_matrix` which
-can take some time, but then the actual morphing operation carried out by
-:func:`mne.SourceEstimate.morph_precomputed` is very fast, even for
-:class:`mne.SourceEstimate` objects with many time points. The method
-:func:`mne.SourceEstimate.morph`, by contrast, smooths the data by operating
-directly on the data, which can be **very slow** with many time points.
-If there are thousands of time points, then
-:func:`mne.SourceEstimate.morph_precomputed` will be much faster; if there
-are a few time points, then :func:`mne.SourceEstimate.morph` will be faster.
-For data sizes in between, we advise testing to determine which is best,
-although some developers choose to always use
-:func:`mne.SourceEstimate.morph_precomputed` since it will rarely take
-a long time.
-
 References
 ----------
 

diff --git a/doc/glossary.rst b/doc/glossary.rst
@@ -75,6 +75,10 @@ MNE-Python core terminology and general concepts
         See :ref:`sphx_glr_auto_tutorials_plot_info.py` for a narrative
         overview.
 
+    label
+        A :class:`Label` refers to a region in the cortex, also often called
+        a region of interest (ROI) in the literature.
+
     montage
         EEG channel names and the relative positions of the sensor w.r.t. the scalp.
         See :class:`Montage <channels.Montage>` for the API of the corresponding object

diff --git a/doc/manual/cookbook.rst b/doc/manual/cookbook.rst
@@ -431,4 +431,4 @@ done *e.g.*, to ``subject='fsaverage'`` as::
 
     >>> stc_fsaverage = stc.morph('fsaverage')  # doctest: +SKIP
 
-See :ref:`ch_morph` for more information.
+See :ref:`sphx_glr_auto_tutorials_plot_morph_stc.py` for more information.
diff --git a/doc/manual/source_localization/inverse.rst b/doc/manual/source_localization/inverse.rst
@@ -471,8 +471,8 @@ produce stc or w files which contain the numerical current estimate
 data in a simple binary format for postprocessing. These files can
 be displayed in :ref:`mne_analyze`,
 see :ref:`ch_interactive_analysis`, utilized in the cross-subject averaging
-process, see :ref:`ch_morph`, and read into Matlab using the MNE
-Matlab toolbox, see :ref:`ch_matlab`.
+process, see :ref:`sphx_glr_auto_tutorials_plot_morph_stc.py`,
+and read into Matlab using the MNE Matlab toolbox, see :ref:`ch_matlab`.
 
 
 .. _computing_inverse:

diff --git a/doc/manual/source_localization/morph.rst b/doc/manual/source_localization/morph.rst
@@ -1,4 +1,4 @@
-
+:orphan:
 
 .. _ch_morph:
 
@@ -116,6 +116,7 @@ created to assist mne_analyze and mne_make_movie in
 morphing. Since the morphing maps described above take a while to
 compute, it is beneficial to construct all necessary maps in advance
 before using mne_make_movie .
+
 The precomputed morphing maps are located in ``$SUBJECTS_DIR/morph-maps`` . mne_make_morph_maps creates
 this directory automatically if it does not exist. If this directory
 exists when mne_analyze or mne_make_movie is run

diff --git a/doc/python_reference.rst b/doc/python_reference.rst
@@ -763,27 +763,26 @@ Source Space Data
    SourceEstimate
    VectorSourceEstimate
    VolSourceEstimate
+   SourceMorph
 
 .. autosummary::
    :toctree: generated/
    :template: function.rst
 
+   compute_source_morph
    head_to_mni
    head_to_mri
-   compute_morph_matrix
    extract_label_time_course
    grade_to_tris
    grade_to_vertices
    grow_labels
    label_sign_flip
-   morph_data
-   morph_data_precomputed
    random_parcellation
    read_labels_from_annot
    read_dipole
    read_label
    read_source_estimate
-   save_stc_as_volume
+   read_source_morph
    split_label
    stc_to_label
    transform_surface_to

diff --git a/doc/whats_new.rst b/doc/whats_new.rst
@@ -19,6 +19,8 @@ Current
 Changelog
 ~~~~~~~~~
 
+- Add :func:`mne.compute_source_morph` which creates a :class:`mne.SourceMorph` object to unify morphing any type of source estimates (surface or volume) from one subject to another for group studies. It is now possible to do group studies when working on the volume with MNE. Work by `Tommy Clausner`_ during GSOC 2018 with the help of `Alex Gramfort`_ and `Eric Larson`_.
+
 - Add ability to pass threshold for EOG to :func:`mne.preprocessing.find_eog_events` and :func:`mne.preprocessing.create_eog_epochs` by `Peter Molfese_`
 
 - Add possibility to save :class:`mne.VolSourceEstimate` and :class:`mne.MixedSourceEstimate` to HDF5 format (file extension .h5) with :meth:`mne.VolSourceEstimate.save` and :meth:`mne.MixedSourceEstimate.save` by `Alex Gramfort`_
@@ -109,6 +111,8 @@ Bug
 API
 ~~~
 
+- Deprecated ``mne.SourceEstimate.morph_precomputed``, ``mne.SourceEstimate.morph``, ``mne.compute_morph_matrix``, ``mne.morph_data_precomputed`` and ``mne.morph_data`` in favor of :func:`mne.compute_source_morph`, by `Tommy Clausner`_
+
 - Prepare transition to Python 3. This release will be the last release compatible with Python 2. The next version will be Python 3 only.
 
 - CUDA support now relies on CuPy_ instead of ``PyCUDA`` and ``scikits-cuda``. It can be installed using ``conda install cupy``. By `Eric Larson`_
@@ -487,7 +491,7 @@ Changelog
 
 - Add reduced set of labels for HCPMMP-1.0 parcellation in :func:`mne.datasets.fetch_hcp_mmp_parcellation` by `Eric Larson`_
 
-- Enable morphing between hemispheres with :func:`mne.compute_morph_matrix` by `Christian Brodbeck`_
+- Enable morphing between hemispheres with ``mne.compute_morph_matrix`` by `Christian Brodbeck`_
 
 - Add ``return_residual`` to :func:`mne.minimum_norm.apply_inverse` by `Eric Larson`_
 

diff --git a/environment.yml b/environment.yml
@@ -32,6 +32,7 @@ dependencies:
   - mne
   - mayavi
   - PySurfer
+  - dipy
   - nitime
   - nibabel
   - nilearn

diff --git a/examples/inverse/plot_morph_data.py b/examples/inverse/plot_morph_data.py
Original file line number	Diff line number	Diff line change
Expand Up		@@ -431,4 +431,4 @@ done e.g., to ``subject='fsaverage'`` as::

		>>> stc_fsaverage = stc.morph('fsaverage') # doctest: +SKIP

		See :ref:`ch_morph` for more information.
		See :ref:`sphx_glr_auto_tutorials_plot_morph_stc.py` for more information.
-Original file line number
+Diff line change
@@ Expand Up / @@ -32,6 +32,7 @@ dependencies: @@
       - mne
       - mayavi
       - PySurfer
+      - dipy
       - nitime
       - nibabel
       - nilearn
@@ Expand Down @@