Add function for generating connectivity links + tests

Author: EtienneCmb

frites/conn/__init__.py

@@ -23,5 +23,5 @@
 # connectivity utility functions
 from .conn_fcd_corr import conn_fcd_corr  # noqa
 from .conn_sliding_windows import define_windows, plot_windows  # noqa
-from .conn_utils import (conn_get_pairs, conn_reshape_undirected,  # noqa
+from .conn_utils import (conn_get_pairs, conn_links, conn_reshape_undirected,  # noqa
                          conn_reshape_directed, conn_ravel_directed, conn_net)

frites/conn/conn_ccf.py

@@ -42,7 +42,7 @@ def conn_ccf(data, times=None, roi=None, normalized=True, n_jobs=1,
         name of the ROI dimension can be provided
     normalized : bool | True
         Z-score normalization of the data. By default, it set to true.
-    times_as_sample : bool | False
+    times_as_sample : bool | True
         Specify whether the time dimension of the cross-correlation output
         should be described using the time unit of the input data or in
         samples. By default, samples are used to describe lags between

frites/conn/conn_utils.py

@@ -142,6 +142,107 @@ def conn_get_pairs(roi, directed=False, nb_min_suj=-np.inf, verbose=None):
     return df_conn, df_suj
 
 
+def conn_links(roi, directed=False, net=False, within_roi=True, sep='auto',
+               nb_min_links=None, pairs=None, verbose=None):
+    """Construct pairwise links for functional connectivity.
+
+    This function can be used for defining the pairwise links for computing
+    either undirected or directed FC on M/EEG or intracranial EEG.
+
+    Parameters
+    ----------
+    roi : array_like
+        List of roi (or contacts) names.
+    directed : bool | False
+        Specify whether the links should be for undirected (False) or directed
+        (True) FC
+    net : bool | False
+        Specify whether it is for net directed FC (True) or not (False)
+    within_roi : bool | True
+        Specify whether links within a brain region (e.g. V1-V1) should be
+        keept (True) or removed (False).
+    sep : string | 'auto'
+        If 'auto', '-' are used to linked brain region names for undirected FC
+        or '->' for directed FC. Alternatively, you can provide a custom
+        separator (e.g. sep='/')
+    nb_min_links : int | None
+        Threshold for defining a minimum number of links between two brain
+        regions (e.g. iEEG)
+    pairs : array_like | None
+        Force to use certain pairs of brain regions. Should be an array of
+        shape (n_pairs, 2) where the first column refer to sources and the
+        second to targets
+
+    Returns
+    -------
+    indices : tuple
+        Remaining indices for (sources, targets)
+    roi_st : list
+        Name of the pairs of brain regions
+    """
+    set_log_level(verbose)
+    assert isinstance(roi, (np.ndarray, list, tuple))
+    if not directed:
+        assert not net, ("Net computations not supported for undirected "
+                         "connectivity")
+    roi = np.asarray(roi)
+    n_roi = len(roi)
+    logger.info(f"Defining links (n_roi={n_roi}; directed={directed}; "
+                f"net={net}, nb_min_links={nb_min_links})")
+
+    # build separator name
+    if sep == 'auto':
+        sep = '->' if directed and not net else '-'
+    else:
+        assert isinstance(sep, str)
+
+    # get (un)directed pairs
+    if isinstance(pairs, np.ndarray) and (pairs.shape[1] == 2):
+        x_s, x_t = pairs[:, 0], pairs[:, 1]
+    else:
+        if directed and not net:
+            x_s, x_t = np.where(~np.eye(n_roi, dtype=bool))
+        elif (not directed) or (directed and net):
+            x_s, x_t = np.triu_indices(n_roi, k=1)
+
+    # drop within roi links
+    if not within_roi:
+        logger.info("    Dropping within-roi links")
+        roi_s, roi_t = roi[x_s], roi[x_t]
+        keep = [s != t for s, t in zip(roi_s, roi_t)]
+        x_s, x_t = x_s[keep], x_t[keep]
+
+    # change roi order for undirected and net directed
+    if (not directed) or (directed and net):
+        logger.info("    Sorting roi names")
+        roi_low = np.asarray([np.char.lower(r.astype(str)) for r in roi])
+        _xs, _xt = x_s.copy(), x_t.copy()
+        x_s, x_t = [], []
+        for s, t in zip(_xs, _xt):
+            _pair = np.array([roi_low[s], roi_low[t]])
+            if np.all(_pair == np.sort(_pair)):
+                x_s.append(s)
+                x_t.append(t)
+            else:
+                x_s.append(t)
+                x_t.append(s)
+    x_s, x_t = np.asarray(x_s), np.asarray(x_t)
+
+    # keep pairs with a minimum number of links inside
+    if isinstance(nb_min_links, int):
+        logger.info("    Thresholding number of links")
+        roi_st = [f"{s}{sep}{t}" for s, t in zip(roi[x_s], roi[x_t])]
+        df = pd.DataFrame({'pairs': roi_st})
+        df = df.groupby('pairs').size()
+        keep = [df.loc[r] >= nb_min_links for r in roi_st]
+        x_s, x_t = x_s[keep], x_t[keep]
+
+    # build pairs of brain region names
+    roi_st = np.asarray([f"{s}{sep}{t}" for s, t in zip(roi[x_s], roi[x_t])])
+
+    return (x_s, x_t), roi_st
+
+
 ###############################################################################
 ###############################################################################
 #                              CONN RESHAPING

frites/conn/tests/test_conn_utils.py

@@ -4,7 +4,8 @@
 
 from frites.conn import (conn_reshape_undirected, conn_reshape_directed,
                          conn_ravel_directed, define_windows, plot_windows,
-                         conn_dfc, conn_covgc, conn_get_pairs, conn_net)
+                         conn_dfc, conn_covgc, conn_get_pairs, conn_net,
+                         conn_links)
 
 
 class TestConnUtils(object):
@@ -222,3 +223,61 @@ def test_conn_net(self):
         # test order
         net = conn_net(conn, roi='space', sep='->', order=['z', 'x', 'y'])
         np.testing.assert_array_equal(net['space'], ['z-x', 'z-y', 'x-y'])
+
+    def test_conn_links(self):
+        """Test function conn_links."""
+        roi = ['dlPFC', 'aINS', 'dlPFC', 'vmPFC']
+        # overall testing
+        (x_s, x_t), roi_st = conn_links(roi, verbose=False)
+        assert len(x_s) == len(x_t) == len(roi_st)
+        assert all([f"{roi_st[s]}-{roi_st[t]}" for s, t in zip(x_s, x_t)])
+
+        # test direction
+        _, roi_st = conn_links(roi)
+        np.testing.assert_array_equal(roi_st,
+            ['aINS-dlPFC', 'dlPFC-dlPFC', 'dlPFC-vmPFC', 'aINS-dlPFC',
+            'aINS-vmPFC', 'dlPFC-vmPFC'])
+        _, roi_st = conn_links(roi, directed=True, net=False)
+        np.testing.assert_array_equal(roi_st,
+            ['dlPFC->aINS', 'dlPFC->dlPFC', 'dlPFC->vmPFC', 'aINS->dlPFC',
+            'aINS->dlPFC', 'aINS->vmPFC', 'dlPFC->dlPFC', 'dlPFC->aINS',
+            'dlPFC->vmPFC', 'vmPFC->dlPFC', 'vmPFC->aINS', 'vmPFC->dlPFC'])
+        _, roi_st = conn_links(roi, directed=True, net=True)
+        np.testing.assert_array_equal(roi_st,
+            ['aINS-dlPFC', 'dlPFC-dlPFC', 'dlPFC-vmPFC', 'aINS-dlPFC',
+            'aINS-vmPFC', 'dlPFC-vmPFC'])
+
+        # testing removing within roi connections
+        _, roi_st = conn_links(roi, within_roi=False)
+        assert 'dlPFC-dlPFC' not in roi_st
+        _, roi_st = conn_links(roi, directed=True, net=False, within_roi=False)
+        assert 'dlPFC->dlPFC' not in roi_st
+        _, roi_st = conn_links(roi, directed=True, net=True, within_roi=False)
+        assert 'dlPFC-dlPFC' not in roi_st
+
+        # remove links without a minimum number of conections
+        _, roi_st = conn_links(roi, nb_min_links=2)
+        np.testing.assert_array_equal(roi_st,
+            ['aINS-dlPFC', 'dlPFC-vmPFC', 'aINS-dlPFC', 'dlPFC-vmPFC'])
+        _, roi_st = conn_links(roi, directed=True, nb_min_links=2)
+        np.testing.assert_array_equal(roi_st,
+            ['dlPFC->aINS', 'dlPFC->dlPFC', 'dlPFC->vmPFC', 'aINS->dlPFC',
+            'aINS->dlPFC', 'dlPFC->dlPFC', 'dlPFC->aINS', 'dlPFC->vmPFC',
+            'vmPFC->dlPFC', 'vmPFC->dlPFC'])
+        _, roi_st = conn_links(roi, directed=True, nb_min_links=2, net=True)
+        np.testing.assert_array_equal(roi_st,
+            ['aINS-dlPFC', 'dlPFC-vmPFC', 'aINS-dlPFC', 'dlPFC-vmPFC'])
+
+        # testing string separator
+        for direction in [True, False]:
+            _, roi_st = conn_links(roi, sep='/', directed=True)
+            assert all(['/' in r for r in roi_st])
+
+        # testing pairs
+        p_1, p_2 = np.array([0, 2]), np.array([1, 3])
+        _, roi_st = conn_links(roi, pairs=np.c_[p_1, p_2])
+        np.testing.assert_array_equal(roi_st,
+            ['aINS-dlPFC', 'dlPFC-vmPFC'])
+        _, roi_st = conn_links(roi, pairs=np.c_[p_1, p_2], directed=True)
+        np.testing.assert_array_equal(roi_st,
+            ['dlPFC->aINS', 'dlPFC->vmPFC'])

frites/data/frites.mplstyle

@@ -13,8 +13,9 @@ axes.edgecolor: white
 axes.linewidth: 1
 axes.grid: True
 axes.titlesize: xx-large
+axes.titlecolor: 444444
 axes.labelsize: xx-large
-axes.labelcolor: 555555
+axes.labelcolor: 444444
 axes.axisbelow: True       # grid/ticks are below elements (e.g., lines, text)
 
 axes.prop_cycle: cycler('color', ['E24A33', '348ABD', '988ED5', '777777', 'FBC15E', '8EBA42', 'FFB5B8'])
@@ -38,6 +39,12 @@ grid.color: lightgray
 grid.linestyle: -    # solid line
 
 legend.fontsize: 18
+legend.labelcolor: 444444
+
+text.color: 444444
 
 figure.facecolor: white
 figure.edgecolor: 0.50
+
+savefig.dpi: 300
+savefig.bbox: tight