_images/docs_header.png

Welcome to Cepy’s documentation!

The Cepy pacakge is a python implementation of the connectome embedding (CE) framework.

Embedding of brain graph or connectome embedding (CE) involves finding a compact vectorized representation of nodes that captures their higher-order topological attributes. CE are obtained using the node2vec algorithm fitted on random walk on a brain graph. The current framework includes a novel approach to align separately learned embeddings to the same latent space.

Installation

Cepy can be installed using pip:

pip install cepy

Example Notebooks

If you’re looking for hands-on examples on connectome embeddings (CE) and Cepy, check out the links below. These are notebooks that go over the general methodology of the CE framework and how it is used in Cepy. They are available both as static GitHub pages and interactive Binder notebooks.

We recommend going over them in the following order:

  • Random walk sampling (see a.i.) - static, Binder 1

  • Learning (fitting) connectome embedding (CE; see a.ii, a.iii) and mapping structural to functional connectivity (c.i) - static, Binder 2

  • Aligning CEs within the same individual (independent fitting of the same subject) - static, Binder 3

  • Aligning CEs between individuals (across subjects; see b) - static, Binder 4

  • Learning and aligning CEs of a large cohort (see a,b) - static

  • Predicting age from aligned CEs (see c.ii)- static, Binder 5

Quick start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import cepy as ce
import numpy as np

# Load an adjacency matrix (structural connectivity matrix)
sc_group = ce.get_example('sc_group_matrix')

# Initiate and fit the connectome embedding model
ce_group = ce.CE(permutations = 1, seed=1)
ce_group.fit(sc_group)

# Extract the cosine similarity matrix among pairwise nodes
cosine_sim = ce_group.similarity()

# Save and load the model
ce_group.save_model('group_ce.json')
ce_loaded = ce.load_model('group_ce.json') # load it

# Load two existing CE models
ce_subject1 = ce.get_example('ce_subject1')
ce_subject2 = ce.get_example('ce_subject2')

# Align the two to the space of the [ce]:
ce_subject1_aligned = ce.align(ce_group, ce_subject1)
ce_subject2_aligned = ce.align(ce_group, ce_subject2)

# Extract the node vectorized representations (normalized) for subsequent use (prediction, for example)
w_sbject1 = ce_subject1_aligned.weights.get_w_mean(norm = True)
w_sbject2 = ce_subject2_aligned.weights.get_w_mean(norm = True)
  • see the full API

Cite

If you find cepy useful for your research, please consider citing the following paper:

Levakov, G., Faskowitz, J., Avidan, G. & Sporns, O. (2020). Mapping structure to function and behavior with individual-level connectome embedding. In preparation

Acknowledgements

  • The node2vec implementation is modeified from the node2vec package by Elior Cohen and the connectome_embedding code by Gideon Rosenthal.

  • Rosenthal, G., Váša, F., Griffa, A., Hagmann, P., Amico, E., Goñi, J., … & Sporns, O. (2018). Mapping higher-order relations between brain structure and function with embedded vector representations of connectomes. Nature communications, 9(1), 1-12.

Indices and tables