QSIRecon: construct connectivity matrices based on a custom atlas for each individual

Hi developers,

I would like to construct connectivity matrices based on a custom atlas (i.e. MUSE segmentation) for each individual. Every subject has his/her own MUSE segmentation file, like FreeSurfer’s aparc+aseg.mgz, e.g.

sub-CND0012_ses-001_desc-preproc_T1w_DLMUSE.nii.gz

How can I incorporate this custom atlas into the reconstruction workflow for each individual? Can you show me the steps?

## Reconstruction
apptainer run \
--containall \
--writable-tmpfs \
-B $WORKPATH/:/scratch \
-B $PREPOUTPATH:/prep_out \
-B $RECONOUTPATH:/recon_out \
-B $FSPATH:/fs_out \
-B $FSLICENSE:/fs_license:ro \
~/Software/singularity_images/qsirecon-26.0.0.sif \
/prep_out /recon_out participant \
--fs-license-file /fs_license \
--participant-label $SUB \
--nthreads $CPUS \
--fs-subjects-dir /fs_out \
--recon-spec ss3t_fod_autotrack \
--atlases <custom_atlas> \
-w /scratch \
-v -v

On the other hand, I have already processed 1262 DTI scans using the QSIPrep and QSIRecon, without constructing the connectivity matrices. Will this additional step (constructing connectivity matrices) start from scratch? Or will it build on the existing reconstructed files from QSIRecon?

Thanks for your advice in advance.

Best,

Angel

Hi @angelwong,

You are going to want to update 26.0.1 to make connectivity matrices (Release 26.0.1 · PennLINC/qsirecon · GitHub).

You may find this post helpful: QSIRecon Custom Atlas and Response Functions - #3 by tsalo

If you’ve only run ss3t_auto_track, then you will still need to generate whole-brain tractograms. The only thing that could be reused are the response functions / FODs. I forget if they are reused or rather regenerated in each run. I think you would need to have a same-name recon spec and same working directory for a chance to reuse those response functions / FODs. But the whole brain tractogram is much more time consuming anyway, so the time save won’t be too much, maybe ~1 hour per scan.

Best,
Steven

Hi @Steven,

Thanks for your prompt reply. I did follow the suggested steps and test for 1 subject as follows:

atlases/
├── atlas-CND0012001muse   # 1 atlas directory for each subject
│   ├── atlas-CND0012001muse_dseg.nii.gz   # original muse segmentation file in T1 native space
│   ├── atlas-CND0012001muse_dseg.tsv
│   ├── atlas-CND0012001muse_space-MNI152NLin2009cAsym_dseg.json
│   └── atlas-CND0012001muse_space-MNI152NLin2009cAsym_dseg.nii.gz   # muse segmentation file in MNI space
└── dataset_description.json

Inside the dataset_description.json, I put something like this:

{
    "Name": "MUSE",
    "BIDSVersion": "1.1.1",
    "DatasetType": "atlas"
}

Inside the atlas-CND0012001muse_dseg.tsv, I put something like this:

index   name    roi_resolution
4       3rd Ventricle   Single
11      4th Ventricle   Single
23      Right Accumbens Area    Single
30      Left Accumbens Area     Single
31      Right Amygdala  Single
32      Left Amygdala   Single
...

Inside the atlas-CND0012001muse_space-MNI152NLin2009cAsym_dseg.json, I put something like this:

{
  "SpatialReference": {
    "VolumeReferenceSpace": "MNI152NLin2009cAsym"
  }
}

Then, the command liked this:

## Reconstruction
apptainer run \
--containall \
--writable-tmpfs \
-B $WORKPATH/:/scratch \
-B $PREPOUTPATH:/prep_out \
-B $RECONOUTPATH:/recon_out \
-B $ATLASPATH:/atlas \
-B $FSLICENSE:/fs_license:ro \
/beegfs/share/neuroimaging/Software/singularity_images/qsirecon-26.0.1.sif \
/prep_out /recon_out participant \
--fs-license-file /fs_license \
--participant-label $SUB \
--nthreads $CPUS \
--recon-spec ss3t_fod_autotrack \
--datasets ${SUB}001muse=/atlas \
--atlases ${SUB}001muse \
-w /scratch \
-v -v

