Simplify commands to automatically detect modality

README.rst

@@ -30,7 +30,7 @@ ModelArrayIO
    :target: https://github.com/astral-sh/ruff
    :alt: Code style: ruff
 
-**ModelArrayIO** is a Python package that converts between neuroimaging formats (fixel ``.mif``, voxel NIfTI, CIFTI-2 dscalar) and the HDF5 (``.h5``) layout used by the R package `ModelArray <https://pennlinc.github.io/ModelArray/>`_. It can also write ModelArray statistical results back to imaging formats.
+**ModelArrayIO** is a Python package that converts between neuroimaging formats (fixel ``.mif``, voxel NIfTI, CIFTI-2 dscalar/pscalar/pconn) and the HDF5 (``.h5``) layout used by the R package `ModelArray <https://pennlinc.github.io/ModelArray/>`_. It can also write ModelArray statistical results back to imaging formats.
 
 **Relationship to ConFixel:** The earlier project `ConFixel <https://github.com/PennLINC/ConFixel>`_ is superseded by ModelArrayIO. The ConFixel repository is retained for history (including links from publications) and will be archived; new work should use this repository.
 
@@ -48,20 +48,10 @@ ModelArrayIO provides three converter areas, each with import and export command
 
 Once ModelArrayIO is installed, these commands are available in your terminal:
 
-* **Fixel-wise** data (MRtrix ``.mif``):
+* Neuroimaging data (CIFTI, NIfTI, or MRtrix ``.mif``):
 
-  * ``.mif`` → ``.h5``: ``modelarrayio mif-to-h5``
-  * ``.h5`` → ``.mif``: ``modelarrayio h5-to-mif``
-
-* **Voxel-wise** data (NIfTI):
-
-  * NIfTI → ``.h5``: ``modelarrayio nifti-to-h5``
-  * ``.h5`` → NIfTI: ``modelarrayio h5-to-nifti``
-
-* **Greyordinate-wise** data (CIFTI-2):
-
-  * CIFTI-2 → ``.h5``: ``modelarrayio cifti-to-h5``
-  * ``.h5`` → CIFTI-2: ``modelarrayio h5-to-cifti``
+  * Neuroimaging → ``.h5``: ``modelarrayio to-modelarray``
+  * ``.h5`` → Neuroimaging: ``modelarrayio export-results``
 
 
 Storage backends: HDF5 and TileDB

docs/examples/plot_cifti_workflow.py

@@ -2,9 +2,9 @@
 CIFTI (Greyordinate-wise) Data Conversion
 =========================================
 
