DyNeuSR is a Python visualization library for topological representations of neuroimaging data.
DyNeuSR connects the Mapper algorithm (e.g. KeplerMapper) with network analysis tools (e.g. NetworkX) and other neuroimaging data visualization libraries (e.g. Nilearn). It provides a high-level interface for interacting with shape graph representations of neuroimaging data and relating such representations back to neurophysiology.
This package was designed specifically for working with shape graphs produced by the Mapper algorithm from topological data analysis (TDA) as described in the paper "Towards a new approach to reveal dynamical organization of the brain using topological data analysis" (Saggar et al., 2018). See this blog post for more about the initial work that inspired the development of DyNeuSR.
Online documentation will include detailed API documentation, Jupyter notebook examples and tutorials, and other useful information. (coming soon)
The documentation will include several examples that introduce and highlight different aspects of DyNeuSR.
For more detailed tutorials, see the dyneusr-notebooks.
Basic usage (trefoil knot)
from dyneusr import DyNeuGraph
from dyneusr.datasets import make_trefoil
from dyneusr.tools import visualize_mapper_stages
from kmapper import KeplerMapper
# Generate synthetic dataset
dataset = make_trefoil(size=100)
X = dataset.data
y = dataset.target
# Generate shape graph using KeplerMapper
mapper = KeplerMapper(verbose=1)
lens = mapper.fit_transform(X, projection=[0])
graph = mapper.map(lens, X, nr_cubes=6, overlap_perc=0.2)
# Visualize the shape graph using DyNeuSR's DyNeuGraph
dG = DyNeuGraph(G=graph, y=y)
dG.visualize('dyneusr_output.html')
Advanced usage (trefoil knot)
# Define projections to compare
projections = ([0], [0,1], [1,2], [0, 2])
# Compare different sets of columns as lenses
for projection in projections:
# Generate shape graph using KeplerMapper
mapper = KeplerMapper(verbose=1)
lens = mapper.fit_transform(X, projection=projection)
graph = mapper.map(lens, X, nr_cubes=4, overlap_perc=0.3)
# Visualize the stages of Mapper
fig, axes = visualize_mapper_stages(
dataset, lens=lens, graph=graph, cover=mapper.cover,
layout="spectral")
Neuroimaging examples (haxby decoding)
import numpy as np
import pandas as pd
from nilearn.datasets import fetch_haxby
from nilearn.input_data import NiftiMasker
from kmapper import KeplerMapper, Cover
from sklearn.manifold import TSNE
from sklearn.cluster import DBSCAN
# Fetch dataset, extract time-series from ventral temporal (VT) mask
dataset = fetch_haxby()
masker = NiftiMasker(
dataset.mask_vt[0],
standardize=True, detrend=True, smoothing_fwhm=4.0,
low_pass=0.09, high_pass=0.008, t_r=2.5,
memory="nilearn_cache")
X = masker.fit_transform(dataset.func[0])
# Encode labels as integers
df = pd.read_csv(dataset.session_target[0], sep=" ")
target, labels = pd.factorize(df.labels.values)
y = pd.DataFrame({l:(target==i).astype(int) for i,l in enumerate(labels)})
# Generate shape graph using KeplerMapper
mapper = KeplerMapper(verbose=1)
lens = mapper.fit_transform(X, projection=TSNE(2))
graph = mapper.map(lens, X, cover=Cover(20, 0.5), clusterer=DBSCAN(eps=20.))
# Visualize the shape graph using DyNeuSR's DyNeuGraph
dG = DyNeuGraph(G=graph, y=y)
dG.visualize('dyneusr_output.html')
- Python 3.6
The following Python packages are required:
For the full list of packages and required versions, see requirements.txt and requirements-versions.txt
If your default environment is Python 2, we recommend that you install dyneusr in a separate Python 3 environment.
To create a new environment and activate it:
conda create -n py36 python=3.6
source activate py36You can find more information about creating a separate environment for Python 3, here.
If you don't have conda, or are new to scientific python, we recommend that you download the Anaconda scientific python distribution.
To download the source:
git clone https://github.com/braindynamicslab/dyneusr.git
cd dyneusrTo install from source:
pip install -e .All development happens here, on GitHub. Please feel free to report any issues and propose improvements.
If you're interested in contributing to DyNeuSR, please also refer to the Contributing guide.
Please submit any bugs or questions to the GitHub issue tracker.
Released under a BSD-3 license
Geniesse C, Sporns O, Petri G, & Saggar M. Generating dynamical neuroimaging spatiotemporal representations (DyNeuSR) using topological data analysis. In press, 2019.