But I received the following error messages:

261013-19:32:06,451 nipype.interface WARNING:
         No atlas images found for CND0012001muse with query {'template': 'MNI152NLin2009cAsym', 'suffix': 'dseg', 'extension': ['.nii.gz', '.nii']}
WARNING:nipype.interface:No atlas images found for CND0012001muse with query {'template': 'MNI152NLin2009cAsym', 'suffix': 'dseg', 'extension': ['.nii.gz', '.nii']}
Process Process-2:
Traceback (most recent call last):
  File "/app/.pixi/envs/qsirecon/lib/python3.10/multiprocessing/process.py", line 314, in _bootstrap
    self.run()
  File "/app/.pixi/envs/qsirecon/lib/python3.10/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/app/.pixi/envs/qsirecon/lib/python3.10/site-packages/qsirecon/cli/workflow.py", line 132, in build_workflow
    retval['workflow'] = init_qsirecon_wf()
  File "/app/.pixi/envs/qsirecon/lib/python3.10/site-packages/qsirecon/workflows/base.py", line 42, in init_qsirecon_wf
    single_subject_wf = init_single_subject_recon_wf(subject_id=subject_id)
  File "/app/.pixi/envs/qsirecon/lib/python3.10/site-packages/qsirecon/workflows/base.py", line 198, in init_single_subject_recon_wf
    atlas_configs = collect_atlases(
  File "/app/.pixi/envs/qsirecon/lib/python3.10/site-packages/qsirecon/utils/atlases.py", line 136, in collect_atlases
    raise ValueError(f'Errors found in atlas collection:\n\t{error_str}')
ValueError: Errors found in atlas collection:
        No atlas images found for CND0012001muse with query {'template': 'MNI152NLin2009cAsym', 'suffix': 'dseg', 'extension': ['.nii.gz', '.nii']}

Which step(s) went wrong?

Thanks for your advice in advnace.

Best,
Angel

this reads like a layout indexing problem rather than a tractography one. collect_atlases just trusts the pybids query, so if that returns zero files the run dies even when the dseg is sitting right there. i would check three things in order: the expanded label string is identical across --datasets, --atlases, and the atlas- folder name; the path given to --datasets is the dataset root (dataset_description.json and the atlas folder side by side), not the atlas folder itself; and the filename parses as space-MNI152NLin2009cAsym_dseg with nothing extra in between. quickest test is building a BIDSLayout on the atlas root and running the same query standalone, that tells you straight away whether its filename parsing, a .bidsignore, or the sidecar. i wrote up the full check sequence here: https://vectle.com/skills/skl_TcoQhfFrQ6wdQNBQf1P_Kg

Hi @angelwong,

Apologies, the guidance from the other post is outdated. We have since updated the software to use the OFFICIAL BIDS atlas spec which you may find here: Templates and atlases - Brain Imaging Data Structure 1.11.2

Perhaps you can try:

${SUB}001muse/
    atlas-${SUB}001muse_description.json
    tpl-MNI152NLin2009cAsym/
       anat/
           tpl-MNI152NLin2009cAsym_atlas-${SUB}001muse_dseg.nii.gz
           tpl-MNI152NLin2009cAsym_atlas-${SUB}001muse_dseg.tsv
           tpl-MNI152NLin2009cAsym_atlas-${SUB}001muse_dseg.json
           tpl-MNI152NLin2009cAsym_atlas-${SUB}001muse_dseg.nii.gz

And pass in the full path to the ${SUB}001muse folder as the atlas dir.

Also, a reminder that the built in ss3t_fod_autotrack recon spec will not perform any wholebrain tractography or connectivity matrices.

Best,
Steven

Hi @Steven and @gregvectle,

Thanks for your prompt reply. Unfortunately, it still didn’t work. I changed the data structure for the atlas like this:

cd /beegfs/share/neuroimaging/Data/longitudinal/derivatives/qsirecon-26.0.1
tree atlases/
atlases/
├── CND0012001muse
│   ├── atlas-CND0012001muse_description.json
│   └── tpl-MNI152NLin2009cAsym
│       └── anat
│           ├── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.json
│           ├── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.nii.gz
│           └── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.tsv
└── dataset_description.json   # must present; otherwise it prompts error

These are the paths, and I entered an interactive terminal session inside the container:

WORKPATH='/beegfs/userhome/angelwong/Data/scratch'  # send intermediate files to scratch folder
BIDSPATH='/beegfs/share/neuroimaging/Data/longitudinal/bids/MRI'
PREPOUTPATH='/beegfs/share/neuroimaging/Data/longitudinal/derivatives/qsiprep-26.0.0'
RECONOUTPATH='/beegfs/share/neuroimaging/Data/longitudinal/derivatives/qsirecon-26.0.1-2'
ATLASPATH='/beegfs/share/neuroimaging/Data/longitudinal/derivatives/qsirecon-26.0.1/atlases'
FSLICENSE='/beegfs/share/neuroimaging/Software/freesurfer/license.txt'

apptainer shell \
--containall \
--writable-tmpfs \
-B $WORKPATH/:/scratch \
-B $PREPOUTPATH:/prep_out \
-B $RECONOUTPATH:/recon_out \
-B $ATLASPATH:/atlas \
-B $FSLICENSE:/fs_license:ro \
/beegfs/share/neuroimaging/Software/singularity_images/qsirecon-26.0.1.sif

I tried to query the atlas files in python:

>>> from bids import BIDSLayout
>>> layout = BIDSLayout("/atlas")
>>> layout.get(suffix="dseg", extension=[".nii", ".nii.gz"])
[]

It returned nothing. What can I do?

Thanks,
Angel

Hi @angelwong, your atlas dir that you pass into QSIRecon should not include that overarching CND0012001muse folder.

Best,
Steven

Hi @Steven,

I figured out the correct data structure for the atlases:

atlases-muse
├── atlas-CND0012001muse_description.json
├── atlas-CND026E001muse_description.json
├── dataset_description.json
└── tpl-MNI152NLin2009cAsym
    ├── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.json
    ├── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.nii.gz
    ├── tpl-MNI152NLin2009cAsym_atlas-CND0012001muse_res-01_dseg.tsv
    ├── tpl-MNI152NLin2009cAsym_atlas-CND026E001muse_res-01_dseg.json
    ├── tpl-MNI152NLin2009cAsym_atlas-CND026E001muse_res-01_dseg.nii.gz
    ├── tpl-MNI152NLin2009cAsym_atlas-CND026E001muse_res-01_dseg.tsv

The command I used:

## Reconstruction
apptainer run \
--containall \
--writable-tmpfs \
-B $WORKPATH/:/scratch \
-B $PREPOUTPATH:/prep_out \
-B $RECONOUTPATH:/recon_out \
-B $ATLASPATH:/atlas \
-B $FSLICENSE:/fs_license:ro \
/beegfs/share/neuroimaging/Software/singularity_images/qsirecon-26.0.1.sif \
/prep_out /recon_out participant \
--fs-license-file /fs_license \
--participant-label $SUB \
--session-id $SES \
--nthreads $CPUS \
--recon-spec mrtrix_singleshell_ss3t_noACT \
--atlases ${SUB}${SES}muse \
--datasets ${SUB}${SES}muse=/atlas \
-w /scratch \
-v -v

The QSIRecon can now be run successfully.

Best,
Angel