MRG, ENH: Add arbitrary connectivity for stats (mne-tools#7916)

* ENH: Add arbitrary connectivity for stats

* FIX: Naming

* API: Rename connectivity->adjacency

* FIX: A few more

* FIX: Setup

* FIX: Old refs

* FIX: Test

* FIX: More nesting

* FIX: Comment

doc/changes/0.15.inc

@@ -52,7 +52,7 @@ Changelog
 
 - Add :func:`mne.inverse_sparse.make_stc_from_dipoles` to generate stc objects from lists of dipoles by `Daniel Strohmeier`_
 
-- Add :func:`mne.channels.find_ch_connectivity` that tries to infer the correct connectivity template using channel info. If no template is found, it computes the connectivity matrix using :class:`Delaunay <scipy.spatial.Delaunay>` triangulation of the 2d projected channel positions by `Jaakko Leppakangas`_
+- Add ``mne.channels.find_ch_connectivity`` that tries to infer the correct connectivity template using channel info. If no template is found, it computes the connectivity matrix using :class:`Delaunay <scipy.spatial.Delaunay>` triangulation of the 2d projected channel positions by `Jaakko Leppakangas`_
 
 - Add IO support for EGI MFF format by `Jaakko Leppakangas`_  and `ramonapariciog`_
 
@@ -88,7 +88,7 @@ Changelog
 
 - Add example on how to plot ERDS maps (also known as ERSP) by `Clemens Brunner`_
 
-- Add support for volume source spaces to :func:`spatial_src_connectivity` and :func:`spatio_temporal_src_connectivity` by `Alex Gramfort`_
+- Add support for volume source spaces to ``spatial_src_connectivity`` and ``spatio_temporal_src_connectivity`` by `Alex Gramfort`_
 
 - Plotting raw data (:func:`mne.viz.plot_raw` or :meth:`mne.io.Raw.plot`) with events now includes event numbers (if there are not more than 50 events on a page) by `Clemens Brunner`_
 

doc/changes/0.19.inc

@@ -238,4 +238,4 @@ API
 
 - Reading annotations contained in GDF files with :func:`mne.io.read_raw_gdf` now returns numeric event codes as descriptions (instead of textual descriptions) due to restrictive licensing of the GDF event code table from BioSig by `Clemens Brunner`_
 
-- :func:`channels.find_ch_connectivity` now returns pre-built neighbor maps for KIT systems when available, by `Christian Brodbeck`_
+- ``channels.find_ch_connectivity`` now returns pre-built neighbor maps for KIT systems when available, by `Christian Brodbeck`_

doc/changes/latest.inc

@@ -65,6 +65,8 @@ Changelog
 
 - Add :func:`mne.stats.ttest_ind_no_p` to mirror :func:`mne.stats.ttest_1samp_no_p` with hat correction by `Eric Larson`_
 
+- Add `mne.stats.combine_adjacency` to combine adjacency matrices for independent data dimensions to enable things like spatio-temporal-time-frequency clustering in `mne.stats.permutation_cluster_test` by `Eric Larson`_
+
 - Speed up raw data reading without preload in :func:`mne.io.read_raw_nirx` by `Eric Larson`_
 
 - Support for saving movies of source time courses (STCs) with ``brain.save_movie`` method and from graphical user interface by `Guillaume Favelier`_
@@ -227,6 +229,13 @@ API
 
 - Python 3.5 is no longer supported, Python 3.6+ is required, by `Eric Larson`_
 
+- ``adjacency`` has replaced ``connectivity`` in the names of:
+
+  1. Arguments to clustering functions, such as `mne.stats.permutation_cluster_test`, and
+  2. Function names for defining adjacency, such as `mne.spatio_temporal_src_adjacency` replacing ``mne.spatio_temporal_src_connectivity``.
+
+  "connectivity" is now reserved for discussions of functional and effective connectivity of the brain, and "adjacency" for source or sensor neighbor definitions for cluster-based analyses, by `Eric Larson`_.
+
 - Add ``n_cols`` parameter to :meth:`mne.preprocessing.ICA.plot_scores` to allow plotting scores in multiple columns, by `Luke Bloy`_
 
 - In :func:`mne.stats.permutation_cluster_test` and :func:`mne.stats.permutation_cluster_1samp_test` the default parameter value ``out_type='mask'`` has changed to ``None``, which in 0.21 means ``'mask'`` but will change to mean ``'indices'`` in the next version, by `Daniel McCloy`_

doc/python_reference.rst

@@ -332,8 +332,8 @@ Projections:
    find_layout
    make_eeg_layout
    make_grid_layout
-   find_ch_connectivity
-   read_ch_connectivity
+   find_ch_adjacency
+   read_ch_adjacency
    equalize_channels
    rename_channels
    generate_2d_layout
@@ -920,6 +920,7 @@ Non-parametric (clustering) resampling methods:
 .. autosummary::
    :toctree: generated/
 
+   combine_adjacency
    permutation_cluster_test
    permutation_cluster_1samp_test
    permutation_t_test
@@ -928,22 +929,22 @@ Non-parametric (clustering) resampling methods:
    summarize_clusters_stc
    bootstrap_confidence_interval
 
-Compute ``connectivity`` matrices for cluster-level statistics:
+Compute ``adjacency`` matrices for cluster-level statistics:
 
 .. currentmodule:: mne
 
 .. autosummary::
    :toctree: generated/
 
-   channels.find_ch_connectivity
-   channels.read_ch_connectivity
-   spatial_dist_connectivity
-   spatial_src_connectivity
-   spatial_tris_connectivity
-   spatial_inter_hemi_connectivity
-   spatio_temporal_src_connectivity
-   spatio_temporal_tris_connectivity
-   spatio_temporal_dist_connectivity
+   channels.find_ch_adjacency
+   channels.read_ch_adjacency
+   spatial_dist_adjacency
+   spatial_src_adjacency
+   spatial_tris_adjacency
+   spatial_inter_hemi_adjacency
+   spatio_temporal_src_adjacency
+   spatio_temporal_tris_adjacency
+   spatio_temporal_dist_adjacency
 
 
 Simulation

mne/__init__.py

@@ -16,7 +16,7 @@
 # Dev branch marker is: 'X.Y.devN' where N is an integer.
 #
 
-__version__ = '0.21.dev0'
+from ._version import __version__
 
 # have to import verbose first since it's needed by many things
 from .utils import (set_log_level, set_log_file, verbose, set_config,
@@ -53,13 +53,13 @@
                               VolSourceEstimate, VolVectorSourceEstimate,
                               MixedSourceEstimate, MixedVectorSourceEstimate,
                               grade_to_tris,
-                              spatial_src_connectivity,
-                              spatial_tris_connectivity,
-                              spatial_dist_connectivity,
-                              spatial_inter_hemi_connectivity,
-                              spatio_temporal_src_connectivity,
-                              spatio_temporal_tris_connectivity,
-                              spatio_temporal_dist_connectivity,
+                              spatial_src_adjacency,
+                              spatial_tris_adjacency,
+                              spatial_dist_adjacency,
+                              spatial_inter_hemi_adjacency,
+                              spatio_temporal_src_adjacency,
+                              spatio_temporal_tris_adjacency,
+                              spatio_temporal_dist_adjacency,
                               extract_label_time_course)
 from .surface import (read_surface, write_surface, decimate_surface, read_tri,
                       read_morph_map, get_head_surf, get_meg_helmet_surf,
@@ -121,6 +121,23 @@
 from . import viz
 from . import decoding
 
+from .utils import deprecated_alias
+deprecated_alias(
+    'spatial_src_connectivity', spatial_src_adjacency)
+deprecated_alias(
+    'spatial_tris_connectivity', spatial_tris_adjacency)
+deprecated_alias(
+    'spatial_dist_connectivity', spatial_dist_adjacency)
+deprecated_alias(
+    'spatial_inter_hemi_connectivity', spatial_inter_hemi_adjacency)
+deprecated_alias(
+    'spatio_temporal_src_connectivity', spatio_temporal_src_adjacency)
+deprecated_alias(
+    'spatio_temporal_tris_connectivity', spatio_temporal_tris_adjacency)
+deprecated_alias(
+    'spatio_temporal_dist_connectivity', spatio_temporal_dist_adjacency)
+del deprecated_alias
+
 # initialize logging
 set_log_level(None, False)
 set_log_file()

mne/_version.py

@@ -0,0 +1,6 @@
+"""The version number."""
+# Authors: Eric Larson <[email protected]>
+#
+# License: BSD (3-clause)
+
+__version__ = '0.21.dev0'

mne/channels/__init__.py

@@ -15,8 +15,12 @@
                       read_custom_montage, read_dig_hpts,
                       compute_native_head_t)
 from .channels import (equalize_channels, rename_channels, fix_mag_coil_types,
-                       read_ch_connectivity, _get_ch_type,
-                       find_ch_connectivity, make_1020_channel_selections)
+                       read_ch_adjacency, _get_ch_type,
+                       find_ch_adjacency, make_1020_channel_selections)
+from ..utils import deprecated_alias
+deprecated_alias('read_ch_connectivity', read_ch_adjacency)
+deprecated_alias('find_ch_connectivity', find_ch_adjacency)
+del deprecated_alias
 
 __all__ = [
     # Data Structures
@@ -27,14 +31,14 @@
     'make_standard_montage',
 
     # Readers
-    'read_ch_connectivity', 'read_dig_captrak', 'read_dig_dat',
+    'read_ch_adjacency', 'read_dig_captrak', 'read_dig_dat',
     'read_dig_egi', 'read_dig_fif', 'read_dig_montage',
     'read_dig_polhemus_isotrak', 'read_layout', 'read_montage',
     'read_polhemus_fastscan', 'read_custom_montage', 'read_dig_hpts',
 
     # Helpers
     'rename_channels', 'make_1020_channel_selections',
-    '_get_ch_type', 'equalize_channels', 'find_ch_connectivity', 'find_layout',
+    '_get_ch_type', 'equalize_channels', 'find_ch_adjacency', 'find_layout',
     'fix_mag_coil_types', 'generate_2d_layout', 'get_builtin_montages',
 
     # Other