Improve documentation of new features

README.rst

@@ -59,8 +59,8 @@ Storage backends: HDF5 and TileDB
 
 ModelArrayIO supports two on-disk backends for the subject-by-element matrix:
 
-* HDF5 (default), implemented in ``modelarrayio/h5_storage.py``
-* TileDB, implemented in ``modelarrayio/tiledb_storage.py``
+* HDF5 (default), implemented in ``src/modelarrayio/storage/h5_storage.py``
+* TileDB, implemented in ``src/modelarrayio/storage/tiledb_storage.py``
 
 Both backends expose a similar API:
 
@@ -71,6 +71,6 @@ Both backends expose a similar API:
 Notes and minor differences:
 
 * Chunking vs tiling: HDF5 uses chunks; TileDB uses tiles. We compute tile sizes analogous to chunk sizes to keep write/read patterns similar.
-* Compression: HDF5 uses ``gzip`` by default; TileDB defaults to ``zstd`` with shuffle for better speed/ratio. You can switch to ``gzip`` for parity.
+* Compression: HDF5 uses ``gzip`` by default; TileDB defaults to ``gzip`` with shuffle for better speed/ratio. You can switch to ``gzip`` for parity.
 * Metadata: HDF5 stores ``column_names`` as a dataset attribute; TileDB stores names as JSON metadata on the array/group.
 * Layout: Both backends keep dimensions in the same order and use zero-based indices.

docs/examples/README.rst

@@ -2,4 +2,5 @@ Walkthroughs
 ============
 
 Step-by-step guides for converting neuroimaging data to and from the HDF5
-format used by `ModelArray <https://pennlinc.github.io/ModelArray/>`_.
+format used by `ModelArray <https://pennlinc.github.io/ModelArray/>`_. Each
+workflow includes cohort CSV examples in both long and wide formats.

docs/examples/plot_cifti_workflow.py

@@ -15,12 +15,16 @@
 #
 # 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).
+# 1. **A cohort CSV** describing every CIFTI file to include.
 #
-# Cohort CSV columns (names are fixed, not user-defined):
+# The cohort CSV may use either of these layouts:
 #
-# * ``scalar_name`` — which metric is being analysed (e.g., ``FA``)
-# * ``source_file`` — path to the subject's CIFTI file
+# * **Long format:** one row per subject and scalar, with the fixed columns ``scalar_name`` and
+#   ``source_file``.
+# * **Wide format:** one row per subject, with a separate file-path column for each scalar
+#   (for example, ``FA`` and ``MD``). Pass those column names to ``--scalar-columns``.
+#
+# Other columns, such as subject IDs and demographics, may appear alongside the path columns.
 
 # %%
 # Example folder structure
@@ -30,17 +34,27 @@
 #
 #     /home/username/myProject/data
 #     |
-#     ├── cohort_FA.csv
+#     ├── cohort_long.csv
+#     ├── cohort_wide.csv
 #     │
 #     ├── FA
 #     │   ├── sub-01_FA.dscalar.nii
 #     │   ├── sub-02_FA.dscalar.nii
 #     │   ├── sub-03_FA.dscalar.nii
 #     │   └── ...
 #     │
+#     ├── MD
+#     │   ├── sub-01_MD.dscalar.nii
+#     │   ├── sub-02_MD.dscalar.nii
+#     │   ├── sub-03_MD.dscalar.nii
+#     │   └── ...
+#     │
 #     └── ...
 #
-# Corresponding ``cohort_FA.csv`` for scalar FA:
+# Long-format cohort CSV
+# ----------------------
+#
+# Corresponding ``cohort_long.csv`` for scalars FA and MD:
 #
 # .. list-table::
 #    :header-rows: 1
@@ -66,6 +80,21 @@
 #      - sub-03
 #      - 15
 #      - F
+#    * - MD
+#      - /home/username/myProject/data/MD/sub-01_MD.dscalar.nii
+#      - sub-01
+#      - 10
+#      - F
+#    * - MD
+#      - /home/username/myProject/data/MD/sub-02_MD.dscalar.nii
+#      - sub-02
+#      - 20
+#      - M
+#    * - MD
+#      - /home/username/myProject/data/MD/sub-03_MD.dscalar.nii
+#      - sub-03
+#      - 15
+#      - F
 #    * - ...
 #      - ...
 #      - ...
