Omni-synth: advice on how to feed outputs to fMRIPrep

[ajschadler]

In the spirit of a previous thread, I am exploring ways to preprocess an older fMRI dataset that does not contain any usable fieldmaps. In addition to SyN-SDC and synBOLD-DISCO (using two of @jsein’s suggestions: either synthetic+distorted BOLD as twin EPI inputs or using synbold-disco’s topup-generated fieldmap as input), I’d also like to test the omni pipeline. The end goal would be to use omni’s outputs in fMRIprep.

The main output from the omni-pipeline is a motion-corrected (3dAllineate using low DVARS volumes as base), distortion-corrected, and MNI152NLin2009cSym-aligned BOLD image. Using an already-processed input seems a bit redundant, plus I think I would need to calculate motion params from omni’s moco workflow.

As part of its processing steps, omni-synth calculates synthetic, undistorted EPI images, using info from T1w and T2w contrasts, at 4, 2, and 1mm resolutions. My naive thought is to take the 1mm synthetic image, rigid-body align and downsample to the distorted BOLD resolution, then use the synthetic and distorted BOLD images as twin-EPI inputs to fMRIprep, a-la SynBOLD-DISCO.

I am curious if anyone else has tried integrating omni-pipeline outputs with fMRIprep?

[ajschadler]

I ended up using omni to create SDC’ed “raw” bold scans, which were then used as fMRIprep input.

As part of its intermediate processing, omni will generate a warpfield that is used to unwarp a distorted BOLD image. Since omni normally outputs corrected data in template space, you can apply the warpfield to the raw data yourself.

<omni output folder>/
    sub-abcd/
        ses-abcd/
            func/
                sub-1_ses-1_task-mytask_bold/
                    ...
                    epi_proc_1_distortion_correction/
                        final_epi_to_synth_warp.nii.gz
                        ...
                   ...
                   func_proc_0_deoblique_func/
                       sub-abcd_ses-1_task-mytask_bold_deobliqued.nii.gz
                       ...
                   ...
                ...

For my project, I am using “deobliqued” intermediate data omni generates. However, with the exception of FOV, I have not seen appreciable visual changes when applying the warpfield to raw and “omni deobliqued” data. (using deobliqued anyway out of an “abundance of caution”)
The warpfield is applied using 3dNwarpApply. (recommended to copy raw data to a new “fakebids” directory and save unwarped BOLD to that, to leave raw data untouched)

OUTOMNI=""
FAKEBIDS=""
subid=""
sesid=""
taskname=""

funclab="sub-${subid}_ses-${sesid}_task-${taskname}_bold"
funcbase="$OUTOMNI/sub-${subid}/ses-${sesid}/func/$funclab/"
towarp="$funcbase/func_proc_0_deoblique_func/${funclab}_deobliqued.nii.gz"
outwarp="$FAKEBIDS/sub-${subid}/ses-${sesid}/func/${funclab}.nii.gz"
warpfield="$funcbase/epi_proc_1_distortion_correction/final_epi_to_synth_warp.nii.gz"

3dNwarpApply \
    -verbose \
    -overwrite \
    -source $towarp \
    -master $towarp \
    -prefix $outwarp \
    -nwarp $warpfield

[lelew]

Hi @ajschadler,

I am very interested in your approach, as I’m considering doing something similar. I am still quite naive to both the fMRIPrep and omni pipelines, but if I understand correctly:
you ran part of the omni pipeline to generate SDC’ed bold scans, and then used those new raw scans as inputs to fMRIPrep — effectively tricking its fieldmap-less correction by providing already unwarped data, instead of adding omni-derived synthetic fieldmaps into the BIDS with fake jsons so that fMRIPrep would treat them as actual fieldmaps. Is that correct?

Did you apply only specific omni functions to avoid redundant preprocessing, or did you run the full omni pipeline in a separate directory and simply replace the raw bold scans in the BIDS directory used by fMRIPrep?

I also noticed that you used the deobliqued data from omni. In that case, Do I need to update the bold json files to reflect the obliquity correction?

Finally, I don’t necessarily have SliceTiming, PhaseEncodingDirection and DwellTime for every scans. Omni’s documentation mentions these as required fields — did you need to provide all of them for your specific steps?

Thanks in advance!

[ajschadler]

@lelew

