.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_voxel_workflow.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_plot_voxel_workflow.py: NIfTI (Voxel-wise) Data Conversion ================================== 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 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`). .. GENERATED FROM PYTHON SOURCE LINES 13-29 Prepare data ------------ To convert a list of NIfTI files to ``.h5`` format, you need: 1. **A cohort CSV** describing every NIfTI file to include (one CSV per scalar recommended). 2. **A group mask** — only voxels inside the group mask are kept during conversion. 3. **Subject-specific masks** *(optional)* — voxels outside each subject's mask are set to ``NaN`` after conversion. If you do not have per-subject masks, supply the group mask for every subject (see the CSV example below). Cohort CSV columns (names are fixed, not user-defined): * ``scalar_name`` — which metric is being analysed (e.g., ``FA``) * ``source_file`` — path to the subject's NIfTI file * ``source_mask_file`` — path to the subject-specific mask (or the group mask if none exists) .. GENERATED FROM PYTHON SOURCE LINES 31-96 Example folder structure ------------------------ .. code-block:: text /home/username/myProject/data | ├── cohort_FA.csv ├── group_mask.nii.gz │ ├── FA │ ├── sub-01_FA.nii.gz │ ├── sub-02_FA.nii.gz │ ├── sub-03_FA.nii.gz │ └── ... │ ├── individual_masks │ ├── sub-01_mask.nii.gz │ ├── sub-02_mask.nii.gz │ ├── sub-03_mask.nii.gz │ └── ... └── ... Corresponding ``cohort_FA.csv`` for scalar FA: .. list-table:: :header-rows: 1 :widths: auto * - **scalar_name** *(required)* - **source_file** *(required)* - **source_mask_file** *(required)* - subject_id - age - sex * - FA - /home/username/myProject/data/FA/sub-01_FA.nii.gz - /home/username/myProject/data/individual_masks/sub-01_mask.nii.gz - sub-01 - 10 - F * - FA - /home/username/myProject/data/FA/sub-02_FA.nii.gz - /home/username/myProject/data/individual_masks/sub-02_mask.nii.gz - sub-02 - 20 - M * - FA - /home/username/myProject/data/FA/sub-03_FA.nii.gz - /home/username/myProject/data/individual_masks/sub-03_mask.nii.gz - 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 98-115 Convert NIfTI files to HDF5 --------------------------- Using the FA dataset from the example above: .. code-block:: console # activate your conda environment first conda activate 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 This produces ``FA.h5`` in ``/home/username/myProject/data``. You can then use `ModelArray `_ to run statistical analyses on it. .. GENERATED FROM PYTHON SOURCE LINES 117-142 Convert result .h5 back to NIfTI -------------------------------- After running **ModelArray** and obtaining statistical results inside ``FA.h5`` (suppose the analysis name is ``"mylm"``), use ``modelarrayio export-results`` to export them as NIfTI files. .. code-block:: console modelarrayio export-results \ --mask /home/username/myProject/data/group_mask.nii.gz \ --analysis-name mylm \ --input-hdf5 /home/username/myProject/data/FA.h5 \ --output-dir /home/username/myProject/data/FA_stats All converted volume data are saved as ``float32`` and compressed (``.nii.gz``) by default. Pass ``--no-compress`` to write uncompressed ``.nii`` files instead. Results in ``FA_stats`` can be viewed with any NIfTI image viewer. .. warning:: 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 export-results``. .. GENERATED FROM PYTHON SOURCE LINES 144-170 Number-of-observations image ---------------------------- If you requested ``nobs`` during model fitting in ModelArray, after conversion you will find an image called ``*_model.nobs.nii*``. With subject-specific masks, this image may be inhomogeneous across voxels. Voxels that did not have sufficient subjects (due to subject-specific masking) are stored as ``NaN`` in the HDF5 file. How different viewers display these voxels: .. list-table:: :header-rows: 1 :widths: auto * - Viewer - Regular voxel - Voxel without sufficient subjects * - nibabel (Python) - e.g. ``nobs: 209.0``, ``p.value: 0.01`` - ``NaN`` * - MRtrix mrview - e.g. ``nobs: 209``, ``p.value: 0.01`` - ``?`` * - ITK-SNAP - e.g. ``nobs: 209``, ``p.value: 0.01`` - ``0`` (displayed, but excluded when thresholding) .. GENERATED FROM PYTHON SOURCE LINES 172-183 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_voxel_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_voxel_workflow.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_voxel_workflow.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_voxel_workflow.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_