TotalReadoutTime - unwarp - fieldmap-less

Dear all,

Recently we have updated our fMRIPrep from version 20.2.1 to version 21.0.1 (to collaborate with another research team). I have applied the same pipeline/BIDS from the 20.2.1. version (which we ran successfully) to the 21.0.1 version but now get an error on the total read out time during unwarping.

Error: fmriprep_wf.single_subject_001x1_wf.func_preproc_ses_day01_task_sdi_wf.unwarp_wf.rotime ValueError: Unknown total-readout time specification

Attempts so far fixing it: creating a TotalReadoutTime value in the task/bold .json file. This solved the error. With a value for the TotalReadoutTime provided, the entire pipeline ran without any issues. Using --ignore fieldmaps without adding the TotalReadoutTime raised the same error.

Outstanding issue/question: I do not really understand why we do need this TotalReadoutTime this time while we could run fMRIprep successfully without this value in the previous fMRIPrep version we used. I read that is not a required (but recommended) field of the BIDS format and that it is used in the FSL top-up function. We only wish to use fieldmap-less as SDC. I have tried --ignore fieldmaps but this still raised the same issue. A somewhat complicating factor is that we have Philips Scans and no DICOM files, as I read (on other NeuroStars pages) that calculating the TotalReadoutTime in this manner is somewhat more challenging.

In case you have any thoughts on the cause/solutions I’d be happy hearing so! In case we only use SDC fieldmap-less, is a correct value for the TotalReadoutTime required (or could it also be just any value)?

Best regards and thanks in advance!

Welcome @acvdh to Neurostars! Thank you for your interesting question!

Regarding the behavior of FMRIPREP with respect to the use of the fildmap-less option, I encourage you to read this post: Using --use-syn-sdc with FieldMap Data - #2 by effigies?

I am not totally sure but I would guess that a correct value of the TotalReadoutTime is not strictly necessary when doing SDC with the field map-less approach. You can check the details of the field map-less implementation in the paper cited here :Question about Fieldmap-less distortion in QSIPrep

Thanks a lot for your reply! I read indeed on this that the TotalReadoutTime is required for all fieldmaps except fieldmap-less. That’s why I was surprised that the pipeline actually aborts when the value is not there (as we wish to only use the fieldmap-less). Via this page I now managed to calculate the TotalReadoutTime for our (Philips scans, in absence of DICOM files but with use of the scan sequence). I may run the pipeline two times with a different value for the TotalReadoutTime to see whether the output seems to be affected by it. I’ll also definitely have a look at the links you sent, thank you once more!

Nice! Did you launch your fmriprep command with --use-syn-sdc --ignore fieldmaps ?

This has actually changed as of fMRIPrep 21.0. What’s new is that we now combine the distortions estimated from multiple BOLD files to estimate a fieldmap, which we then apply. This can only be done if the total readout times (TRT) are the same, otherwise the susceptibility distortions induced in the BOLD series will be different and need to be estimated separately.

Note TRT can be directly encoded or we can calculate it from other metadata.

SyN-SDC uses the anatomical image to estimate a voxel displacement map, which we turn into a fieldmap estimate with fieldmap = displacment / TRT. When we apply, displacement = fieldmap * TRT, so the TRT can be anything non-zero without inducing distortion (outside floating point error).

Therefore, if you don’t know TRT, you can set TRT to encode your intention. Each (subject, TRT) combination will produce a single fieldmap that will correct matching BOLD files, so you can set multiple BOLD series to the same TRT if you want an average fieldmap, or different if you want a separate estimation per series.

I recognize this isn’t ideal from the perspective of only adding true metadata in your dataset. In the future, our preference in ambiguous situations will be to allow users to use sdcflows as a standalone tool to perform estimation and pass the pre-estimated fieldmaps as additional inputs to fMRIPRep.


Yes I have indeed! However if I use both --use-syn-sdc and --ignore fieldmaps but without the TRT (TotalReadoutTime) I still get the error - I think the next comment of effigies confirms that this indeed has changed as of version 21.0! Thanks a lot for thinking along!

Thank you very much for your extensive and informative reply! It helps a lot to know that this indeed has changed as of fMRIPrep version 21.0 and that the TRT may also be taken in account for the SyN-SDC - this confirms in fact all I wished to know! Thanks a lot!