\n\n\n\n## **Dynamical Neuroimaging Spatiotemporal Representations**\n\n[DyNeuSR](https://braindynamicslab.github.io/dyneusr/) is a Python visualization library for topological representations of neuroimaging data.\n\nDyNeuSR 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](https://www.mitpressjournals.org/doi/abs/10.1162/netn_a_00093)\" (Geniesse et al., 2019) and \"[Towards a new approach to reveal dynamical organization of the brain using topological data analysis](https://www.nature.com/articles/s41467-018-03664-4)\" (Saggar et al., 2018). Check out this [blog post](https://bdl.stanford.edu/blog/tda-cme-paper/) for more about the initial work that inspired the development of DyNeuSR. \n\nDeveloped with neuroimaging data analysis in mind, DyNeuSR connects existing implementations of Mapper (e.g. [KeplerMapper](https://kepler-mapper.scikit-tda.org)) with network analysis tools (e.g. [NetworkX](https://networkx.github.io/)) and other neuroimaging data visualization libraries (e.g. [Nilearn](https://nilearn.github.io/)) and provides a high-level interface for interacting with and manipulating shape graph representations of neuroimaging data and relating these representations back to neurophysiology.\n\nDyNeuSR also provides an interactive web interface for visualizing and exploring shape graphs. To see this visual interface in action, check out the [demos](https://braindynamicslab.github.io/dyneusr/demo/).\n\n\n\n\n## **Demos**\n\n- [Trefoil knot](https://braindynamicslab.github.io/dyneusr/demo/trefoil-knot/) ([code](https://github.com/braindynamicslab/dyneusr/blob/master/docs/demo/trefoil-knot/trefoil_knot.py))\n- [Trefoil knot (custom layouts)](https://braindynamicslab.github.io/dyneusr/demo/trefoil-knot/) ([code](https://github.com/braindynamicslab/dyneusr/blob/master/docs/demo/trefoil-knot-custom-layouts/trefoil_knot_custom_layouts.py))\n- [Haxby fMRI data (t-SNE lens)](https://braindynamicslab.github.io/dyneusr/demo/haxby-tsne/) ([code](https://github.com/braindynamicslab/dyneusr/blob/master/docs/demo/haxby-tsne/haxby_tsne.py))\n- [Haxby fMRI data (UMAP lens)](https://braindynamicslab.github.io/dyneusr/demo/haxby-umap/) ([code](https://github.com/braindynamicslab/dyneusr/blob/master/docs/demo/haxby-umap/haxby_umap.py))\n- [Haxby fMRI data (supervised UMAP lens)](https://braindynamicslab.github.io/dyneusr/demo/haxby-umap-supervised/) ([code](https://github.com/braindynamicslab/dyneusr/blob/master/docs/demo/haxby-umap-supervised/haxby_umap_supervised.py))\n\n\n## **Related Projects** \n\n- [DyNeuSR Fire](https://braindynamicslab.github.io/dyneusr-fire/) is a new project that provides a command line interface for DyNeuSR. It wraps `kmapper` and `dyneusr` into a single pipeline, and uses the [Python Fire](https://github.com/google/python-fire) library 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 the [docs](https://braindynamicslab.github.io/dyneusr-fire/).\n\n\n## **References**\n\nIf you find DyNeuSR useful, please consider citing:\n\n> Geniesse, C., Sporns, O., Petri, G., & Saggar, M. (2019). [Generating dynamical neuroimaging spatiotemporal representations (DyNeuSR) using topological data analysis](https://www.mitpressjournals.org/doi/abs/10.1162/netn_a_00093). *Network Neuroscience*. Advance publication. doi:10.1162/netn_a_00093\n\n\nFor more information about the Mapper approach, please see:\n\n> 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](https://www.nature.com/articles/s41467-018-03664-4). *Nature Communications, 9*(1). doi:10.1038/s41467-018-03664-4\n\n\n\n\n\n## **API Usage & Examples**\n\nDyNeuSR provides a Python API for working with and visualizing shape graphs generated by Mapper. This repository includes several [examples](https://github.com/braindynamicslab/dyneusr/tree/master/examples/) that introduce DyNeuSR's API and highlight different aspects of analysis with DyNeuSR. For more detailed tutorials, check out [dyneusr-notebooks](https://github.com/braindynamicslab/dyneusr-notebooks/).\n\n\n### **_Shape Graph Visualization_** ([trefoil knot](https://github.com/braindynamicslab/dyneusr/blob/master/examples/trefoil_knot/trefoil_knot.py))\n\n```python\n\nfrom dyneusr import DyNeuGraph\nfrom dyneusr.datasets import make_trefoil\nfrom dyneusr.tools import visualize_mapper_stages\nfrom kmapper import KeplerMapper\n\n# Generate synthetic dataset\ndataset = make_trefoil(size=100)\nX = dataset.data\ny = dataset.target\n\n# Generate shape graph using KeplerMapper\nmapper = KeplerMapper(verbose=1)\nlens = mapper.fit_transform(X, projection=[0])\ngraph = mapper.map(lens, X, nr_cubes=6, overlap_perc=0.2)\n\n# Visualize the shape graph using DyNeuSR's DyNeuGraph \ndG = DyNeuGraph(G=graph, y=y)\ndG.visualize('dyneusr_output.html')\n\n```\n\n
![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/logo.png\"){kind=logo}
\n\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/haxby_decoding_mapper_stages.png\")
\n\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/dyneusr_trefoil_knot.png\")
\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0.png\")
\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0_1.png\")
\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0_2.png\")
\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_1_2.png\")
\n![](\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/dyneusr_haxby_decoding.png\")
\n