-For imaging data in CIFTI format, use the ``modelarrayio cifti-to-h5`` command to convert
+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 h5-to-cifti`` to export results back to CIFTI.
+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`).
 """
@@ -89,7 +89,7 @@
 #     # activate your conda environment first
 #     conda activate <env_name>
 #
-#     modelarrayio cifti-to-h5 \
+#     modelarrayio to-modelarray \
 #         --cohort-file     /home/username/myProject/data/cohort_FA.csv \
 #         --output          /home/username/myProject/data/FA.h5
 #
@@ -101,13 +101,13 @@
 # --------------------------------
 #
 # 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.
+# 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 h5-to-cifti \
+#     modelarrayio export-results \
 #         --cohort-file     /home/username/myProject/data/cohort_FA.csv \
 #         --analysis-name   mylm \
 #         --input-hdf5      /home/username/myProject/data/FA.h5 \
@@ -119,11 +119,11 @@
 #
 # .. warning::
 #
-#    If ``--output-dir`` already exists, ``modelarrayio h5-to-cifti`` will not delete it — you will
+#    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 h5-to-cifti``.
+#    directory before re-running ``modelarrayio export-results``.
 
 # %%
 # Number-of-observations image
@@ -161,7 +161,7 @@
 #
 # .. code-block:: console
 #
-#     modelarrayio cifti-to-h5 --help
-#     modelarrayio h5-to-cifti --help
+#     modelarrayio to-modelarray --help
+#     modelarrayio export-results --help
 #
 # or in the :doc:`/usage` page of this documentation.

docs/examples/plot_fixel_workflow.py

@@ -3,9 +3,9 @@
 ================================
 
 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
+use the ``modelarrayio to-modelarray`` 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.
+and ``modelarrayio export-results`` to export results back to MIF.
 This guide assumes **ModelArrayIO** and **MRtrix** are already installed.
 """
 
@@ -100,7 +100,7 @@
 #     # activate your conda environment first
 #     conda activate <env_name>
 #
-#     modelarrayio mif-to-h5 \
+#     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 \
@@ -114,13 +114,13 @@
 # --------------------------------------
 #
 # After running ModelArray and obtaining statistical results inside ``FD.h5`` (suppose the
-# analysis name is ``"mylm"``), use ``modelarrayio h5-to-mif`` to export them as ``.mif`` files.
+# 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 h5-to-mif \
+#     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 \
@@ -132,11 +132,11 @@
 #
 # .. warning::
 #
-#    **Existing files are not overwritten.**  ``modelarrayio h5-to-mif`` calls ``mrconvert`` without
+#    **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 h5-to-mif``.
+#    fresh, manually remove the output directory before re-running ``modelarrayio export-results``.
 
 # %%
 # Additional help
@@ -146,7 +146,7 @@
 #
 # .. code-block:: console
 #
-#     modelarrayio mif-to-h5 --help
-#     modelarrayio h5-to-mif --help
+#     modelarrayio to-modelarray --help
+#     modelarrayio export-results --help
 #
 # or in the :doc:`/usage` page of this documentation.

docs/examples/plot_voxel_workflow.py

@@ -2,9 +2,9 @@
 NIfTI (Voxel-wise) Data Conversion
 ==================================
 
-For imaging data in NIfTI format, use the ``modelarrayio nifti-to-h5`` command to convert
+For imaging data in NIfTI format, use the ``modelarrayio to-modelarray`` command to convert
 the NIfTI files to the HDF5 format (``.h5``) used by **ModelArray**,
-and ``modelarrayio h5-to-nifti`` to export results back to NIfTI.
+and ``modelarrayio export-results`` to export results back to NIfTI.
 The voxel workflow is very similar to the fixel workflow
 (:ref:`sphx_glr_auto_examples_plot_mif_workflow.py`).
 """
@@ -105,8 +105,8 @@
 #     # activate your conda environment first
 #     conda activate <env_name>
 #
-#     modelarrayio nifti-to-h5 \
-#         --group-mask-file /home/username/myProject/data/group_mask.nii.gz \
+#     modelarrayio to-modelarray \
+#         --mask /home/username/myProject/data/group_mask.nii.gz \
 #         --cohort-file     /home/username/myProject/data/cohort_FA.csv \
 #         --output          /home/username/myProject/data/FA.h5
 #
@@ -118,12 +118,12 @@
 # --------------------------------
 #
 # After running **ModelArray** and obtaining statistical results inside ``FA.h5`` (suppose the
-# analysis name is ``"mylm"``), use ``modelarrayio h5-to-nifti`` to export them as NIfTI files.
+# analysis name is ``"mylm"``), use ``modelarrayio export-results`` to export them as NIfTI files.
 #
 # .. code-block:: console
 #
-#     modelarrayio h5-to-nifti \
-#         --group-mask-file /home/username/myProject/data/group_mask.nii.gz \
+#     modelarrayio export-results \
+#         --mask /home/username/myProject/data/group_mask.nii.gz \
 #         --cohort-file     /home/username/myProject/data/cohort_FA.csv \
 #         --analysis-name   mylm \
 #         --input-hdf5      /home/username/myProject/data/FA.h5 \
@@ -135,11 +135,11 @@
 #
 # .. warning::
 #
-#    If ``--output-dir`` already exists, ``modelarrayio h5-to-nifti`` will not delete it — you will
+#    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 h5-to-nifti``.
+#    directory before re-running ``modelarrayio export-results``.
 
 # %%
 # Number-of-observations image
@@ -177,7 +177,7 @@
 #
 # .. code-block:: console
 #
-#     modelarrayio nifti-to-h5 --help
-#     modelarrayio h5-to-nifti --help
+#     modelarrayio to-modelarray --help
+#     modelarrayio export-results --help
 #
 # or in the :doc:`/usage` page of this documentation.

docs/installation.rst

@@ -17,7 +17,7 @@ If you want to use the most up-to-date version, you can install from the ``main`
 MRtrix (required for fixel ``.mif`` only)
 -----------------------------------------
 
-For fixel-wise ``.mif`` conversion, the ``modelarrayio mif-to-h5`` / ``modelarrayio h5-to-mif`` tools use MRtrix ``mrconvert``.
+Fixel-wise ``.mif`` conversion 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.