Add official recon spec for ss3t FOD autotrack

.circleci/config.yml

@@ -125,6 +125,30 @@ jobs:
           paths:
             - /src/qsirecon/.circleci/data/hsvs_data
 
+  Recon_SS3T_FOD_AutoTrack:
+    <<: *dockersetup
+    steps:
+      - checkout
+      - restore_cache:
+          key: singleshell_output-01
+      - run: *runinstall
+      - run:
+          name: Test the SS3T AutoTrack workflow
+          no_output_timeout: 1h
+          command: |
+            pytest -rP -o log_cli=true -m "ss3t_fod_autotrack" --cov-config=/src/qsirecon/pyproject.toml --cov-append --cov-report term-missing --cov=qsirecon --data_dir=/src/qsirecon/.circleci/data --output_dir=/src/qsirecon/.circleci/out --working_dir=/src/qsirecon/.circleci/work qsirecon
+            mkdir /src/coverage
+            mv /src/qsirecon/.coverage /src/coverage/.coverage.ss3t_fod_autotrack
+            # remove nifti files before uploading artifacts
+            find /src/qsirecon/.circleci/out/ -name "*.nii.gz" -type f -delete
+            find /src/qsirecon/.circleci/out/ -name "*.fib.gz" -type f -delete
+      - persist_to_workspace:
+          root: /src/coverage/
+          paths:
+            - .coverage.ss3t_fod_autotrack
+      - store_artifacts:
+          path: /src/qsirecon/.circleci/out/ss3t_fod_autotrack/
+
   Recon_3Tissue_Singleshell_ACT:
     <<: *dockersetup
     steps:
@@ -616,6 +640,13 @@ workflows:
             tags:
               only: /.*/
 
+      - Recon_SS3T_FOD_AutoTrack:
+          requires:
+            - download_singleshell_output
+          filters:
+            tags:
+              only: /.*/
+
       - Recon_msmt_Multishell_HSVS:
           requires:
             - download_hsvs_data
@@ -718,6 +749,7 @@ workflows:
           requires:
             - Recon_3Tissue_Singleshell_ACT
             - Recon_3Tissue_Singleshell_NoACT
+            - Recon_SS3T_FOD_AutoTrack
             - Recon_MRtrix3
             - Recon_Interfaces
             - Recon_AutoTrack
@@ -743,6 +775,7 @@ workflows:
           requires:
             - Recon_3Tissue_Singleshell_ACT
             - Recon_3Tissue_Singleshell_NoACT
+            - Recon_SS3T_FOD_AutoTrack
             - Recon_MRtrix3
             - Recon_Interfaces
             - Recon_msmt_Multishell_HSVS

docs/builtin_workflows.rst

@@ -273,16 +273,22 @@ Other Outputs
    :widths: 15, 30
 
 
-.. _ss3t_autotrack:
+.. _ss3t_fod_autotrack:
 
-``ss3t_autotrack``
-========================
+``ss3t_fod_autotrack``
+======================
 
 This workflow is identical to :ref:`dsi_studio_autotrack`, except it substitutes
 the GQI fit with the ``ss3t_csd_beta1`` algorithm :footcite:p:`dhollander2016novel`
 to estimate FODs for white matter.
 
+A GQI reconstruction is performed first based on the entier input data.
+The QA and ISO images from GQI are used to register the ACPC data to DSI Studio's ICBM 152 template.
+The GQI-based registration is used to transform the template bundles to subject ACPC space,
+where the SS3T-based FODs are used for tractography.
+
 This is a good workflow for doing tractometry on low-quality single shell data.
+If more than one shell is present in the input data, only the highest b-value shell is used.
 
 Scalar Maps
 -----------
@@ -295,7 +301,7 @@ Other Outputs
 -------------
 .. csv-table::
    :header: "File Name", "Description"
-   :file: nonscalars/ss3t_autotrack.csv
+   :file: nonscalars/ss3t_fod_autotrack.csv
    :widths: 15, 30
 
 .. _tortoise:
@@ -483,6 +489,8 @@ the model-fitting workflows and which sampling schemes work with them.
 +-------------------------------------------+-------------+------------+-----------------+
 |:ref:`mrtrix_singleshell_ss3t_ACT-fast`\*  |     No      |    No      |      Yes        |
 +-------------------------------------------+-------------+------------+-----------------+
