|
1 | | -****************** |
2 | | -Install |
3 | | -****************** |
| 1 | +.. include:: links.rst |
| 2 | + |
| 3 | +------------ |
| 4 | +Installation |
| 5 | +------------ |
4 | 6 |
|
5 | 7 | .. contents:: Table of Contents |
6 | 8 |
|
| 9 | +There are two ways to install **m2g**: |
7 | 10 |
|
8 | | -Summary |
9 | | -=================== |
| 11 | +* using container technologies - `Docker Container`_ - (RECOMMENDED) or |
| 12 | +* within a Manually Prepared Environment (For ``m2g-d`` pipeline). |
10 | 13 |
|
11 | | -Pull docker container:: |
| 14 | +However, the manually prepared environment is not recommended, as it is more complex and error-prone. |
12 | 15 |
|
13 | | - docker pull neurodata/m2g |
14 | 16 |
|
15 | | -Run dmri participant pipeline:: |
| 17 | +Docker Container |
| 18 | +================================================ |
| 19 | +**m2g** is distributed as a Docker image, which is the recommended way to run the pipeline. See :doc:`Docker <./docker>`. |
16 | 20 |
|
17 | | - docker run -ti -v /path/to/local/data:/data neurodata/m2g /data/ /data/outputs |
| 21 | +The Docker image contains all the necessary software dependencies, and the pipeline is executed in a containerized environment. |
| 22 | +This ensures that the pipeline runs in a consistent environment, regardless of the host system. |
18 | 23 |
|
19 | | -System Requirements |
20 | | -==================== |
21 | | -.. TODO: update package versions |
| 24 | +The most recent docker image can be pulled using:: |
| 25 | + |
| 26 | + $ docker pull neurodata/m2g:latest |
| 27 | + |
| 28 | +The image can then be used to create a container and run directly with the following command (and any additional options you may require for Docker, such as volume mounting):: |
| 29 | + |
| 30 | + $ docker run -ti --entrypoint /bin/bash neurodata/m2g:latest |
| 31 | + |
| 32 | +**m2g** docker containers can also be made from m2g's Dockerfile:: |
| 33 | + |
| 34 | + $ git clone https://github.com/neurodata/m2g.git |
| 35 | + $ cd m2g |
| 36 | + $ docker build -t <imagename:uniquelabel> . |
| 37 | + |
| 38 | +Where "uniquelabel" can be whatever you wish to call this Docker image (for example, `m2g:latest`). |
| 39 | +Additional information about building Docker images can be found `here <https://docs.docker.com/engine/reference/commandline/image_build/>`_. |
| 40 | +Creating the Docker image should take several minutes if this is the first time you have used this docker file. |
| 41 | +In order to create a docker container from the docker image and access it, use the following command to both create and enter the container:: |
22 | 42 |
|
23 | | -The m2g pipeline was developed and tested primarily on Mac OSX, Ubuntu (16, 18, 20, 22), and CentOS (5, 6); |
| 43 | + $ docker run -it --entrypoint /bin/bash m2g:uniquelabel |
24 | 44 |
|
25 | | -Made to work on Python 3.8; |
| 45 | +Manually Prepared Environment (For ``m2g-d`` pipeline) |
| 46 | +======================================================= |
26 | 47 |
|
27 | | -Is wrapped in a Docker container; |
| 48 | +.. warning:: |
28 | 49 |
|
29 | | -Has install instructions via a Dockerfile; |
| 50 | + This method is not recommended! Please consider using containers. |
30 | 51 |
|
31 | | -Requires no non-standard hardware to run; |
| 52 | +.. warning:: |
32 | 53 |
|
33 | | -Has key features built upon FSL, Dipy, Nibabel, Nilearn, Networkx, Numpy, Scipy, Scikit-Learn, and others; |
| 54 | + Without Docker, you can only run ``m2g-d`` portion of the pipeline. ``m2g-f`` requires CPAC, which also runs |
| 55 | + on a Docker container. |
34 | 56 |
|
35 | | -Takes approximately 1-core, 8-GB of RAM, and 1 hour to run for most datasets. |
36 | | - |
37 | | -While m2g is quite robust to Python package versions (with only few exceptions, mentioned in the installation guide), an example of possible versions (taken from the m2g Docker Image with version v0.3.0) is shown below. Note: this list excludes many libraries which are standard with a Python distribution, and a complete list with all packages and versions can be produced by running pip freeze within the Docker container mentioned above. :: |
38 | | - |
39 | | - awscli==1.16.210 , boto3==1.9.200 , botocore==1.12.200 , colorama==0.3.9 , configparser>=3.7.4 , |
40 | | - Cython==0.29.13 , dipy==0.16.0 , duecredit==0.7.0 , fury==0.3.0 , graspy==0.0.3 , ipython==7.7.0 , |
41 | | - matplotlib==3.1.1 , networkx==2.3 , nibabel==2.5.0 , nilearn==0.5.2 , numpy==1.17.0 , pandas==0.25.0, |
42 | | - Pillow==6.1.0 , plotly==1.12.9, pybids==0.6.4 , python-dateutil==2.8.0 , PyVTK==0.5.18 , |
43 | | - requests==2.22.0 , s3transfer==0.2.1 , setuptools>=40.0 scikit-image==0.13.0 , scikit-learn==0.21.3 , |
44 | | - scipy==1.3.0 , sklearn==8.0 , vtk==8.1.2 |
45 | | - |
46 | | -Installation Guide |
47 | | -================== |
48 | | -.. TODO: add links to external packages |
49 | | -
|
50 | | -Currently, the Docker image is recommended. |
51 | | - |
52 | | -``pip`` and Github installations are also available. |
53 | | - |
54 | | -Docker |
55 | | --------------- |
56 | | -.. _Dockerhub : https://hub.docker.com/r/neurodata/m2g/ |
57 | | -.. _documentation : https://docs.docker.com/ |
58 | | - |
59 | | -The neurodata/m3r-release Docker container enables users to run end-to-end connectome estimation on structural MRI or functional MRI right from container launch. The pipeline requires that data be organized in accordance with the BIDS spec. If the data you wish to process is available on S3 you simply need to provide your s3 credentials at build time and the pipeline will auto-retrieve your data for processing. |
60 | | - |
61 | | -If you have never used Docker before, it is useful to run through the Docker documentation_. |
62 | | - |
63 | | -**Getting Docker container**:: |
64 | | - |
65 | | - $ docker pull neurodata/m2g |
66 | 57 |
|
67 | | -*(A) I do not wish to use S3:* |
| 58 | +Make sure all of **m2g**'s `External Dependencies`_ are installed. |
| 59 | +These tools must be installed and their binaries available in the |
| 60 | +system's ``$PATH``. |
| 61 | +A relatively interpretable description of how your environment can be set-up |
| 62 | +is found in the `Dockerfile <https://github.com/neurodata/m2g/blob/deploy/Dockerfile>`_. |
68 | 63 |
|
69 | | -You are good to go! |
| 64 | +On a functional Python 3.8 (or above) environment with ``pip`` installed, |
| 65 | +**m2g** can be installed using the habitual command :: |
70 | 66 |
|
71 | | -*(B) I wish to use S3:* |
| 67 | + $ python -m pip install m2g |
72 | 68 |
|
73 | | -Add your secret key/access id to a file called credentials.csv in this directory on your local machine. A dummy file has been provided to make the format we expect clear. (This is how AWS provides credentials) |
| 69 | +Check your installation with the ``--version`` argument :: |
| 70 | + |
| 71 | + $ m2g --version |
| 72 | + |
| 73 | + |
| 74 | +External Dependencies |
| 75 | +--------------------- |
| 76 | + |
| 77 | +**m2g** requires other neuroimaging software that are not handled by the Python's packaging system (Pypi): |
| 78 | + |
| 79 | +- FSL_ (version 6.0.6.5) |
| 80 | +- ANTs_ (version 2.4.3) |
| 81 | +- AFNI_ (version 23.3.09) |
| 82 | +- `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.3.0) |
| 83 | + |
| 84 | + |
| 85 | +Requirements |
| 86 | +==================== |
74 | 87 |
|
75 | | -**Processing Data** |
| 88 | +Hardware Requirements |
| 89 | +--------------------- |
76 | 90 |
|
77 | | -Below is the help output generated by running **m2g** with the ``-h`` command. All parameters are explained in this output. :: |
| 91 | +The pipeline only requires 1-core and 16-GB of RAM, and takes approximately 1 hour to run for most datasets. |
78 | 92 |
|
79 | | - $ docker run -ti neurodata/m2g -h |
80 | 93 |
|
81 | | - usage: m2g_bids [-h] |
82 | | - [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] |
83 | | - [--session_label SESSION_LABEL [SESSION_LABEL ...]] |
84 | | - [--run_label RUN_LABEL [RUN_LABEL ...]] [--bucket BUCKET] |
85 | | - [--remote_path REMOTE_PATH] [--push_data] [--dataset DATASET] |
86 | | - [--atlas ATLAS] [--debug] [--sked] [--skreg] [--vox VOX] [-c] |
87 | | - [--mod MOD] [--tt TT] [--mf MF] [--sp SP] [--seeds SEEDS] |
88 | | - [--modif MODIF] |
89 | | - bids_dir output_dir |
| 94 | +Python Requirements |
| 95 | +------------------- |
90 | 96 |
|
91 | | - This is an end-to-end connectome estimation pipeline from M3r Images. |
| 97 | +The m2g pipeline was developed and tested for Python <=3.8 and <=3.10 on linux systems, such as Ubuntu, CentOS and macOS. |
| 98 | +With `Docker execution`_, **m2g** can run on almost all systems that support Docker. |
92 | 99 |
|
93 | | - positional arguments: |
94 | | - bids_dir The directory with the input dataset formatted |
95 | | - according to the BIDS standard. |
96 | | - output_dir The directory where the output files should be stored. |
97 | | - If you are running group level analysis this folder |
98 | | - should be prepopulated with the results of the |
99 | | - participant level analysis. |
| 100 | +While m2g is quite robust to Python package versions (with only few exceptions, mentioned in the installation guide), an example of possible versions (taken from the m2g Docker Image with version v0.3.0) is shown below. :: |
100 | 101 |
|
101 | | - optional arguments: |
102 | | - -h, --help show this help message and exit |
103 | | - --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...] |
104 | | - The label(s) of the participant(s) that should be |
105 | | - analyzed. The label corresponds to |
106 | | - sub-<participant_label> from the BIDS spec (so it does |
107 | | - not include "sub-"). If this parameter is not provided |
108 | | - all subjects should be analyzed. Multiple participants |
109 | | - can be specified with a space separated list. |
110 | | - --session_label SESSION_LABEL [SESSION_LABEL ...] |
111 | | - The label(s) of the session that should be analyzed. |
112 | | - The label corresponds to ses-<participant_label> from |
113 | | - the BIDS spec (so it does not include "ses-"). If this |
114 | | - parameter is not provided all sessions should be |
115 | | - analyzed. Multiple sessions can be specified with a |
116 | | - space separated list. |
117 | | - --run_label RUN_LABEL [RUN_LABEL ...] |
118 | | - The label(s) of the run that should be analyzed. The |
119 | | - label corresponds to run-<run_label> from the BIDS |
120 | | - spec (so it does not include "task-"). If this |
121 | | - parameter is not provided all runs should be analyzed. |
122 | | - Multiple runs can be specified with a space separated |
123 | | - list. |
124 | | - --bucket BUCKET The name of an S3 bucket which holds BIDS organized |
125 | | - data. You must have built your bucket with credentials |
126 | | - to the S3 bucket you wish to access. |
127 | | - --remote_path REMOTE_PATH |
128 | | - The path to the data on your S3 bucket. The data will |
129 | | - be downloaded to the provided bids_dir on your |
130 | | - machine. |
131 | | - --push_data flag to push derivatives back up to S3. |
132 | | - --dataset DATASET The name of the dataset you are perfoming QC on. |
133 | | - --atlas ATLAS The atlas being analyzed in QC (if you only want one). |
134 | | - --debug If False, remove any old files in the output |
135 | | - directory. |
136 | | - --sked Whether to skip eddy correction if it has already been |
137 | | - run. |
138 | | - --skreg whether or not to skip registration |
139 | | - --vox VOX Voxel size to use for template registrations (e.g. |
140 | | - default is '2mm') |
141 | | - -c, --clean Whether or not to delete intemediates |
142 | | - --mod MOD Determinstic (det) or probabilistic (prob) tracking. |
143 | | - Default is det. |
144 | | - --tt TT Tracking approach: local or particle. Default is |
145 | | - local. |
146 | | - --mf MF Diffusion model: csd or csa. Default is csd. |
147 | | - --sp SP Space for tractography. Default is native. |
148 | | - --seeds SEEDS Seeding density for tractography. Default is 20. |
149 | | - --modif MODIF Name of folder on s3 to push to. If empty, push to a |
150 | | - folder with m2g's version number. |
151 | | - |
152 | | -In order to share data between our container and the rest of our machine in Docker, we need to mount a volume. Docker does this with the -v flag. Docker expects its input formatted as: ``-v path/to/local/data:/path/in/container``. We'll do this when we launch our container, as well as give it a helpful name so we can locate it later on. |
153 | | - |
154 | | -**To run m2g on data** :: |
155 | | - |
156 | | - docker run -ti -v /path/to/local/data:/data neurodata/m2g /data/ /data/outputs |
157 | | - |
158 | | - |
159 | | -Pip |
160 | | -------------- |
161 | | - |
162 | | -m2g relies on FSL, Dipy, networkx, and nibabel, numpy scipy, scikit-learn, scikit-image, nilearn. You should install FSL through the instructions on their website, then follow install other Python dependencies with the following:: |
163 | | - |
164 | | - pip install m2g |
165 | | - |
166 | | -The only known packages which require a specific version are plotly and networkx, due to backwards-compatability breaking changes. |
167 | | - |
168 | | -Installation shouldn't take more than a few minutes, but depends on your internet connection. |
169 | | - |
170 | | -Github |
171 | | ------------ |
172 | | - |
173 | | -To install directly from Github, run:: |
174 | | - |
175 | | - git clone https://github.com/neurodata/m2g |
176 | | - cd m2g |
177 | | - python setup.py install |
| 102 | + boto3==1.28.4 |
| 103 | + configparser>=3.7.4 |
| 104 | + dipy==0.16.0 |
| 105 | + graspologic>=3.3.0 |
| 106 | + networkx==2.3 |
| 107 | + nibabel==2.5.0 |
| 108 | + nilearn==0.5.2 |
| 109 | + numpy==1.17.0 |
0 commit comments