Skip to content

Commit ce9064a

Browse files
tsalotsalo
authored
Remove --relative-root parameter (#26)
1 parent 85d13b4 commit ce9064a

28 files changed

Lines changed: 745 additions & 533 deletions

‎.circleci/config.yml‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,10 @@ jobs:
6969
-v /tmp/data:/inputs \
7070
-v /tmp:/tmp \
7171
pennbbl/fixeldb:latest \
72-
--relative-root /inputs \
73-
--directions-file fixeldata/directions.mif \
74-
--index-file fixeldata/index.mif \
75-
--cohort-file test_cohort.csv \
76-
--output-hdf5 fixels.h5
72+
--directions-file /inputs/fixeldata/directions.mif \
73+
--index-file /inputs/fixeldata/index.mif \
74+
--cohort-file /inputs/test_cohort.csv \
75+
--output-hdf5 /inputs/fixels.h5
7776
7877
- store_artifacts:
7978
path: /tmp/data/fixels.h5

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ instance/
7272
# Sphinx documentation
7373
docs/_build/
7474
docs/generated/
75+
docs/auto_examples/
7576

7677
# PyBuilder
7778
target/

‎docs/conf.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,18 @@
2424
'sphinxarg.ext',
2525
'sphinx_copybutton',
2626
'sphinx_rtd_theme',
27+
'sphinx_gallery.gen_gallery',
2728
]
2829

30+
sphinx_gallery_conf = {
31+
'examples_dirs': ['examples'],
32+
'gallery_dirs': ['auto_examples'],
33+
'filename_pattern': r'/plot_',
34+
'abort_on_example_error': False,
35+
'download_all_examples': False,
36+
'plot_gallery': False,
37+
}
38+
2939
templates_path = ['_templates']
3040
source_suffix = {'.rst': 'restructuredtext'}
3141

‎docs/examples/README.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Walkthroughs
2+
============
3+
4+
Step-by-step guides for converting neuroimaging data to and from the HDF5
5+
format used by `ModelArray <https://pennlinc.github.io/ModelArray/>`_.

‎docs/examples/plot_fixel_workflow.py‎

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