+|:ref:`ss3t_fod_autotrack`                  |     Yes     |    No      |      Yes        |
++-------------------------------------------+-------------+------------+-----------------+
 |:ref:`pyafq_tractometry`                   |     Yes     |    No      |      Yes        |
 +-------------------------------------------+-------------+------------+-----------------+
 |:ref:`pyafq_input_trk`                     |     Yes     |    No      |      Yes        |
@@ -495,8 +503,6 @@ the model-fitting workflows and which sampling schemes work with them.
 +-------------------------------------------+-------------+------------+-----------------+
 |:ref:`dsi_studio_autotrack`                |     Yes     |   Yes      |    Yes          |
 +-------------------------------------------+-------------+------------+-----------------+
-|:ref:`ss3t_autotrack`                      |     No      |   No       |    Yes          |
-+-------------------------------------------+-------------+------------+-----------------+
 |:ref:`dipy_mapmri`                         |     Yes     |   Yes      |      No         |
 +-------------------------------------------+-------------+------------+-----------------+
 |:ref:`dipy_dki`                            |     Yes     |    No      |      No         |

docs/nonscalars/README

@@ -0,0 +1,2 @@
+WARING: Do not edit these csv files directly!
+They are created by ../update_scalardefs.py

docs/nonscalars/dsistudio_autotrack.csv

@@ -1,5 +1,5 @@
-\*_streamlines.tck.gz,One tck.gz per bundle. The bundle represented by this file is specified in the ``bundle-`` tag.
-\*bundles-DSIStudio\*_scalarstats.csv,Statistics on scalars produced by this workflow
+\*_streamlines.tck.gz,One tck.gz per bundle. The bundle represented by this file is specified in the ``bundle-`` tag. 
+\*bundles-DSIStudio\*_scalarstats.csv,Statistics on scalars produced by this workflow 
 \*bundles-DSIStudio\*_tdistats.tsv,Statistics on streamline density in voxels
-\*space-ACPC\*_dwimap.fib.gz,DSI Studio fib format containing the GQI ODFs used for AutoTrack.
-\*space-ACPC\*_mapping.map.gz,Mapping file produced by DSI Studio.
+\*space-ACPC|T1w\*_dwimap.fib.gz,DSI Studio fib format containing the GQI ODFs used for AutoTrack. 
+\*space-ACPC|T1w\*_dwimap.map.gz,Mapping file produced by DSI Studio.

docs/nonscalars/dsistudio_gqi.csv

@@ -1,3 +1,3 @@
-\*_connectivity.mat,MATLAB format mat file containing connectivity matrices for all the selected atlases. This is an hdf5-format file and can be read using ``scipy.io.matlab.loadmat`` in Python.
-\*space-ACPC\*_dwimap.fib.gz,DSI Studio fib format containing the GQI ODFs used for AutoTrack.
-\*space-ACPC\*_mapping.map.gz,Mapping file produced by DSI Studio.
+\*_connectivity.mat,MATLAB format mat file containing connectivity matrices for all the selected atlases. This is an hdf5-format file and can be read using ``scipy.io.matlab.loadmat`` in Python. 
+\*space-ACPC|T1w\*_dwimap.fib.gz,DSI Studio fib format containing the GQI ODFs used for AutoTrack. 
+\*space-ACPC|T1w\*_dwimap.map.gz,Mapping file produced by DSI Studio.

docs/nonscalars/mrtrix_anat.csv

@@ -1,2 +1,2 @@
-\*space-ACPC\*seg-hsvs\*_dseg.nii.gz,Hybrid Surface/Volume Segmentation in MRtrix3 5tt format. Aligned in coordinate space to ``space-ACPC``.
+\*space-ACPC|T1w\*seg-hsvs\*_dseg.nii.gz,Hybrid Surface/Voume Segmentation in MRtrix3 5tt format. Aligned in coordinate space to ``space-ACPC``. 
 \*space-fsnative\*seg-hsvs\*_dseg.nii.gz,Hybrid Surface/Volume Segmentation in MRtrix3 5tt format. Aligned to the FreeSurfer ``orig.mgz`` image.

