Docs (#418)

* ndmg -> m2g * black * md format
neurodata · Apr 6, 2024 · 3201359 · 3201359
1 parent 3c16e54
commit 3201359
Show file tree

Hide file tree

Showing 20 changed files with 626 additions and 431 deletions.
diff --git 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 <input_directory> <output_directory>
-  
+
 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 <input_directory> <output_directory>
@@ -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 <input_directory> <output_directory>
-  
+
 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 <input_directory> <output_directory>
@@ -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 <label> --session_label <label> <input_directory> <output_directory>
 
-
 ## Running both `m2g-d` and `m2g-f`
+
 Both pipelines can be run by setting the `pipeline` parameter to `both`:
-    
+
     m2g --pipeline both <input_directory> <output_directory>
 
 # Outputs
 
 ## Diffusion Pipeline
+
 The organization of the output files generated by the m2g-d pipeline are shown below. If you only care about the connectome edgelists (**m2g**'s fundamental output), you can find them in `/output/connectomes_d`.
 
 ```
@@ -165,7 +171,7 @@ res = The file has been resliced to the desired voxel size specified by the user
 
 /output
     /anat_d
-        
+
         /preproc
             t1w_aligned_mni.nii.gz = preprocessed t1w_brain anatomical image in mni space
             t1w_brain.nii.gz = t1w anatomical image with only the brain
@@ -204,7 +210,7 @@ res = The file has been resliced to the desired voxel size specified by the user
             nodif_B0_bet.nii.gz = nodif_B0 image with all non-brain matter removed
             nodif_B0_bet_mask.nii.gz = mask of nodif_B0_bet.nii.gz brain
             tensor_fa.nii.gz = tensor image fractional anisotropy map
-        
+
         /tensor
             Contains the rgb tensor file(s) for the dwi data if tractography is being done in MNI space
 
@@ -226,7 +232,7 @@ res = The file has been resliced to the desired voxel size specified by the user
             t1w_wm_in_dwi_2_nodif_B0_bet.png = overlay of white matter mask on top of registered anatomical image
         /skull_strip
             qa_skullstrip__<sub>_<ses>_T1w_reor_RAS_res.png = overlay of skullstripped anatomical image on top of original anatomical image
-    
+
     /tmp_d
         /reg_a (Intermediate files created during the processing of the anatomical data)
             mni2t1w_warp.nii.gz = nonlinear warp coefficients/fields for mni to t1w space
@@ -252,8 +258,8 @@ res = The file has been resliced to the desired voxel size specified by the user
 ```
 
 ## Functional Pipeline
-The organization of the output files generated by the m2g-f pipeline are shown below. If you only care about the connectome edgelists (**m2g**'s fundamental output), you can find them in `/output/connectomes_f`.
 
+The organization of the output files generated by the m2g-f pipeline are shown below. If you only care about the connectome edgelists (**m2g**'s fundamental output), you can find them in `/output/connectomes_f`.
 
 ```
 File labels that may appear on output files, these denote additional actions m2g may have done:
@@ -299,7 +305,7 @@ res = The file has been resliced to the desired voxel size specified by the user
     /func
         /preproc
             /coordinate_transformation
-                <subject>_<session>_task-rest_bold_calc_tshift_resample.aff12.1D = 
+                <subject>_<session>_task-rest_bold_calc_tshift_resample.aff12.1D =
             /frame_wise_displacement_jenkinson
                 FD_J.1D = vector containing Jenkinson measurement of framewise displacement for each frame of the functional image file
             /frame_wise_displacement_power
@@ -331,7 +337,7 @@ res = The file has been resliced to the desired voxel size specified by the user
                 <subject>_<session>_task-rest_bold_calc_tshift.nii.gz = slice time corrected functional image
         /register
             /functional_to_anat_linear_xfm
-                <subject>_<session>_task-rest_bold_calc_tshift_resample_volreg_calc_tstat_flirt.mat = 
+                <subject>_<session>_task-rest_bold_calc_tshift_resample_volreg_calc_tstat_flirt.mat =
             /functional_to_standard
                 bandpassed_demeaned_filtered_warp.nii.gz = bandpassed and demeaned filtered warp map for registering the functional image to MNI space
             /max_displacement
@@ -396,7 +402,7 @@ res = The file has been resliced to the desired voxel size specified by the user
             snr_s.png = sagittal view of signal to noise ratio for functional image
         /snr_val
             average_snr_file.txt = single value of average signal to noise ratio for functional image
-              
+
 ```
 
 ## Working with S3 Datasets

diff --git a/m2g/__init__.py b/m2g/__init__.py
@@ -11,7 +11,7 @@
 
 # to call `m2g.graph`, etc
 __all__ = ["graph", "preproc", "register", "track"]  # modules
-__all__.extend(["functional","scripts", "stats", "utils"])  # subpackages
+__all__.extend(["functional", "scripts", "stats", "utils"])  # subpackages
 
 # import everything listed in __all__
 # TODO: maybe still change this

diff --git a/m2g/functional/__init__.py b/m2g/functional/__init__.py
@@ -7,4 +7,4 @@
 m2g_func : top-level pipeline entrypoint
 """
 
-from . import m2g_func
+from . import m2g_func