you ran part of the omni pipeline to generate SDC’ed bold scans, and then used those new raw scans as inputs to fMRIPrep — effectively tricking its fieldmap-less correction by providing already unwarped data, instead of adding omni-derived synthetic fieldmaps into the BIDS with fake jsons so that fMRIPrep would treat them as actual fieldmaps. Is that correct?

That is correct, I provided omni-corrected BOLD data as input and ran fMRIprep with --ignore fieldmaps (basically, running no fmap correction). For JSONs, I simply reused them from the raw BOLD.

@lelew

Did you apply only specific omni functions to avoid redundant preprocessing, or did you run the full omni pipeline in a separate directory and simply replace the raw bold scans in the BIDS directory used by fMRIPrep?

The latter. I like to keep raw-BIDS data untouched, instead I saved the omni-correct BOLD scans to a “fakebids” folder under derivatives; I copied the rest of the subject’s raw data to this “fakebids” directory. The “fakebids” directory is given as the “bidsdir” argument to fMRIprep.

(N.B. on a do-over, I’d just symlink relevant raw data to “fakebids”. Unfortunately, neither docker nor apptainer / singularity resolve symlinks in mounted folders, so you have to mount both the folder-with-symlinks and a full-path pointing to where your symlinked files live)

@lelew

I also noticed that you used the deobliqued data from omni. In that case, Do I need to update the bold json files to reflect the obliquity correction?

I’m honestly not sure on that part. My naive thought is that most tags won’t need to be adjusted. Also note: I didn’t find any appreciable difference when comparing the correction on omni-deobliqued and raw BOLD data (based on a single subject). If you had extra time, it might be interesting to see how using raw vs omni-deobliqued data affects downstream processing .

@lelew

Finally, I don’t necessarily have SliceTiming, PhaseEncodingDirection and DwellTime for every scans. Omni’s documentation mentions these as required fields — did you need to provide all of them for your specific steps?

If it helps, the only relevant tag I had was PhaseEncodingAxis, which I copied to PhaseEncodingDirection. If you have neither of these fields, you can either get it from your protocol or hazard a guess by looking at direction of distortions in the raw BOLD data.

[lelew]

Thank you so much for your quick answer!

In your final comparison, what’s your opinion of omni compared to other distortion correction strategies?

[lelew]

@ajschadler

That is correct, I provided omni-corrected BOLD data as input and ran fMRIprep with --ignore fieldmaps (basically, running no fmap correction). For JSONs, I simply reused them from the raw BOLD.

Did you also skip slice timing correction, coregistration or other steps that would have been performed twice with both omni and fmriprep? Or maybe, at least for coregistration, you did not use the coregsitered BOLD?

@ajschadler

(N.B. on a do-over, I’d just symlink relevant raw data to “fakebids”. Unfortunately, neither docker nor apptainer / singularity resolve symlinks in mounted folders, so you have to mount both the folder-with-symlinks and a full-path pointing to where your symlinked files live)

good to know, thanks!

@ajschadler

I’m honestly not sure on that part. My naive thought is that most tags won’t need to be adjusted. Also note: I didn’t find any appreciable difference when comparing the correction on omni-deobliqued and raw BOLD data (based on a single subject). If you had extra time, it might be interesting to see how using raw vs omni-deobliqued data affects downstream processing .

I’ll probably check this in further details

[ajschadler]

@lelew

In your final comparison, what’s your opinion of omni compared to other distortion correction strategies?

Based it off a quick visual comparison, but I preferred omni. Omni-synth had “better looking” brains with minimal smearing and fairly well-aligned gyri, corpus callosum, and ventricles. Though I did notice the cerebellum looked a little stretched / larger in some patients.

(Usual disclaimer that is solely for my data and you should test different methods on your own)

[ajschadler]

@lelew

Did you also skip slice timing correction, coregistration or other steps that would have been performed twice with both omni and fmriprep? Or maybe, at least for coregistration, you did not use the coregsitered BOLD?

I did run the full omni-synth pipeline, including all of the motion-correction, coregistration, etc. However, I only used the deobliqued-image as fMRIPrep input, meaning no moco / etc. was applied to it prior. Though … I’m now wondering if that might or might not be problematic …

[lelew]

@ajschadler

I did run the full omni-synth pipeline, including all of the motion-correction, coregistration, etc. However, I only used the deobliqued-image as fMRIPrep input, meaning no moco / etc. was applied to it prior. Though … I’m now wondering if that might or might not be problematic …

Is the _deobliqued only image is corrected for distortions? I feel there is no change in terms of distortions on my scan test…