docs/nonscalars/ss3t_fod_autotrack.csv

@@ -0,0 +1,6 @@
+\*bundles-DSIStudio\*_scalarstats.csv,Statistics on scalars produced by this workflow. 
+\*bundles-DSIStudio\*_tdistats.tsv,Statistics on streamline density in voxels.
+\*model-ss3t\*_streamlines.tck.gz,One tck.gz per bundle. The bundle represented by this file is specified in the ``bundle-`` tag. Bundles were tracked using the SS3t FODs. 
+\*space-ACPC|T1w\*model-gqi\*_dwimap.fib.gz,DSI Studio fib format containing the GQI ODFs used for AutoTrack registration. 
+\*space-ACPC|T1w\*model-ss3t\*_dwimap.fib.gz,DSI Studio fib format containing the SS3T FODs used for AutoTrack. 
+\*space-ACPC|T1w\*model-ss3t\*_dwimap.map.gz,Mapping file produced by DSI Studio. Here the model entity specifies ss3t so that DSI Studio associates the mapping with the model-ss3t fib.gz file. Be aware that this mapping was created using the model-gqi fib.gz file. 

docs/recon_scalars/README

@@ -0,0 +1,2 @@
+WARING: Do not edit these csv files directly!
+They are created by ../update_scalardefs.py

docs/update_scalardefs.py

@@ -90,7 +90,7 @@ def outputs_to_csv(output_def, output_csv):
     load_yaml(load_data("nonscalars/csdsi_3dshore.yaml")), "nonscalars/csdsi_3dshore.csv"
 )
 outputs_to_csv(
-    load_yaml(load_data("nonscalars/ss3t_autotrack.yaml")), "nonscalars/ss3t_autotrack.csv"
+    load_yaml(load_data("nonscalars/ss3t_fod_autotrack.yaml")), "nonscalars/ss3t_fod_autotrack.csv"
 )
 outputs_to_csv(load_yaml(load_data("nonscalars/mrtrix_dwi.yaml")), "nonscalars/mrtrix_dwi.csv")
 outputs_to_csv(load_yaml(load_data("nonscalars/mrtrix_anat.yaml")), "nonscalars/mrtrix_anat.csv")

qsirecon/cli/convertODFs.py

@@ -111,15 +111,15 @@ def mif_to_fib():
     if opts.mask is not None:
         converter = FODtoFIBGZ(
             mif_file=opts.mif,
-            fib_file=opts.fib,
+            output_fib_file=opts.fib,
             num_fibers=opts.num_fibers,
             unit_odf=opts.unit_odf,
             mask_file=opts.mask,
         )
     else:
         converter = FODtoFIBGZ(
             mif_file=opts.mif,
-            fib_file=opts.fib,
+            output_fib_file=opts.fib,
             num_fibers=opts.num_fibers,
             unit_odf=opts.unit_odf,
         )

qsirecon/data/io_spec.json

@@ -14,6 +14,10 @@
             "name": "seg",
             "pattern": "(?:^|_)seg-([a-zA-Z0-9]+)"
         },
