Package: dyneusr
Dynamical Neuroimaging Spatiotemporal RepresentationsDyNeuSRis a Python visualization library for topological representations of neuroimaging data.DyNeuSR was designed specifically for working with shape graphs produced by the Mapper algorithm from topological data analysis (TDA), as described in the papers "Generating dynamical neuroimaging spatiotemporal representations (DyNeuSR) using topological data analysis" (Geniesse et al., 2019) and "Towards a new approach to reveal dynamical organization of the brain using topological data analysis" (Saggar et al., 2018). Check out thisblog postfor more about the initial work that inspired the development of DyNeuSR.Developed with neuroimaging data analysis in mind, DyNeuSR connects existing implementations of Mapper (e.g.KeplerMapper) with network analysis tools (e.g.NetworkX) and other neuroimaging data visualization libraries (e.g.Nilearn) and  provides a high-level interface for interacting with and manipulating shape graph representations of neuroimaging data and relating these representations back to neurophysiology.DyNeuSR also provides an interactive web interface for visualizing and exploring shape graphs. To see this visual interface in action, check out thedemos.DemosTrefoil knot(code)Trefoil knot (custom layouts)(code)Haxby fMRI data (t-SNE lens)(code)Haxby fMRI data (UMAP lens)(code)Haxby fMRI data (supervised UMAP lens)(code)Related ProjectsDyNeuSR Fireis a new project that provides a command line interface for DyNeuSR. It wrapskmapperanddyneusrinto a single pipeline, and uses thePython Firelibrary to automatically generate a simple command line interface that accepts several important options and allows users to customize this pipeline. For more information about DyNeuSR Fire, check out thedocs.ReferencesIf you find DyNeuSR useful, please consider citing:Geniesse, C., Sporns, O., Petri, G., & Saggar, M. (2019).Generating dynamical neuroimaging spatiotemporal representations (DyNeuSR) using topological data analysis.Network Neuroscience. Advance publication. doi:10.1162/netn_a_00093For more information about the Mapper approach, please see:Saggar, M., Sporns, O., Gonzalez-Castillo, J., Bandettini, P.A., Carlsson, G., Glover, G., & Reiss, A.L. (2018).Towards a new approach to reveal dynamical organization of the brain using topological data analysis.Nature Communications, 9(1). doi:10.1038/s41467-018-03664-4API Usage & ExamplesDyNeuSR provides a Python API for working with and visualizing shape graphs generated by Mapper. This repository includes severalexamplesthat introduce DyNeuSR's API and highlight different aspects of analysis with DyNeuSR. For more detailed tutorials, check outdyneusr-notebooks.Shape Graph Visualization(trefoil knot)fromdyneusrimportDyNeuGraphfromdyneusr.datasetsimportmake_trefoilfromdyneusr.toolsimportvisualize_mapper_stagesfromkmapperimportKeplerMapper# Generate synthetic datasetdataset=make_trefoil(size=100)X=dataset.datay=dataset.target# Generate shape graph using KeplerMappermapper=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 DyNeuGraphdG=DyNeuGraph(G=graph,y=y)dG.visualize('dyneusr_output.html')Mapper Parameter Comparison(trefoil knot)# Define projections to compareprojections=([0],[0,1],[1,2],[0,2])# Compare different sets of columns as lensesforprojectioninprojections:# Generate shape graph using KeplerMappermapper=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 Mapperfig,axes=visualize_mapper_stages(dataset,lens=lens,graph=graph,cover=mapper.cover,layout="spectral")Neuroimaging Applications(haxby decoding)importnumpyasnpimportpandasaspdfromnilearn.datasetsimportfetch_haxbyfromnilearn.input_dataimportNiftiMaskerfromkmapperimportKeplerMapper,Coverfromsklearn.manifoldimportTSNEfromsklearn.clusterimportDBSCAN# Fetch dataset, extract time-series from ventral temporal (VT) maskdataset=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 integersdf=pd.read_csv(dataset.session_target[0],sep=" ")target,labels=pd.factorize(df.labels.values)y=pd.DataFrame({l:(target==i).astype(int)fori,linenumerate(labels)})# Generate shape graph using KeplerMappermapper=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 DyNeuGraphdG=DyNeuGraph(G=graph,y=y)dG.visualize('dyneusr_output.html')SetupDependenciesPython 3.6Required Python Packagesnumpypandasscipyscikit-learnmatplotlibseabornnetworkxnilearnkmapperFor a full list of packages and required versions, seerequirements.txtandrequirements-versions.txt.Install with PIPTo install with pip:pipinstalldyneusrTo install from source:gitclonehttps://github.com/braindynamicslab/dyneusr.gitcddyneusr

pipinstall-rrequirements.txt
pipinstall-e.

pytestInstall with CondaIf your default environment is Python 2, we recommend that you installdyneusrin a separate Python 3 environment. You can find more information about creating a separate environment for Python 3here.If you don't have conda, or if you are new to scientific python, we recommend that you download theAnaconda scientific python distribution.To create a new conda environment and install from source:condacreate-ndyneusrpython=3.6
condaactivatedyneusr

gitclonehttps://github.com/braindynamicslab/dyneusr.gitcddyneusr

condainstall--filerequirements-conda.txt
pipinstall-e.

pytestThis creates a new conda environmentdyneusrand installs in it the dependencies that are needed. To access it, use theconda activate dyneusrcommand (if your conda version >= 4.4) and usesource activate dyneusrcommand (if your conda version < 4.4).Run in a Singularity ContainerTo run dyneusr in a Singularity container, for use on clusters where you do not have root access for example, first install singularity. Then, you can use the following command:singularity run shub://braindynamicslab/dyneusr
source activate neuroThis will download and run a singularity container fromsingularity-hubrunning centos 7 with dyneusr, jupyter, and all dependencies. It will also activate the conda environementneurowhere these are installed. For more information on how to use singularity, see thedocumentation. The singularity recipe for this file was built withneurodockerSupportPlease feel free toreportany issues,requestnew features, orproposeimprovements. You can also contact Caleb Geniesse at geniesse [at] stanford [dot] edu.If you contribute to DyNeuSR, please feel free to add your name to thelist of contributors.CitationGeniesse, C., Sporns, O., Petri, G., & Saggar, M. (2019).Generating dynamical neuroimaging spatiotemporal representations (DyNeuSR) using topological data analysis.Network Neuroscience. Advance publication. doi:10.1162/netn_a_00093