Note

Go to the end to download the full example code.

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

/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:

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:

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

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:

modelarrayio to-modelarray --help
modelarrayio export-results --help

or in the Usage page of this documentation.

Gallery generated by Sphinx-Gallery