Fix names and paths in examples

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,4 @@
+contact_links:
+  - name: Usage question
+    url: https://neurostars.org/tags/c/software-support/234/modelarray
+    about: Please ask questions about using ModelArrayIO on NeuroStars.

README.rst

@@ -50,70 +50,19 @@ Once ModelArrayIO is installed, these commands are available in your terminal:
 
 * **Fixel-wise** data (MRtrix ``.mif``):
 
-  * ``.mif`` → ``.h5``: ``confixel`` (CLI name kept for compatibility with earlier ConFixel workflows)
-  * ``.h5`` → ``.mif``: ``fixelstats_write``
+  * ``.mif`` → ``.h5``: ``modelarrayio mif-to-h5``
+  * ``.h5`` → ``.mif``: ``modelarrayio h5-to-mif``
 
 * **Voxel-wise** data (NIfTI):
 
-  * NIfTI → ``.h5``: ``convoxel``
-  * ``.h5`` → NIfTI: ``volumestats_write``
+  * NIfTI → ``.h5``: ``modelarrayio nifti-to-h5``
+  * ``.h5`` → NIfTI: ``modelarrayio h5-to-nifti``
 
 * **Greyordinate-wise** data (CIFTI-2):
 
-  * CIFTI-2 → ``.h5``: ``concifti``
-  * ``.h5`` → CIFTI-2: ``ciftistats_write``
+  * CIFTI-2 → ``.h5``: ``modelarrayio cifti-to-h5``
+  * ``.h5`` → CIFTI-2: ``modelarrayio h5-to-cifti``
 
-Installation
-============
-
-MRtrix (required for fixel ``.mif`` only)
------------------------------------------
-
-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.
-
-If your data are voxel-wise or CIFTI only, you can skip this step.
-
-Install ModelArrayIO
---------------------
-
-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.
-
-Install from GitHub:
-
-.. code-block:: console
-
-   git clone https://github.com/PennLINC/ModelArrayIO.git
-   cd ModelArrayIO
-   pip install .   # build via pyproject.toml
-
-Editable install for development:
-
-.. code-block:: console
-
-   # From the repository root
-   pip install -e .
-
-With ``hatch`` installed, you can build wheels/sdist locally:
-
-.. code-block:: console
-
-   hatch build
-   pip install dist/*.whl
-
-How to use
-==========
-
-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``).
-
-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).
-
-CLI help:
-
-.. code-block:: console
-
-   confixel --help
-
-Use the same pattern for ``convoxel``, ``concifti``, ``fixelstats_write``, ``volumestats_write``, and ``ciftistats_write``.
 
 Storage backends: HDF5 and TileDB
 =================================

docs/examples/plot_cifti_workflow.py

@@ -0,0 +1,167 @@
+"""
+CIFTI (Greyordinate-wise) Data Conversion
+=========================================
+
+For imaging data in CIFTI format, use the ``modelarrayio cifti-to-h5`` command to convert
+the CIFTI files to the HDF5 format (``.h5``) used by **ModelArray**,
+and ``modelarrayio h5-to-cifti`` 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 cifti-to-h5 \
+#         --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 h5-to-cifti`` 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 h5-to-cifti \
+#         --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 h5-to-cifti`` 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 h5-to-cifti``.
+
+# %%
+# 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 cifti-to-h5 --help
+#     modelarrayio h5-to-cifti --help
+#
+# or in the :doc:`/usage` page of this documentation.

docs/examples/plot_fixel_workflow.py

@@ -1,10 +1,12 @@
 """
-Fixel-wise Data Conversion
-==========================
+MIF (Fixel-wise) Data Conversion
+================================
 
-For fixel-wise data, use the **``confixel``** command from **ModelArrayIO** to convert between
-MRtrix ``.mif`` files and the HDF5 format (``.h5``) used by ModelArray.  This guide assumes
-ModelArrayIO and MRtrix are already installed.
+To convert fixel-wise data in MIF format to HDF5 format,
+use the ``modelarrayio mif-to-h5`` command to convert the MIF files to the HDF5 format
+(``.h5``) used by **ModelArray**,
+and ``modelarrayio h5-to-mif`` to export results back to MIF.
+This guide assumes **ModelArrayIO** and **MRtrix** are already installed.
 """
 
 # %%
@@ -61,17 +63,17 @@
 #      - age
 #      - sex
 #    * - FD
-#      - FD/sub-01_fd.mif
+#      - /home/username/myProject/data/FD/sub-01_fd.mif
 #      - sub-01
 #      - 10
 #      - F
 #    * - FD
-#      - FD/sub-02_fd.mif
+#      - /home/username/myProject/data/FD/sub-02_fd.mif
 #      - sub-02
 #      - 20
 #      - M
 #    * - FD
-#      - FD/sub-03_fd.mif
+#      - /home/username/myProject/data/FD/sub-03_fd.mif
 #      - sub-03
 #      - 15
 #      - F
@@ -112,7 +114,7 @@
 # --------------------------------------
 #
 # After running ModelArray and obtaining statistical results inside ``FD.h5`` (suppose the
-# analysis name is ``"mylm"``), use ``fixelstats_write`` to export them as ``.mif`` files.
+# analysis name is ``"mylm"``), use ``modelarrayio h5-to-mif`` to export them as ``.mif`` files.
 # The command also copies the original ``index.mif`` and ``directions.mif`` into the output
 # folder.
 #
@@ -130,11 +132,11 @@
 #
 # .. warning::
 #
-#    **Existing files are not overwritten.**  ``fixelstats_write`` calls ``mrconvert`` without
+#    **Existing files are not overwritten.**  ``modelarrayio h5-to-mif`` 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 ``fixelstats_write``.
+#    fresh, manually remove the output directory before re-running ``modelarrayio h5-to-mif``.
 
 # %%
 # Additional help