{"id":13689090,"url":"https://github.com/braindynamicslab/dyneusr","last_synced_at":"2025-05-01T23:32:09.838Z","repository":{"id":34794262,"uuid":"183305943","full_name":"braindynamicslab/dyneusr","owner":"braindynamicslab","description":"Dynamical Neuroimaging Spatiotemporal Representations (DyNeuSR)","archived":false,"fork":false,"pushed_at":"2023-12-12T22:32:44.000Z","size":25471,"stargazers_count":44,"open_issues_count":12,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-03T00:07:18.601Z","etag":null,"topics":["brain-dynamics","brain-networks","mapper-algorithm","neuroimaging","topological-data-analysis","visualization"],"latest_commit_sha":null,"homepage":"https://braindynamicslab.github.io/dyneusr","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause-clear","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/braindynamicslab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-04-24T20:58:55.000Z","updated_at":"2024-10-14T02:40:19.000Z","dependencies_parsed_at":"2022-07-18T22:01:35.801Z","dependency_job_id":"66bac18f-5f28-49c2-8a41-428a9e24e5d4","html_url":"https://github.com/braindynamicslab/dyneusr","commit_stats":{"total_commits":447,"total_committers":8,"mean_commits":55.875,"dds":0.1476510067114094,"last_synced_commit":"720f36ec76cca4912fa6b0a3e24266627b483617"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindynamicslab%2Fdyneusr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindynamicslab%2Fdyneusr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindynamicslab%2Fdyneusr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindynamicslab%2Fdyneusr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/braindynamicslab","download_url":"https://codeload.github.com/braindynamicslab/dyneusr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282111,"owners_count":17285772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brain-dynamics","brain-networks","mapper-algorithm","neuroimaging","topological-data-analysis","visualization"],"created_at":"2024-08-02T15:01:33.505Z","updated_at":"2024-11-12T13:30:45.512Z","avatar_url":"https://github.com/braindynamicslab.png","language":"Python","readme":"\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://braindynamicslab.github.io/dyneusr/\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/logo.png\" height=\"250\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://braindynamicslab.github.io/dyneusr/\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/haxby_decoding_mapper_stages.png\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\n\n## **Dynamical Neuroimaging Spatiotemporal Representations**\n\n[![https://www.singularity-hub.org/static/img/hosted-singularity--hub-%23e32929.svg](https://www.singularity-hub.org/static/img/hosted-singularity--hub-%23e32929.svg)](https://singularity-hub.org/collections/4218)\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\u003e Geniesse, C., Sporns, O., Petri, G., \u0026 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\u003e Saggar, M., Sporns, O., Gonzalez-Castillo, J., Bandettini, P.A., Carlsson, G., Glover, G., \u0026 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 \u0026 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\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/braindynamicslab/dyneusr/tree/master/examples/trefoil_knot\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/dyneusr_trefoil_knot.png\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n\n\n### **_Mapper Parameter Comparison_** ([trefoil knot](https://github.com/braindynamicslab/dyneusr/blob/master/examples/trefoil_knot/compare_lenses.py))\n\n```python\n# Define projections to compare\nprojections = ([0], [0,1], [1,2], [0, 2])\n\n# Compare different sets of columns as lenses\nfor projection in projections:\n\n\t# Generate shape graph using KeplerMapper\n\tmapper = KeplerMapper(verbose=1)\n\tlens = mapper.fit_transform(X, projection=projection)\n\tgraph = mapper.map(lens, X, nr_cubes=4, overlap_perc=0.3)\n\n\t# Visualize the stages of Mapper\n\tfig, axes = visualize_mapper_stages(\n\t\tdataset, lens=lens, graph=graph, cover=mapper.cover, \n\t\tlayout=\"spectral\")\n\t\t\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/braindynamicslab/dyneusr/tree/master/examples/trefoil_knot\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0.png\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0_1.png\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_0_2.png\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/trefoil_knot_mapper_lens_1_2.png\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n\n\n### **_Neuroimaging Applications_** ([haxby decoding](https://github.com/braindynamicslab/dyneusr/tree/master/examples/haxby_decoding))\n\n```python\n\nimport numpy as np \nimport pandas as pd\n\nfrom nilearn.datasets import fetch_haxby\nfrom nilearn.input_data import NiftiMasker\n\nfrom kmapper import KeplerMapper, Cover\nfrom sklearn.manifold import TSNE\nfrom sklearn.cluster import DBSCAN\n\n# Fetch dataset, extract time-series from ventral temporal (VT) mask\ndataset = fetch_haxby()\nmasker = NiftiMasker(\n    dataset.mask_vt[0], \n    standardize=True, detrend=True, smoothing_fwhm=4.0,\n    low_pass=0.09, high_pass=0.008, t_r=2.5,\n    memory=\"nilearn_cache\")\nX = masker.fit_transform(dataset.func[0])\n\n# Encode labels as integers\ndf = pd.read_csv(dataset.session_target[0], sep=\" \")\ntarget, labels = pd.factorize(df.labels.values)\ny = pd.DataFrame({l:(target==i).astype(int) for i,l in enumerate(labels)})\n\n# Generate shape graph using KeplerMapper\nmapper = KeplerMapper(verbose=1)\nlens = mapper.fit_transform(X, projection=TSNE(2))\ngraph = mapper.map(lens, X, cover=Cover(20, 0.5), clusterer=DBSCAN(eps=20.))\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\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/braindynamicslab/dyneusr/tree/master/examples/haxby_decoding\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/braindynamicslab/dyneusr/master/docs/assets/dyneusr_haxby_decoding.png\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n\n\n## **Setup**\n\n### **_Dependencies_**\n\n#### [Python 3.6](https://www.python.org/)\n\n#### Required Python Packages\n* [numpy](www.numpy.org)\n* [pandas](pandas.pydata.org)\n* [scipy](www.scipy.org)\n* [scikit-learn](scikit-learn.org)\n* [matplotlib](matplotlib.sourceforge.net)\n* [seaborn](stanford.edu/~mwaskom/software/seaborn)\n* [networkx](networkx.github.io)\n* [nilearn](nilearn.github.io)\n* [kmapper](kepler-mapper.scikit-tda.org)\n\n_For a full list of packages and required versions, see [`requirements.txt`](https://github.com/braindynamicslab/dyneusr/blob/master/requirements.txt) and [`requirements-versions.txt`](https://github.com/braindynamicslab/dyneusr/blob/master/requirements-versions.txt)._\n\n\n### **_Install with PIP_**\n\n_To install with pip:_\n```bash\npip install dyneusr\n```\n\n_To install from source:_\n```bash\ngit clone https://github.com/braindynamicslab/dyneusr.git\ncd dyneusr\n\npip install -r requirements.txt\npip install -e .\n\npytest\n```\n\n\n### **_Install with Conda_**\n\nIf your default environment is Python 2, we recommend that you install `dyneusr` in a separate Python 3 environment. You can find more information about creating a separate environment for Python 3 [here](https://salishsea-meopar-docs.readthedocs.io/en/latest/work_env/python3_conda_environment.html). \n\nIf you don't have conda, or if you are new to scientific python, we recommend that you download the [Anaconda scientific python distribution](https://store.continuum.io/cshop/anaconda/). \n\n_To create a new conda environment and install from source:_\n```bash\nconda create -n dyneusr python=3.6\nconda activate dyneusr\n\ngit clone https://github.com/braindynamicslab/dyneusr.git\ncd dyneusr\n\nconda install --file requirements-conda.txt\npip install -e .\n\npytest\n```\n\nThis creates a new conda environment `dyneusr` and installs in it the dependencies that are needed. To access it, use the `conda activate dyneusr` command (if your conda version \u003e= 4.4) and use `source activate dyneusr` command (if your conda version \u003c 4.4).\n\n### **_Run in a Singularity Container_**\nTo 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:\n```\nsingularity run shub://braindynamicslab/dyneusr\nsource activate neuro\n```\nThis will download and run a singularity container from [singularity-hub](https://singularity-hub.org/) running centos 7 with dyneusr, jupyter, and all dependencies. It will also activate the conda environement `neuro` where these are installed. For more information on how to use singularity, see the [documentation](https://sylabs.io/docs/). The singularity recipe for this file was built with [neurodocker](https://github.com/ReproNim/neurodocker)\n\n## **Support**\n\nPlease feel free to [report](https://github.com/braindynamicslab/dyneusr/issues/new) any issues, [request](https://github.com/braindynamicslab/dyneusr/issues/new) new features, or [propose](https://github.com/braindynamicslab/dyneusr/compare) improvements. You can also contact Caleb Geniesse at geniesse [at] stanford [dot] edu.\n\nIf you contribute to DyNeuSR, please feel free to add your name to the [list of contributors](https://github.com/braindynamicslab/dyneusr/blob/master/contributors.md). \n\n## **Citation**\n\n\u003e Geniesse, C., Sporns, O., Petri, G., \u0026 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","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraindynamicslab%2Fdyneusr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbraindynamicslab%2Fdyneusr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraindynamicslab%2Fdyneusr/lists"}