-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathplot_fixel_workflow.py
More file actions
152 lines (146 loc) · 4.68 KB
/
plot_fixel_workflow.py
File metadata and controls
152 lines (146 loc) · 4.68 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
"""
MIF (Fixel-wise) Data Conversion
================================
To convert fixel-wise data in MIF format to HDF5 format,
use the ``modelarrayio to-modelarray`` command to convert the MIF files to the HDF5 format
(``.h5``) used by **ModelArray**,
and ``modelarrayio export-results`` to export results back to MIF.
This guide assumes **ModelArrayIO** and **MRtrix** are already installed.
"""
# %%
# Prepare data
# ------------
#
# To convert a list of fixel-wise data from ``.mif`` to ``.h5`` format, prepare a cohort CSV
# file that describes every ``.mif`` file you want to include. We recommend one CSV per scalar
# (e.g. FD, FC, FDC), yielding one ``.h5`` file per scalar.
#
# Cohort CSV columns (names are fixed, not user-defined):
#
# * ``scalar_name`` — which metric is being analysed (e.g. ``FD``, ``FC``, ``FDC``)
# * ``source_file`` — path to the ``.mif`` file for this subject
# %%
# Example folder structure
# ------------------------
#
# .. code-block:: text
#
# /home/username/myProject/data
# |
# ├── cohort_FD.csv
# │
# ├── FD
# │ ├── index.mif
# │ ├── directions.mif
# │ ├── sub-01_fd.mif
# │ ├── sub-02_fd.mif
# │ ├── sub-03_fd.mif
# │ └── ...
# │
# ├── FC
# │ ├── index.mif
# │ ├── directions.mif
# │ ├── sub-01_fc.mif
# │ ├── sub-02_fc.mif
# │ ├── sub-03_fc.mif
# │ └── ...
# └── ...
#
# These ``.mif`` files are generated by MRtrix.
#
# Corresponding ``cohort_FD.csv`` for scalar FD:
#
# .. list-table::
# :header-rows: 1
# :widths: auto
#
# * - **scalar_name** *(required)*
# - **source_file** *(required)*
# - subject_id
# - age
# - sex
# * - FD
# - /home/username/myProject/data/FD/sub-01_fd.mif
# - sub-01
# - 10
# - F
# * - FD
# - /home/username/myProject/data/FD/sub-02_fd.mif
# - sub-02
# - 20
# - M
# * - FD
# - /home/username/myProject/data/FD/sub-03_fd.mif
# - sub-03
# - 15
# - F
# * - ...
# - ...
# - ...
# - ...
# - ...
#
# Notes:
#
# * Column order does not matter.
# * Values are case-sensitive — folder names, file names, and scalar names must match exactly
# between the CSV and disk.
# %%
# Convert .mif files to HDF5
# --------------------------
#
# Using the FD dataset from the example above:
#
# .. code-block:: console
#
# # activate your conda environment first
# conda activate <env_name>
#
# modelarrayio to-modelarray \
# --index-file /home/username/myProject/data/FD/index.mif \
# --directions-file /home/username/myProject/data/FD/directions.mif \
# --cohort-file /home/username/myProject/data/cohort_FD.csv \
# --output /home/username/myProject/data/FD.h5
#
# This produces ``FD.h5`` in ``/home/username/myProject/data``. You can then use
# `ModelArray <https://pennlinc.github.io/ModelArray/>`_ to run statistical analyses on it.
# %%
# Convert result .h5 back to .mif files
# --------------------------------------
#
# After running ModelArray and obtaining statistical results inside ``FD.h5`` (suppose the
# analysis name is ``"mylm"``), use ``modelarrayio export-results`` to export them as ``.mif`` files.
# The command also copies the original ``index.mif`` and ``directions.mif`` into the output
# folder.
#
# .. code-block:: console
#
# modelarrayio export-results \
# --index-file /home/username/myProject/data/FD/index.mif \
# --directions-file /home/username/myProject/data/FD/directions.mif \
# --cohort-file /home/username/myProject/data/cohort_FD.csv \
# --analysis-name mylm \
# --input-hdf5 /home/username/myProject/data/FD.h5 \
# --output-dir /home/username/myProject/data/FD_stats
#
# The results in ``FD_stats`` can now be viewed in ``mrview``.
#
# .. warning::
#
# **Existing files are not overwritten.** ``modelarrayio export-results`` calls ``mrconvert`` without
# ``-force``, so any ``.mif`` file already present in ``--output-dir`` with the same name
# will be left unchanged. If ``--output-dir`` itself already exists you will see a
# ``WARNING: Output directory exists`` message, but no files will be deleted. To start
# fresh, manually remove the output directory before re-running ``modelarrayio export-results``.
# %%
# Additional help
# ---------------
#
# Full argument documentation is available from the command line:
#
# .. code-block:: console
#
# modelarrayio to-modelarray --help
# modelarrayio export-results --help
#
# or in the :doc:`/usage` page of this documentation.