Repository: graspologic-org/graspologic

Issue:
Add MCC methods to graspologic
We've developed a few methods for analyzing multi-subject connectomics data at multiple scales (edges, vertices, and communities). 

All methods are implemented using functions in graspologic (eg omni).

jovo suggested adding jupyter notebooks showing these methods working on real data into graspoloic. 

**Proposed changes**
- Add a small multi-subject connectomics dataset to the `datasets` submodule (specifically [this dataset](https://github.com/v715/popcon/tree/master/popcon/datasets/data/duke))
- Add 1 notebook demoing the edge analysis algorithm
- Add 1 notebook demoing the vertex analysis algorithm
- Add 1 notebook demoing the community analysis algorithm


Discussion:

Resolving patch:
diff --git a/graspologic/datasets/__init__.py b/graspologic/datasets/__init__.py
--- a/graspologic/datasets/__init__.py
+++ b/graspologic/datasets/__init__.py
@@ -1,6 +1,6 @@
 # Copyright (c) Microsoft Corporation and contributors.
 # Licensed under the MIT License.
 
-from .base import load_drosophila_left, load_drosophila_right
+from .base import load_drosophila_left, load_drosophila_right, load_mice
 
-__all__ = ["load_drosophila_left", "load_drosophila_right"]
+__all__ = ["load_drosophila_left", "load_drosophila_right", "load_mice"]
diff --git a/graspologic/datasets/base.py b/graspologic/datasets/base.py
--- a/graspologic/datasets/base.py
+++ b/graspologic/datasets/base.py
@@ -2,7 +2,13 @@
 # Licensed under the MIT License.
 
 from os.path import dirname, join
+from pathlib import Path
+
 import numpy as np
+import pandas as pd
+from sklearn.utils import Bunch
+
+from ..utils import import_edgelist
 
 
 def load_drosophila_left(return_labels=False):
@@ -95,3 +101,80 @@ def load_drosophila_right(return_labels=False):
         return graph, labels
     else:
         return graph
+
+
+def load_mice():
+    """
+    Load connectomes of mice from distinct genotypes.
+
+    Dataset of 32 mouse connectomes derived from whole-brain diffusion
+    magnetic resonance imaging of four distinct mouse genotypes:
+    BTBR T+ Itpr3tf/J (BTBR), C57BL/6J(B6), CAST/EiJ (CAST), and DBA/2J (DBA2).
+    For each strain, connectomes were generated from eight age-matched mice
+    (N = 8 per strain), with a sex distribution of four males and four females.
+    Each connectome was parcellated using asymmetric Waxholm Space, yielding a
+    vertex set with a total of 332 regions of interest (ROIs) symmetrically
+    distributed across the left and right hemispheres. Within a given
+    hemisphere, there are seven superstructures consisting up multiple ROIs,
+    resulting in a total of 14 distinct communities in each connectome.
+
+    Returns
+    -------
+    data : :class:`~sklearn.utils.Bunch`
+        Dictionary-like object, with the following attributes.
+
+        graphs : list of np.ndarray
+            List of adjacency matrices of the connectome
+        labels : np.ndarray
+            Array of string labels for each mouse (subject)
+        atlas : pd.DataFrame
+            DataFrame of information for each ROI
+        blocks : pd.DataFrame
+            DataFrame of block assignments for each ROI
+        features : pd.DataFrame
+            DataFrame of anatomical features for each ROI in each connectome
+
+    References
+    ----------
+    .. [1] Wang, N., Anderson, R. J., Ashbrook, D. G., Gopalakrishnan, V.,
+           Park, Y., Priebe, C. E., ... & Johnson, G. A. (2020). Variability
+           and heritability of mouse brain structure: Microscopic MRI atlases
+           and connectomes for diverse strains. NeuroImage.
+           https://doi.org/10.1016/j.neuroimage.2020.117274
+    """
+
+    data = Path(__file__).parent.joinpath("mice")
+
+    # Load all connectomes and construct a dictionary of study metadata
+    graphs, vertices = import_edgelist(data.joinpath("edgelists"), return_vertices=True)
+
+    n_vertices = len(vertices)
+    n_subjects = len(graphs)
+    meta = {"n_subjects": n_subjects, "n_vertices": n_vertices}
+
+    # Read the participants file and get genotype labels
+    participants = pd.read_csv(data.joinpath("participants.csv"))
+    labels = participants["genotype"].values
+
+    # Read the atlas and block information
+    atlas = pd.read_csv(data.joinpath("atlas.csv"))
+    blocks = pd.read_csv(data.joinpath("blocks.csv"))
+
+    # Read features
+    tmp = []
+    for fl in data.joinpath("features").glob("*" + "csv"):
+        subid = fl.stem
+        df = pd.read_csv(fl, skiprows=2)
+        df["participant_id"] = subid
+        tmp.append(df)
+    features = pd.concat(tmp, axis=0)
+    features = features.reset_index(drop=True)
+
+    return Bunch(
+        graphs=graphs,
+        labels=labels,
+        atlas=atlas,
+        blocks=blocks,
+        features=features,
+        meta=meta,
+    )


Test patch:
diff --git a/tests/test_datasets.py b/tests/test_datasets.py
--- a/tests/test_datasets.py
+++ b/tests/test_datasets.py
@@ -13,3 +13,7 @@ def test_drosphila_left():
 def test_drosphila_right():
     graph = load_drosophila_right()
     graph, labels = load_drosophila_right(return_labels=True)
+
+
+def test_load_mice():
+    data = load_mice()