"""
MIF (Fixel-wise) Data Conversion
================================

To convert fixel-wise data in MIF format to HDF5 format,
use the ``modelarrayio to-modelarray`` command to convert the MIF files to the HDF5 format
(``.h5``) used by **ModelArray**,
and ``modelarrayio export-results`` to export results back to MIF.
This guide assumes **ModelArrayIO** is already installed.
"""

# %%
# Prepare data
# ------------
#
# To convert a list of fixel-wise data from ``.mif`` to ``.h5`` format, prepare a cohort CSV
# file that describes every ``.mif`` file you want to include.  We recommend one CSV per scalar
# (e.g. FD, FC, FDC), yielding one ``.h5`` file per scalar.
#
# Cohort CSV columns (names are fixed, not user-defined):
#
# * ``scalar_name`` — which metric is being analysed (e.g. ``FD``, ``FC``, ``FDC``)
# * ``source_file`` — path to the ``.mif`` file for this subject

# %%
# Example folder structure
# ------------------------
#
# .. code-block:: text
#
#     /home/username/myProject/data
#     |
#     ├── cohort_FD.csv
#     │
#     ├── FD
#     │   ├── index.mif
#     │   ├── directions.mif
#     │   ├── sub-01_fd.mif
#     │   ├── sub-02_fd.mif
#     │   ├── sub-03_fd.mif
#     │   └── ...
#     │
#     ├── FC
#     │   ├── index.mif
#     │   ├── directions.mif
#     │   ├── sub-01_fc.mif
#     │   ├── sub-02_fc.mif
#     │   ├── sub-03_fc.mif
#     │   └── ...
#     └── ...
#
# These ``.mif`` files are generated by MRtrix.
#
# Corresponding ``cohort_FD.csv`` for scalar FD:
#
# .. list-table::
#    :header-rows: 1
#    :widths: auto
#
#    * - **scalar_name** *(required)*
#      - **source_file** *(required)*
#      - subject_id
#      - age
#      - sex
#    * - FD
#      - /home/username/myProject/data/FD/sub-01_fd.mif
#      - sub-01
#      - 10
#      - F
#    * - FD
#      - /home/username/myProject/data/FD/sub-02_fd.mif
#      - sub-02
#      - 20
#      - M
#    * - FD
#      - /home/username/myProject/data/FD/sub-03_fd.mif
#      - 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 .mif files to HDF5
# --------------------------
#
# Using the FD dataset from the example above:
#
# .. code-block:: console
#
#     # activate your conda environment first
#     conda activate <env_name>
#
#     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 \
#         --output          /home/username/myProject/data/FD.h5
#
# This produces ``FD.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 .mif files
# --------------------------------------
#
# After running ModelArray and obtaining statistical results inside ``FD.h5`` (suppose the
# 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 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 \
#         --analysis-name   mylm \
#         --input-hdf5      /home/username/myProject/data/FD.h5 \
#         --output-dir      /home/username/myProject/data/FD_stats
#
# The results in ``FD_stats`` can now be viewed in ``mrview``.
#
# .. warning::
#
#    **Existing files are not overwritten.** With ``modelarrayio export-results``, 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 export-results``.

# %%
# Additional help
# ---------------
#
# Full argument documentation is available from the command line:
#
# .. code-block:: console
#
#     modelarrayio to-modelarray --help
#     modelarrayio export-results --help
#
# or in the :doc:`/usage` page of this documentation.