-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathplot_cifti_workflow.py
More file actions
167 lines (160 loc) · 5.01 KB
/
plot_cifti_workflow.py
File metadata and controls
167 lines (160 loc) · 5.01 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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
"""
CIFTI (Greyordinate-wise) Data Conversion
=========================================
For imaging data in CIFTI format, use the ``modelarrayio to-modelarray`` command to convert
the CIFTI files to the HDF5 format (``.h5``) used by **ModelArray**,
and ``modelarrayio export-results`` to export results back to CIFTI.
The CIFTI workflow is very similar to the MIF workflow
(:ref:`sphx_glr_auto_examples_plot_mif_workflow.py`).
"""
# %%
# Prepare data
# ------------
#
# To convert a list of CIFTI files to ``.h5`` format, you need:
#
# 1. **A cohort CSV** describing every CIFTI file to include (one CSV per scalar recommended).
#
# Cohort CSV columns (names are fixed, not user-defined):
#
# * ``scalar_name`` — which metric is being analysed (e.g., ``FA``)
# * ``source_file`` — path to the subject's CIFTI file
# %%
# Example folder structure
# ------------------------
#
# .. code-block:: text
#
# /home/username/myProject/data
# |
# ├── cohort_FA.csv
# │
# ├── FA
# │ ├── sub-01_FA.dscalar.nii
# │ ├── sub-02_FA.dscalar.nii
# │ ├── sub-03_FA.dscalar.nii
# │ └── ...
# │
# └── ...
#
# Corresponding ``cohort_FA.csv`` for scalar FA:
#
# .. list-table::
# :header-rows: 1
# :widths: auto
#
# * - **scalar_name** *(required)*
# - **source_file** *(required)*
# - subject_id
# - age
# - sex
# * - FA
# - /home/username/myProject/data/FA/sub-01_FA.dscalar.nii
# - sub-01
# - 10
# - F
# * - FA
# - /home/username/myProject/data/FA/sub-02_FA.dscalar.nii
# - sub-02
# - 20
# - M
# * - FA
# - /home/username/myProject/data/FA/sub-03_FA.dscalar.nii
# - 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 CIFTI files to HDF5
# ---------------------------
#
# Using the FA dataset from the example above:
#
# .. code-block:: console
#
# # activate your conda environment first
# conda activate <env_name>
#
# modelarrayio to-modelarray \
# --cohort-file /home/username/myProject/data/cohort_FA.csv \
# --output /home/username/myProject/data/FA.h5
#
# This produces ``FA.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 CIFTI
# --------------------------------
#
# After running **ModelArray** and obtaining statistical results inside ``FA.h5`` (suppose the
# analysis name is ``"mylm"``), use ``modelarrayio export-results`` to export them as CIFTI files.
#
# You must also provide an example CIFTI file to use as a template for the output.
#
# .. code-block:: console
#
# modelarrayio export-results \
# --cohort-file /home/username/myProject/data/cohort_FA.csv \
# --analysis-name mylm \
# --input-hdf5 /home/username/myProject/data/FA.h5 \
# --output-dir /home/username/myProject/data/FA_stats \
# --example-cifti /home/username/myProject/data/FA/sub-01_FA.dscalar.nii
#
# All converted volume data are saved as ``float32``. Results in ``FA_stats`` can be viewed
# with any CIFTI image viewer.
#
# .. warning::
#
# If ``--output-dir`` already exists, ``modelarrayio export-results`` will not delete it — you will
# see ``WARNING: Output directory exists``. Existing files that are **not** part of the
# current output list are left unchanged. Existing files that **are** part of the current
# output list will be overwritten. To avoid confusion, consider manually deleting the output
# directory before re-running ``modelarrayio export-results``.
# %%
# Number-of-observations image
# ----------------------------
#
# If you requested ``nobs`` during model fitting in ModelArray, after conversion you will find
# an image called ``*_model.nobs.dscalar.nii*``. With subject-specific masks, this image may be
# inhomogeneous across voxels.
#
# Voxels that did not have sufficient subjects (due to subject-specific masking) are stored as
# ``NaN`` in the HDF5 file. How different viewers display these greyordinates:
#
# .. list-table::
# :header-rows: 1
# :widths: auto
#
# * - Viewer
# - Regular voxel
# - Voxel without sufficient subjects
# * - nibabel (Python)
# - e.g. ``nobs: 209.0``, ``p.value: 0.01``
# - ``NaN``
# * - MRtrix mrview
# - e.g. ``nobs: 209``, ``p.value: 0.01``
# - ``?``
# * - ITK-SNAP
# - e.g. ``nobs: 209``, ``p.value: 0.01``
# - ``0`` (displayed, but excluded when thresholding)
# %%
# 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.