.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_fixel_workflow.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_fixel_workflow.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_fixel_workflow.py:


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.

.. GENERATED FROM PYTHON SOURCE LINES 13-24

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

.. GENERATED FROM PYTHON SOURCE LINES 26-91

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.

.. GENERATED FROM PYTHON SOURCE LINES 93-111

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.

.. GENERATED FROM PYTHON SOURCE LINES 113-140

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``.

.. GENERATED FROM PYTHON SOURCE LINES 142-153

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.


.. _sphx_glr_download_auto_examples_plot_fixel_workflow.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_fixel_workflow.ipynb <plot_fixel_workflow.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_fixel_workflow.py <plot_fixel_workflow.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_fixel_workflow.zip <plot_fixel_workflow.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_