{"id":13686632,"url":"https://github.com/mattcieslak/MITTENS","last_synced_at":"2025-05-01T09:32:24.253Z","repository":{"id":68199688,"uuid":"84369143","full_name":"mattcieslak/MITTENS","owner":"mattcieslak","description":"A Python library for Analytic Tractography","archived":false,"fork":false,"pushed_at":"2020-06-19T22:01:06.000Z","size":4769,"stargazers_count":9,"open_issues_count":5,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T11:02:06.309Z","etag":null,"topics":["diffusion-trajectories","fortran90","network-analysis","python3"],"latest_commit_sha":null,"homepage":"","language":"Fortran","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattcieslak.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":"2017-03-08T21:45:45.000Z","updated_at":"2024-08-01T06:15:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"60ad7a91-5432-4a2c-a063-67e57908227e","html_url":"https://github.com/mattcieslak/MITTENS","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattcieslak%2FMITTENS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattcieslak%2FMITTENS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattcieslak%2FMITTENS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattcieslak%2FMITTENS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattcieslak","download_url":"https://codeload.github.com/mattcieslak/MITTENS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251852878,"owners_count":21654476,"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":["diffusion-trajectories","fortran90","network-analysis","python3"],"created_at":"2024-08-02T15:00:36.445Z","updated_at":"2025-05-01T09:32:23.140Z","avatar_url":"https://github.com/mattcieslak.png","language":"Fortran","funding_links":[],"categories":["Fortran"],"sub_categories":[],"readme":"![mitten](doc/img/mitten.png)\n\n# MITTENS\n\nMITTENS is a python library that performs analytical tractography\non reconstructed diffusion-weighted MRI data. Currently the output\nfrom DSI Studio is supported.  \n\n\n# Table of Contents\n1. [Installation](#installation)\n  * [Adding Geometric Constraints](#adding-geometric-constraints)\n2. [Preparing your data](#preparing-your-data)\n3. [Calculating intervoxel fiber transition probabilities](#calulating-intervoxel-fiber-transition-probabilities)\n4. [`VoxelGraph` Construction](#voxel-graph-construction)\n  * [Finding and visualizing connections between regions](#finding-and-visualizing-connections-between-regions)\n  * [Building an `AtlasGraph`](#building-an-atlas-graph)\n\n\n\n## Installation\n\nNOTE: On Mac OS you may need to specify the path to a recent c++\ncompiler (download gcc-8 from homebrew) E.g. ``export CXX=/usr/local/bin/g++-8``. You might also\nneed to edit the setup.py script to include\n\n```\n# initialize Extension module with the appropriate source file\nmodules = [Extension(\"_NetworKit\",\n        src,\n        language = \"c++\",\n        extra_compile_args=[\"-fopenmp\", \"-std={}\".format(stdflag), \"-O3\", \"-DNOGTEST\"],\n        extra_link_args=['-fopenmp', \"-std={}\".format(stdflag),'-lgomp', '-Wl,-rpath,/usr/local/opt/gcc/lib/gcc/8/'], # \u003c- NEW!\n        libraries=[\"NetworKit-Core-{0}\".format(optimize)],\n        library_dirs=[\"./\"])]\n```\n\nWhile this software can be installed like any other python package,\nit is possible to add custom compiled functions before installation.\nAnalytic tractography requires the specification of a set of geometric\nconstraints for inter-voxel tract transition expectations can be\nsolved. MITTENS comes with the functions used to perform the analyses\ndescribed in [our paper], but nothing more.\n\nYou can add as many sets of geometric constraints as you like, but be\nwarned that it can take awhile to compile them.  Remember you only\nneed to compile a solution __once__. Also beware that some\ncombinations of step size and turning angle maximum result in infinite\nsets of turning angle sequences. Python will crash with a recursion error\nin this case.\n\n### Adding Geometric Constraints (optional)\n\nDownload the current version of MITTENS and enter its source tree:\n\n```bash\n$ git clone https://github.com/mattcieslak/MITTENS.git\n$ cd MITTENS\n```\n\nNow, launch a python session in the mittens directory\n\n```python\n\u003e\u003e\u003e from mittens.write_solution import write_solution\n\u003e\u003e\u003e write_solution(\"odf8\", 35, 1.0)\n```\n\nThis will write out two fortran files in the current directory. They are named\nafter the parameters you chose. This particular example will read data\nreconstructed with 8-fold ODF tesselation, a turning angle maximum of 35\ndegrees and a step size of 1.0 voxel units (voxels are assumed to be\nisotropic).\n\nAfter some calculations you will find\n``doubleODF_odf8_ss1_00_am35.f90`` and ``singleODF_odf8_ss1_00_am35.f90``\nin the current directory. Move these files into the ``src/`` directory\nand install the package with ``pip``. We recommend using an editable\ninstall, which will keep all these files in their current directory:\n\n```bash\nmv *.f90 src/\npip install -e .\n```\n\nThis will compile everything in the ``src/`` directory into a\npython module. You can now use these geometric constraints to\ncalculate transition expectations.\n\n\n## Preparing your data\n\nDSI Studio can be used to reconstruct diffusion MRI using a variety\nof methods.  You can use any method you like **except for DTI**.\nIf you acquired DTI data, choose **GQI** reconstruction instead of\nDTI reconstruction.\n\n![recon_opts](doc/img/recon_options.png)\n\nDSI, GQI and QBI can be selected from this menu.  There are additional\noptions not listed on this GUI but are accessible through the commandline.\nFor example, ODF deconvolution and decomposition can be used. All\noptions in purple boxes can be changed, but it is required that ODF data\nis written in the output file.  Critically, the ``ODF Tesselation``\noption determines the angular resolution of your output ODFs. The choice\nhere will result in ``\"odf8\"`` being the appropriate choice for\nthe call to ``write_solutions()`` above.\n\nData from other diffusion MRI packages such as FSL and MRTRIX can be loaded\n(theoretically) after being ![converted to DSI Studio\nformat](http://dsi-studio.labsolver.org/Manual/data-exchange-between-dsi-studio-and-mrtrix).\n\n## Calculating intervoxel fiber transition probabilities\n\nDSI Studio files are read directly by MITTENS:\n\n```python\n\u003e\u003e\u003e from mittens import MITTENS\n\u003e\u003e\u003e mitns = MITTENS(reconstruction=\"HCP.src.gz.odf8.f5rec.fy.gqi.1.25.fib.gz\")\n```\n\nFrom here you can estimate none-ahead or one-ahead, where NIfTI-1 files are\nsaved for each neighbor direction:\n\n```python\n\u003e\u003e\u003e mitns.calculate_transition_probabilities(output_prefix=\"hcp\")\n```\n\nYou will find the output in the current working directory (unless you specified an\nabsolute path as the argument). There is a single 3D file for each neighbor voxel\nnamed ``hcp_doubleODF_r_prob.nii.gz``, ``hcp_singleODF_r_prob.nii.gz``,\n``hcp_doubleODF_lpi_prob.nii.gz``, etc.  There will also be CoDI and CoAsy output.\nInstead of re-running the estimations again, you can create a MITTENS object\nby specifying the prefix of the NIfTI files written out during estimation.\n\n```python\n\u003e\u003e\u003e nifti_mitns = MITTENS(nifti_prefix=\"hcp\")\n```\n\nThis is very fast.\n\n## `VoxelGraph` Construction\n\nMITTENS uses ``networkit`` to construct directed graphs of voxels, where edges\nare weighted by the tract transition expectation from one voxel to another.\nA graph can build directly from MITTENS object.\n\n```python\n\u003e\u003e\u003e voxel_graph = mitns.build_graph(doubleODF=True, weighting_scheme=\"negative_log_p\")\n\u003e\u003e\u003e voxel_graph.save(\"hcp_voxel_graph.mat\")\n```\n\nThere are different schemes available for weighting edges in the graph.\n\n| Option                           | Transformation      | Reference |\n| ---------------------------------|:-------------------:| ----------|\n| `\"negative_log_p\"`               | negative log of transition probability | Zalesky (2008) |\n| `\"minus_iso_negative_log_p\"`     | max(0, transition prob - isotropic transition prob) | None yet |\n| `\"minus_iso_scaled_negative_log_p\"` | Same as above but scaled to sum to 1 across all neighbors of the voxel | None yet |\n| `\"transition_probability\"` | The transition probability. Not useful for shortest paths | None yet |\n\nYou can also build a matching voxel graph using probabilities from isotropic ODFs\n\n```python\n\u003e\u003e\u003e null_graph = mitns.build_null_graph(doubleODF=True, purpose=\"shortest paths\")\n\u003e\u003e\u003e null_graph.save(\"hcp_null_voxel_graph.mat\")\n```\nBoth `voxel_graph` and `null_graph` will be of class `mittens.VoxelGraph`, which contains a `networkit.Graph` and spatial mapping information from the original dMRI data.  You can load these directly from disk using\n\n```python\n\u003e\u003e\u003e from mittens import VoxelGraph\n\u003e\u003e\u003e loaded_voxel_graph = VoxelGraph(\"hcp_voxel_graph.mat\")\n\u003e\u003e\u003e loaded_null_graph = VoxelGraph(\"hcp_null_voxel_graph.mat\")\n```\n\n## Finding and visualizing connections between regions\n\nAssuming the previous steps have been run, we can add an atlas to the graph\nand query for connections between regions. Here we have two cortical regions we'd\nlike to connect. These regions are spheres around peak coordinates in primary\nmotor cortex (M1) and supplementary motor area (SMA). Here we find the shortest path\nfrom each voxel in the M1 sphere to any voxel in the SMA sphere. The paths are\nsaved to be loaded into DSI Studio as streamlines, optionally with their corresponding\nprobabilities.\n\n```python\n\u003e\u003e\u003e paths, probs = voxel_graph.region_voxels_to_region_query(\"lm1_sphere.nii.gz\",\n                      \"sma_sphere.nii.gz\", write_trk=\"test\", write_prob=\"test\")\n\n```\n\nThis will write out two files. One is ``lm1_sphere.nii.gz_to_sma_sphere.nii.gz_test.trk.gz``\nand the other is ``lm1_sphere.nii.gz_to_sma_sphere.nii.gz_test.txt``. To load in DSI Studio,\nopen the fib file used earlier via the \"Step 3: Fiber Tracking\" button.  Load the streamlines\nthrough the context menu and color-code them based on their probabilities:\n\n![recon_opts](doc/img/open_results.png)\n\nthe color-coded streamlines are more informative:\n\n![recon_opts](doc/img/prob_color_streamlines.png)\n\n\n\n## Building an `AtlasGraph`\n\nMost network approaches to date use brain regions as nodes. You can add\nbrain regions to your `VoxelGraph` like so:\n\n```python\nvoxel_graph.add_atlas(\"aligned_AAL.nii.gz\")\n```\n\nThis adds a region label to voxels contained within each region. The node\nlabels can be examined in the `VoxelGraph.atlas_labels`. No additional actions\n(such as adding abstract \"region nodes\" or adding edges) are taken initially.\nAn `AtlasGraph`, a graph where nodes are brain regions and edges are based\non shortest paths through the `VoxelGraph` that connect them, can be\nbuild like so:\n\n```python\nasym_raw_prob_graph, asym_mean_prob_graph, asym_path_length_graph, \\\nconj_raw_prob_graph, conj_mean_prob_graph = voxel_graph.build_atlas_graph()\n```\n\n\nCredits\n========\nThis source code was sponsored by a grant from the GE/NFL head health challenge.\nThe content of the information does not necessarily reflect the position or\nthe policy of these companies, and no official endorsement should be inferred.\n\nAuthors\n-------\n * Matt Cieslak\n * Tegan Brennan\n * Clint Greene\n\nLogo by Allison Shapiro\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattcieslak%2FMITTENS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattcieslak%2FMITTENS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattcieslak%2FMITTENS/lists"}