From 3201359b22b8d2d1107669d06d7e4a6d3d256a45 Mon Sep 17 00:00:00 2001 From: Jaewon Chung Date: Sat, 6 Apr 2024 02:01:44 -0400 Subject: [PATCH] Docs (#418) * ndmg -> m2g * black * md format --- README.md | 48 +++-- m2g/__init__.py | 2 +- m2g/functional/__init__.py | 2 +- m2g/functional/m2g_func.py | 327 ++++++++++++++++++++------------ m2g/graph.py | 6 +- m2g/register.py | 8 +- m2g/scripts/m2g_bids.py | 26 +-- m2g/scripts/m2g_cloud.py | 14 +- m2g/scripts/m2g_dwi_pipeline.py | 53 +++--- m2g/stats/__init__.py | 2 + m2g/stats/qa_fast.py | 67 +++---- m2g/stats/qa_reg.py | 122 ++++++++---- m2g/stats/qa_skullstrip.py | 40 ++-- m2g/stats/qa_tensor.py | 22 +-- m2g/stats/qa_tractography.py | 134 ++++++++----- m2g/track.py | 2 +- m2g/utils/cloud_utils.py | 10 +- m2g/utils/gen_utils.py | 122 +++++++----- m2g/utils/qa_utils.py | 45 +++-- m2g/utils/reg_utils.py | 5 +- 20 files changed, 626 insertions(+), 431 deletions(-) diff --git a/README.md b/README.md index 73de1682c..d12c8cb64 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,8 @@ NeuroData's MR Graphs package, **m2g**, is a turn-key pipeline which uses struct # Overview - The **m2g** pipeline has been developed as a beginner-friendly solution for human connectome estimation by providing robust and reliable estimates of connectivity across a wide range of datasets. The pipelines are explained and derivatives analyzed in our pre-print, available on [BiorXiv](https://www.biorxiv.org/content/10.1101/2021.11.01.466686v1.full). - # System Requirements The **m2g** pipeline: @@ -43,26 +41,32 @@ The **m2g** pipeline: - has install instructions via a Dockerfile; - requires no non-standard hardware to run; - has key features built upon FSL, AFNI, INDI, Dipy, Nibabel, Nilearn, Networkx, Numpy, Scipy, Scikit-Learn, and others - - For Python package version numbers, see [requirements.txt](requirements.txt) - - For binaries required to install AFNI, FSL, INDI, ICA_AROMA, see the [Dockerfile](Dockerfile) + - For Python package version numbers, see [requirements.txt](requirements.txt) + - For binaries required to install AFNI, FSL, INDI, ICA_AROMA, see the [Dockerfile](Dockerfile) - takes approximately 1-core, < 16-GB of RAM, and 1-2 hours to run for most datasets (varies based on data). # Demo + To install and run a tutorial of the latest Docker image of m2g, pull the docker image from DockerHub using the following command. Then enter it using `docker run`: + ``` docker pull neurodata/m2g:latest docker run -ti --entrypoint /bin/bash neurodata/m2g:latest ``` + Once inside of the Docker container, download a tutorial dataset of fMRI and diffusion MRI data from the `open-neurodata` AWS S3 bucket to the `/input` directory in your container (make sure you are connected to the internet): + ``` aws s3 sync --no-sign-request s3://open-neurodata/m2g/TUTORIAL /input ``` + Now you can run the `m2g` pipeline for both the functional and diffusion MRI data using the command below. The number of `seeds` is intentionally set lower than recommended, along with a larger than recommended `voxelsize` for a faster run time (approximately 25 minutes). For more information as to what these input arguments represent, see the Tutorial section below. + ``` m2g --participant_label 0025864 --session_label 1 --parcellation AAL_ --pipeline both --seeds 1 --voxelsize 4mm /input /output ``` -Once the pipeline is done running, the resulting outputs can be found in `/output/sub-0025864/ses-1/`, see Outputs section below for a description of each file. +Once the pipeline is done running, the resulting outputs can be found in `/output/sub-0025864/ses-1/`, see Outputs section below for a description of each file. # Installation Guide @@ -91,9 +95,12 @@ In order to create a docker container from the docker image and access it, use t docker run -it --entrypoint /bin/bash m2g:uniquelabel ## Local Installation [COMING SOON] -Due to the versioning required for CPAC, along with `m2g-d`, we are currently working on streamlining the installation of `m2g`. Stay tuned for updates. +We highly recommend the use of the Docker container provided above. +Due to the versioning required for CPAC, along with `m2g-d`, we are currently working on streamlining the installation of `m2g`. Stay tuned for updates. + +- Requires numerous system level dependencies with specified versions. As such, CPAC on its own runs on a docker container, and we recommond the usage # Usage @@ -103,7 +110,6 @@ The **m2g** pipeline can be used to generate connectomes as a command-line utili Note that more options are available which can be helpful if running on the Amazon cloud, which can be found and documented by running `m2g -h`. - ## Docker Container Usage If running with the Docker container shown above, the `entrypoint` is already set to `m2g`, so the pipeline can be run directly from the host-system command line as follows: @@ -114,15 +120,14 @@ This will run **m2g** on the local data and save the output files to the directo Also note that currently, running `m2g` on a single bids-formatted dataset directory only runs a single scan. To run the entire dataset, we recommend parallelizing on a high-performance cluster or using `m2g`'s s3 integration. - # Tutorial ## Structural Connectome Pipeline (`m2g-d`) Once you have the pipeline up and running, you can run the structural connectome pipeline with: - + m2g --pipeline dwi - + We recommend specifying an atlas and lowering the default seed density on test runs (although, for real runs, we recommend using the default seeding -- lowering seeding simply decreases runtime): m2g --pipeline dwi --seeds 1 --parcellation Desikan @@ -134,9 +139,9 @@ You can set a particular scan and session as well (recommended for batch scripts ## Functional Connectome Pipeline (`m2g-f`) Once you have the pipeline up and running, you can run the functional connectome pipeline with: - + m2g --pipeline func - + We recommend specifying an atlas and lowering the default seed density on test runs (although, for real runs, we recommend using the default seeding -- lowering seeding simply decreases runtime): m2g --pipeline func --seeds 1 --parcellation Desikan @@ -145,15 +150,16 @@ You can set a particular scan and session as well (recommended for batch scripts m2g --pipeline func --seeds 1 --parcellation Desikan --participant_label