+        {
+            "name": "dsistudiotemplate",
+            "pattern": "([a-zA-Z0-9_]+)"
+        },
         {
             "name": "model",
             "pattern": "(?:^|_)model-([a-zA-Z0-9]+)"
@@ -40,6 +44,7 @@
         "sub-{subject}[/ses-{session}]/{datatype<dwi>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<streamlines>}.{extension<tck|tck.gz|json>|tck.gz}",
         "sub-{subject}[/ses-{session}]/{datatype<dwi>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<scalarstats|tdistats|bundlestats|streamlineweights>}.{extension<tsv|csv|json>|tsv}",
         "sub-{subject}[/ses-{session}]/{datatype<dwi>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<mapping>}.{extension<map|map.gz|json>|map.gz}",
+        "sub-{subject}[/ses-{session}]/{datatype<dwi>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<dwimap>}.fib.gz[.{dsistudiotemplate}].{extension<map|map.gz|json>|map.gz}",
         "sub-{subject}[/ses-{session}]/{datatype<dwi|anat>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<mask>}.{extension<nii|nii.gz|json>|nii.gz}",
         "sub-{subject}[/ses-{session}]/{datatype<dwi|anat>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<dseg|probseg>}.{extension<mif|mif.gz|nii.gz|nii|txt|json>|nii.gz}",
         "sub-{subject}[/ses-{session}]/{datatype<dwi>|dwi}/sub-{subject}[_ses-{session}][_acq-{acquisition}][_ce-{ceagent}][_dir-{direction}][_rec-{reconstruction}][_run-{run}][_space-{space}][_cohort-{cohort}][_seg-{seg}][_model-{model}][_bundles-{bundles}][_param-{param}][_bundle-{bundle}][_label-{label}][_desc-{desc}]_{suffix<mu>}.{extension<txt|json>|txt}",

qsirecon/data/nonscalars/dsistudio_autotrack.yaml

@@ -26,7 +26,7 @@ scalarstats:
 
 fibgz:
     bids:
-        space: T1w
+        space: ACPC|T1w
         suffix: dwimap
         extension: fib.gz
     metadata:
@@ -36,8 +36,8 @@ fibgz:
 
 mapping:
     bids:
-        space: T1w
-        suffix: mapping
+        space: ACPC|T1w
+        suffix: dwimap
         extension: map.gz
     metadata:
         Description: Mapping file produced by DSI Studio.

qsirecon/data/nonscalars/dsistudio_gqi.yaml

@@ -10,7 +10,7 @@ conmat:
 
 fibgz:
     bids:
-        space: T1w
+        space: ACPC|T1w
         suffix: dwimap
         extension: fib.gz
     metadata:
@@ -20,8 +20,8 @@ fibgz:
 
 mapping:
     bids:
-        space: T1w
-        suffix: mapping
+        space: ACPC|T1w
+        suffix: dwimap
         extension: map.gz
     metadata:
         Description: Mapping file produced by DSI Studio.

qsirecon/data/nonscalars/mrtrix_anat.yaml

@@ -2,7 +2,7 @@
 qsiprep_5tt_hsvs:
     bids:
         seg: hsvs
-        space: T1w
+        space: ACPC|T1w
         suffix: dseg
         extension: nii.gz
     metadata:
@@ -18,5 +18,5 @@ fs_5tt_hsvs:
         extension: nii.gz
     metadata:
         Description: |
-            Hybrid Surface/Voume Segmentation in MRtrix3 5tt format.
+            Hybrid Surface/Volume Segmentation in MRtrix3 5tt format.
             Aligned to the FreeSurfer ``orig.mgz`` image.

qsirecon/data/nonscalars/ss3t_fod_autotrack.yaml

@@ -0,0 +1,62 @@
+bundles:
+    bids:
+        suffix: streamlines
+        model: ss3t
+        extension: tck.gz
+    metadata:
+        Description: |
+            One tck.gz per bundle. The bundle represented by this file is
+            specified in the ``bundle-`` tag. Bundles were tracked using the
+            SS3t FODs.
+
+tdistats:
+    bids:
+        bundles: DSIStudio
+        suffix: tdistats
+        extension: tsv
+    metadata:
+        Description: Statistics on streamline density in voxels.
+
+scalarstats:
+    bids:
+        bundles: DSIStudio
+        suffix: scalarstats
+        extension: csv
+    metadata:
+        Description: |
+            Statistics on scalars produced by this workflow.
+
+gqi_fibgz:
+    bids:
+        space: ACPC|T1w
+        model: gqi
+        suffix: dwimap
+        extension: fib.gz
+    metadata:
+        Description: |
+            DSI Studio fib format containing the GQI ODFs used for
+            AutoTrack registration.
+
+fibgz:
+    bids:
+        space: ACPC|T1w
+        model: ss3t
+        suffix: dwimap
+        extension: fib.gz
+    metadata:
+        Description: |
+            DSI Studio fib format containing the SS3T FODs used for
+            AutoTrack.
+
+mapping:
+    bids:
+        space: ACPC|T1w
+        model: ss3t
+        suffix: dwimap
+        extension: map.gz
+    metadata:
+        Description: |
+            Mapping file produced by DSI Studio. Here the model entity
+            specifies ss3t so that DSI Studio associates the mapping
+            with the model-ss3t fib.gz file. Be aware that this mapping
+            was created using the model-gqi fib.gz file.