‎docs/examples/plot_voxel_workflow.py‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
"""
2+
Voxel-wise Data Conversion
3+
==========================
4+
5+
For voxel-wise data, use the **``convoxel``** command from **ModelArrayIO** to convert NIfTI
6+
files to the HDF5 format (``.h5``) used by ModelArray, and ``volumestats_write`` to export
7+
results back to NIfTI. The voxel workflow is very similar to the fixel workflow
8+
(:ref:`sphx_glr_auto_examples_plot_fixel_workflow.py`).
9+
"""
10+
11+
# %%
12+
# Prepare data
13+
# ------------
14+
#
15+
# To convert a list of voxel-wise NIfTI files to ``.h5`` format, you need:
16+
#
17+
# 1. **A cohort CSV** describing every NIfTI file to include (one CSV per scalar recommended).
18+
# 2. **A group mask** — only voxels inside the group mask are kept during conversion.
19+
# 3. **Subject-specific masks** *(optional)* — voxels outside each subject's mask are set to
20+
# ``NaN`` after conversion. If you do not have per-subject masks, supply the group mask for
21+
# every subject (see the CSV example below).
22+
#
23+
# Cohort CSV columns (names are fixed, not user-defined):
24+
#
25+
# * ``scalar_name`` — which metric is being analysed (e.g. ``FA``)
26+
# * ``source_file`` — path to the subject's NIfTI file
27+
# * ``source_mask_file`` — path to the subject-specific mask (or the group mask if none exists)
28+
29+
# %%
30+
# Example folder structure
31+
# ------------------------
32+
#
33+
# .. code-block:: text
34+
#
35+
# /home/username/myProject/data
36+
# |
37+
# ├── cohort_FA.csv
38+
# ├── group_mask.nii.gz
39+
# │
40+
# ├── FA
41+
# │ ├── sub-01_FA.nii.gz
42+
# │ ├── sub-02_FA.nii.gz
43+
# │ ├── sub-03_FA.nii.gz
44+
# │ └── ...
45+
# │
46+
# ├── individual_masks
47+
# │ ├── sub-01_mask.nii.gz
48+
# │ ├── sub-02_mask.nii.gz
49+
# │ ├── sub-03_mask.nii.gz
50+
# │ └── ...
51+
# └── ...
52+
#
53+
# Corresponding ``cohort_FA.csv`` for scalar FA:
54+
#
55+
# .. list-table::
56+
# :header-rows: 1
57+
# :widths: auto
58+
#
59+
# * - **scalar_name** *(required)*
60+
# - **source_file** *(required)*
61+
# - **source_mask_file** *(required)*
62+
# - subject_id
63+
# - age
64+
# - sex
65+
# * - FA
66+
# - FA/sub-01_FA.nii.gz
67+
# - individual_masks/sub-01_mask.nii.gz
68+
# - sub-01
69+
# - 10
70+
# - F
71+
# * - FA
72+
# - FA/sub-02_FA.nii.gz
73+
# - individual_masks/sub-02_mask.nii.gz
74+
# - sub-02
75+
# - 20
76+
# - M
77+
# * - FA
78+
# - FA/sub-03_FA.nii.gz
79+
# - individual_masks/sub-03_mask.nii.gz
80+
# - sub-03
81+
# - 15
82+
# - F
83+
# * - ...
84+
# - ...
85+
# - ...
86+
# - ...
87+
# - ...
88+
# - ...
89+
#
90+
# Notes:
91+
#
92+
# * Column order does not matter.
93+
# * Values are case-sensitive — folder names, file names, and scalar names must match exactly
94+
# between the CSV and disk.
95+
96+
# %%
97+
# Convert NIfTI files to HDF5
98+
# ----------------------------
99+
#
100+
# Using the FA dataset from the example above:
101+
#
102+
# .. code-block:: console
103+
#
104+
# # activate your conda environment first
105+
# conda activate <env_name>
106+
#
107+
# convoxel \
108+
# --group-mask-file /home/username/myProject/data/group_mask.nii.gz \
109+
# --cohort-file /home/username/myProject/data/cohort_FA.csv \
110+
# --output-hdf5 /home/username/myProject/data/FA.h5
111+
#
112+
# This produces ``FA.h5`` in ``/home/username/myProject/data``. You can then use
113+
# `ModelArray <https://pennlinc.github.io/ModelArray/>`_ to run statistical analyses on it.
114+
115+
# %%
116+
# Convert result .h5 back to NIfTI
117+
# ---------------------------------
118+
#
119+
# After running ModelArray and obtaining statistical results inside ``FA.h5`` (suppose the
120+
# analysis name is ``"mylm"``), use ``volumestats_write`` to export them as NIfTI files.
121+
#
122+
# .. code-block:: console
123+
#
124+
# volumestats_write \
125+
# --group-mask-file /home/username/myProject/data/group_mask.nii.gz \
126+
# --cohort-file /home/username/myProject/data/cohort_FA.csv \
127+
# --analysis-name mylm \
128+
# --input-hdf5 /home/username/myProject/data/FA.h5 \
129+
# --output-dir /home/username/myProject/data/FA_stats \
130+
# --output-ext .nii.gz
131+
#
132+
# All converted volume data are saved as ``float32``. Results in ``FA_stats`` can be viewed
133+
# with any NIfTI image viewer.
134+
#
135+
# .. warning::
136+
#
137+
# If ``--output-dir`` already exists, ``volumestats_write`` will not delete it — you will
138+
# see ``WARNING: Output directory exists``. Existing files that are **not** part of the
139+
# current output list are left unchanged. Existing files that **are** part of the current
140+
# output list will be overwritten (unlike the fixel ``fixelstats_write``, which does not
141+
# overwrite via ``mrconvert``). To avoid confusion, consider manually deleting the output
142+
# directory before re-running ``volumestats_write``.
143+
144+
# %%
145+
# Number-of-observations image
146+
# -----------------------------
147+
#
148+
# If you requested ``nobs`` during model fitting in ModelArray, after conversion you will find
149+
# an image called ``*_model.nobs.nii*``. With subject-specific masks, this image may be
150+
# inhomogeneous across voxels.
151+
#
152+
# Voxels that did not have sufficient subjects (due to subject-specific masking) are stored as
153+
# ``NaN`` in the HDF5 file. How different viewers display these voxels:
154+
#
155+
# .. list-table::
156+
# :header-rows: 1
157+
# :widths: auto
158+
#
159+
# * - Viewer
160+
# - Regular voxel
161+
# - Voxel without sufficient subjects
162+
# * - nibabel (Python)
163+
# - e.g. ``nobs: 209.0``, ``p.value: 0.01``
164+
# - ``NaN``
165+
# * - MRtrix mrview
166+
# - e.g. ``nobs: 209``, ``p.value: 0.01``
167+
# - ``?``
168+
# * - ITK-SNAP
169+
# - e.g. ``nobs: 209``, ``p.value: 0.01``
170+
# - ``0`` (displayed, but excluded when thresholding)
171+
172+
# %%
173+
# Additional help
174+
# ---------------
175+
#
176+
# Full argument documentation is available from the command line:
177+
#
178+
# .. code-block:: console
179+
#
180+
# convoxel --help
181+
# volumestats_write --help
182+
#
183+
# or in the :doc:`/usage` page of this documentation.

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@
1111
.. toctree::
1212
:maxdepth: 2
1313

14+
auto_examples/index
1415
usage
1516
api

0 commit comments

Comments
 (0)