Split into separate fit & apply workflows

[effigies]

Relevant issues:

• fmriprep --minimal mode #2806
• fmriprep-apply CLI tool #2805

smriprep implementation: nipreps/smriprep#303

[effigies]

Below are the notes that came out of our discussions at the brainhack (originally compiled at https://hackmd.io/@effigies/fmriprep-fit). Thank you for the discussions, @feilong @HippocampusGirl @mgxd @oesteban.

Minimal derivatives

sub-X/func/sub-X_task-Y_run-Z_desc-hmc_boldref.nii.gz  # BOLD contrast
sub-X/func/sub-X_task-Y_run-Z_desc-coreg_boldref.nii.gz  # aligned to hmcref, use sbref and fieldmaps, if possible
sub-X/func/sub-X_task-Y_run-Z_from-orig_to-boldref_mode-image_xfm.txt
sub-X/func/sub-X_task-Y_run-Z_from-boldref_to-T1w_mode-image_xfm.txt
sub-X/func/sub-X_task-Y_run-Z_from-T1w_to-boldref_mode-image_xfm.txt
sub-X/func/sub-X_task-Y_run-Z_from-fmap_to-boldref_mode-image_xfm.txt  # MI metric

Dependency structure

graph TB;
    bold.nii --> desc-hmc_boldref.nii;
    desc-hmc_boldref.nii-->from-orig_to-boldref_xfm.txt;
    desc-hmc_boldref.nii-->from-fmap_to-boldref_xfm.txt;
    sbref.nii--->from-coreg_boldref.nii;
    desc-hmc_boldref.nii-->from-coreg_boldref.nii;
    from-coreg_boldref.nii-->from-boldref_to-T1w_xfm.txt;

Application notes

graph TD;
    bold.nii -- slice-timing correction --> desc-stc_bold.nii;
    desc-stc_bold.nii -- split -->  idx-*_desc-stc_bold.nii;
    space-boldref_bold.nii --> desc-confounds_timeseries.tsv;
    idx-*_desc-stc_bold.nii -- resample and merge -->
    space-boldref_bold.nii & space-*_bold.nii & hemi-L_space-fsnative_bold.func.gii & hemi-R_space-fsnative_bold.func.gii;
    space-*_bold.nii -- select space-MNI152NLin6Asym ---> space-fsLR_bold.dtseries.nii;
    hemi-L_space-fsnative_bold.func.gii -- resample --> hemi-L_space-fsLR_bold.func.gii;
    hemi-R_space-fsnative_bold.func.gii -- resample --> hemi-R_space-fsLR_bold.func.gii;
    hemi-L_space-fsLR_bold.func.gii & hemi-R_space-fsLR_bold.func.gii
    --> space-fsLR_bold.dtseries.nii;

Single-shot surface resampling changes

• Resample coordinates into boldref (Take GIFTIs in T1w space, apply T1w->boldref ITK transform (via nitransforms) to get surfaces in each boldref space.)
  • In:
    • GIFTI in T1w space (output of smriprep)
    • from-T1w_to-boldref_xfm
  • Out:
    • GIFTI surface in boldref
• Resample fieldmap in Hz to surface
  • In:
    • Fieldmap to boldref transform
    • GIFTI in boldref
  • Out:
    • Fieldmap (in Hz) on surface
• Resample BOLD with SDC+HMC onto surface
  • Inputs:
    • BOLD (STC if done)
    • GIFTIs in boldref
    • HMC transforms
    • Fieldmap on surface
    • Optional: weight values from -volume-to-surface-mapping
    • Optional: goodvoxels mask
  • Output
    • fsnative BOLD

[HippocampusGirl]

Please see here some example weight files from -volume-to-surface-mapping. It looks like a list of voxel index and weight for each vertex, so parsing/applying it should be relatively straightforward. What do you think @feilong @effigies?

_hemi_R_volume_to_surface_output_weights.txt
_hemi_L_volume_to_surface_output_weights.txt

[effigies]

Yes, that looks very straightforward. We should test to make sure we get the same result to within reasonable precision. Would you mind pushing a branch with your patch?

[feilong]

Each line seems to be:

• vertex index
• number of "good" voxels
• (for each voxel) ijk indices (int) and weight (float)

What puzzles me a bit is that the sum of the weights don't add up to one. Other parts look quite straightforward to me, too.

[HippocampusGirl]

I've uploaded the code at https://github.com/HippocampusGirl/fmriprep/tree/output-weights-text. It's not really ready for a PR yet, because I guess we wouldn't want to do this with the real data in --minimal mode, but just an empty image, or am I overthinking things?

[effigies]

Right we won't use it this way in the long run, but this is totally fine for getting an output that we can test on.

[effigies]

@feilong What is the minimal set of surfaces we need for resampling? I'll skip inflated, but I suppose we still want sphere.reg, white, midthickness and pial?

[feilong]

@effigies Yes. Definitely sphere.reg, and also white, midthickness and pial for the ribbon-based resampling method.

If the original sphere is available, I'll include it, too. I was reading the code of HCPpipelines, and they use sphere and sphere.reg to create a rotated sphere.rot to initialize MSM.

[effigies]

This is done.