.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_cifti_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_cifti_workflow.py: CIFTI (Greyordinate-wise) Data Conversion ========================================= For imaging data in CIFTI format, use the ``modelarrayio to-modelarray`` command to convert the CIFTI files to the HDF5 format (``.h5``) used by **ModelArray**, and ``modelarrayio export-results`` to export results back to CIFTI. The CIFTI workflow is very similar to the MIF workflow (:ref:`sphx_glr_auto_examples_plot_mif_workflow.py`). .. GENERATED FROM PYTHON SOURCE LINES 13-24 Prepare data ------------ 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). 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 CIFTI file .. GENERATED FROM PYTHON SOURCE LINES 26-80 Example folder structure ------------------------ .. code-block:: text /home/username/myProject/data | ├── cohort_FA.csv │ ├── FA │ ├── sub-01_FA.dscalar.nii │ ├── sub-02_FA.dscalar.nii │ ├── sub-03_FA.dscalar.nii │ └── ... │ └── ... Corresponding ``cohort_FA.csv`` for scalar FA: .. list-table:: :header-rows: 1 :widths: auto * - **scalar_name** *(required)* - **source_file** *(required)* - subject_id - age - sex * - FA - /home/username/myProject/data/FA/sub-01_FA.dscalar.nii - sub-01 - 10 - F * - FA - /home/username/myProject/data/FA/sub-02_FA.dscalar.nii - sub-02 - 20 - M * - FA - /home/username/myProject/data/FA/sub-03_FA.dscalar.nii - 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 82-98 Convert CIFTI files to HDF5 --------------------------- Using the FA dataset from the example above: .. code-block:: console # activate your conda environment first conda activate modelarrayio to-modelarray \ --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 100-127 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. 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 \ --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``. Results in ``FA_stats`` can be viewed with any CIFTI 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 129-155 Number-of-observations image ---------------------------- If you requested ``nobs`` during model fitting in ModelArray, after conversion you will find an image called ``*_model.nobs.dscalar.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 greyordinates: .. 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 157-168 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_cifti_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_cifti_workflow.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_cifti_workflow.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_cifti_workflow.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_