@@ -79,39 +108,115 @@
 #   between the CSV and disk.
 
 # %%
-# Convert CIFTI files to HDF5
-# ---------------------------
+# Wide-format cohort CSV
+# ----------------------
+#
+# A wide CSV stores all scalar paths for a subject on one row. For example,
+# ``cohort_wide.csv`` can contain both FA and MD:
 #
-# Using the FA dataset from the example above:
+# .. list-table::
+#    :header-rows: 1
+#    :widths: auto
+#
+#    * - subject_id
+#      - **FA**
+#      - **MD**
+#      - age
+#      - sex
+#    * - sub-01
+#      - /home/username/myProject/data/FA/sub-01_FA.dscalar.nii
+#      - /home/username/myProject/data/MD/sub-01_MD.dscalar.nii
+#      - 10
+#      - F
+#    * - sub-02
+#      - /home/username/myProject/data/FA/sub-02_FA.dscalar.nii
+#      - /home/username/myProject/data/MD/sub-02_MD.dscalar.nii
+#      - 20
+#      - M
+#    * - ...
+#      - ...
+#      - ...
+#      - ...
+#      - ...
+#
+# ``FA`` and ``MD`` are user-defined scalar column names. All files for a scalar must use
+# compatible CIFTI axes.
+
+# %%
+# Convert a long-format cohort
+# ----------------------------
+#
+# Long-format cohorts combine all scalars into one output by default. The
+# ``--no-split-files`` flag below makes that choice explicit:
 #
 # .. 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
+#         --cohort-file     /home/username/myProject/data/cohort_long.csv \
+#         --no-split-files \
+#         --output          /home/username/myProject/data/modelarray.h5
+#
+# This creates one ``modelarray.h5`` containing both ``scalars/FA`` and ``scalars/MD``.
+# To write one file per scalar instead, use ``--split-files`` with the same output basename:
+#
+# .. code-block:: console
+#
+#     modelarrayio to-modelarray \
+#         --cohort-file /home/username/myProject/data/cohort_long.csv \
+#         --split-files \
+#         --output      /home/username/myProject/data/modelarray.h5
+#
+# The split command creates ``FA_modelarray.h5`` and ``MD_modelarray.h5``. You can then use
+# `ModelArray <https://pennlinc.github.io/ModelArray/>`_ to run statistical analyses on either
+# the combined output or the scalar-specific outputs.
+
+# %%
+# Convert a wide-format cohort
+# ----------------------------
+#
+# Name each scalar path column with ``--scalar-columns``:
+#
+# .. code-block:: console
+#
+#     modelarrayio to-modelarray \
+#         --cohort-file    /home/username/myProject/data/cohort_wide.csv \
+#         --scalar-columns FA MD \
+#         --output         /home/username/myProject/data/modelarray.h5
+#
+# Wide cohorts write one output per scalar by default. This command creates
+# ``FA_modelarray.h5`` and ``MD_modelarray.h5``. To override that default, add
+# ``--no-split-files``:
+#
+# .. code-block:: console
+#
+#     modelarrayio to-modelarray \
+#         --cohort-file     /home/username/myProject/data/cohort_wide.csv \
+#         --scalar-columns  FA MD \
+#         --no-split-files \
+#         --output          /home/username/myProject/data/modelarray.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.
+# This creates one ``modelarray.h5`` containing both scalar groups.
 
 # %%
 # 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.
+# After running **ModelArray** and obtaining statistical results inside ``FA_modelarray.h5``
+# (suppose the analysis name is ``"mylm"``), use ``modelarrayio export-results`` to export them
+# as CIFTI files.
 #
 # Supply either ``--cohort-file`` (the first ``source_file`` entry is used as a header template)
 # or ``--example-file`` (an explicit template path) — these two flags are mutually exclusive.
 #
 # .. code-block:: console
 #
 #     modelarrayio export-results \
-#         --cohort-file     /home/username/myProject/data/cohort_FA.csv \
+#         --cohort-file     /home/username/myProject/data/cohort_long.csv \
 #         --analysis-name   mylm \
-#         --input-hdf5      /home/username/myProject/data/FA.h5 \
+#         --input-hdf5      /home/username/myProject/data/FA_modelarray.h5 \
 #         --output-dir      /home/username/myProject/data/FA_stats
 #
 # All converted volume data are saved as ``float32``.  Results in ``FA_stats`` can be viewed