Skip to content

Commit 50e1c2e

Browse files
tsalotsalo
authored
Fix names and paths in examples (#31)
1 parent 1076906 commit 50e1c2e

16 files changed

Lines changed: 400 additions & 357 deletions

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
contact_links:
2+
- name: Usage question
3+
url: https://neurostars.org/tags/c/software-support/234/modelarray
4+
about: Please ask questions about using ModelArrayIO on NeuroStars.

‎README.rst‎

Lines changed: 6 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -50,70 +50,19 @@ Once ModelArrayIO is installed, these commands are available in your terminal:
5050

5151
* **Fixel-wise** data (MRtrix ``.mif``):
5252

53-
* ``.mif`` → ``.h5``: ``confixel`` (CLI name kept for compatibility with earlier ConFixel workflows)
54-
* ``.h5`` → ``.mif``: ``fixelstats_write``
53+
* ``.mif`` → ``.h5``: ``modelarrayio mif-to-h5``
54+
* ``.h5`` → ``.mif``: ``modelarrayio h5-to-mif``
5555

5656
* **Voxel-wise** data (NIfTI):
5757

58-
* NIfTI → ``.h5``: ``convoxel``
59-
* ``.h5`` → NIfTI: ``volumestats_write``
58+
* NIfTI → ``.h5``: ``modelarrayio nifti-to-h5``
59+
* ``.h5`` → NIfTI: ``modelarrayio h5-to-nifti``
6060

6161
* **Greyordinate-wise** data (CIFTI-2):
6262

63-
* CIFTI-2 → ``.h5``: ``concifti``
64-
* ``.h5`` → CIFTI-2: ``ciftistats_write``
63+
* CIFTI-2 → ``.h5``: ``modelarrayio cifti-to-h5``
64+
* ``.h5`` → CIFTI-2: ``modelarrayio h5-to-cifti``
6565

66-
Installation
67-
============
68-
69-
MRtrix (required for fixel ``.mif`` only)
70-
-----------------------------------------
71-
72-
For fixel-wise ``.mif`` conversion, the ``confixel`` / ``fixelstats_write`` tools use MRtrix ``mrconvert``. Install MRtrix from `MRtrix’s webpage <https://www.mrtrix.org/download/>`_ if needed. Run ``mrview`` in the terminal to verify the installation.
73-
74-
If your data are voxel-wise or CIFTI only, you can skip this step.
75-
76-
Install ModelArrayIO
77-
--------------------
78-
79-
You may want a conda environment first—see `ModelArray: Installation <https://pennlinc.github.io/ModelArray/articles/installations.html>`_. If MRtrix is installed in that environment, install ModelArrayIO in the same environment.
80-
81-
Install from GitHub:
82-
83-
.. code-block:: console
84-
85-
git clone https://github.com/PennLINC/ModelArrayIO.git
86-
cd ModelArrayIO
87-
pip install . # build via pyproject.toml
88-
89-
Editable install for development:
90-
91-
.. code-block:: console
92-
93-
# From the repository root
94-
pip install -e .
95-
96-
With ``hatch`` installed, you can build wheels/sdist locally:
97-
98-
.. code-block:: console
99-
100-
hatch build
101-
pip install dist/*.whl
102-
103-
How to use
104-
==========
105-
106-
We provide a `walkthrough for fixel-wise data <notebooks/walkthrough_fixel-wise_data.md>`_ (``confixel`` / ``fixelstats_write``) and a `walkthrough for voxel-wise data <notebooks/walkthrough_voxel-wise_data.md>`_ (``convoxel`` / ``volumestats_write``).
107-
108-
Together with `ModelArray <https://pennlinc.github.io/ModelArray/>`_, see the `combined walkthrough <https://pennlinc.github.io/ModelArray/articles/walkthrough.html>`_ with example fixel-wise data (ModelArray + ModelArrayIO).
109-
110-
CLI help:
111-
112-
.. code-block:: console
113-
114-
confixel --help
115-
116-
Use the same pattern for ``convoxel``, ``concifti``, ``fixelstats_write``, ``volumestats_write``, and ``ciftistats_write``.
11766

11867
Storage backends: HDF5 and TileDB
11968
=================================

‎docs/examples/plot_cifti_workflow.py‎

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

‎docs/examples/plot_fixel_workflow.py‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
"""
2-
Fixel-wise Data Conversion
3-
==========================
2+
MIF (Fixel-wise) Data Conversion
3+
================================
44
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.
5+
To convert fixel-wise data in MIF format to HDF5 format,
6+
use the ``modelarrayio mif-to-h5`` command to convert the MIF files to the HDF5 format
7+
(``.h5``) used by **ModelArray**,
8+
and ``modelarrayio h5-to-mif`` to export results back to MIF.
9+
This guide assumes **ModelArrayIO** and **MRtrix** are already installed.
810
"""
911

1012
# %%
@@ -61,17 +63,17 @@
6163
# - age
6264
# - sex
6365
# * - FD
64-
# - FD/sub-01_fd.mif
66+
# - /home/username/myProject/data/FD/sub-01_fd.mif
6567
# - sub-01
6668
# - 10
6769
# - F
6870
# * - FD
69-
# - FD/sub-02_fd.mif
71+
# - /home/username/myProject/data/FD/sub-02_fd.mif
7072
# - sub-02
7173
# - 20
7274
# - M
7375
# * - FD
74-
# - FD/sub-03_fd.mif
76+
# - /home/username/myProject/data/FD/sub-03_fd.mif
7577
# - sub-03
7678
# - 15
7779
# - F
@@ -112,7 +114,7 @@
112114
# --------------------------------------
113115
#
114116
# 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.
117+
# analysis name is ``"mylm"``), use ``modelarrayio h5-to-mif`` to export them as ``.mif`` files.
116118
# The command also copies the original ``index.mif`` and ``directions.mif`` into the output
117119
# folder.
118120
#
@@ -130,11 +132,11 @@
130132
#
131133
# .. warning::
132134
#
133-
# **Existing files are not overwritten.** ``fixelstats_write`` calls ``mrconvert`` without
135+
# **Existing files are not overwritten.** ``modelarrayio h5-to-mif`` calls ``mrconvert`` without
134136
# ``-force``, so any ``.mif`` file already present in ``--output-dir`` with the same name
135137
# will be left unchanged. If ``--output-dir`` itself already exists you will see a
136138
# ``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``.
139+
# fresh, manually remove the output directory before re-running ``modelarrayio h5-to-mif``.
138140

139141
# %%
140142
# Additional help

0 commit comments

Comments
 (0)