ENH: Resample BOLD data to any surface template space using the Connectome Workbench #3461
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #3461 +/- ##
==========================================
- Coverage 73.73% 72.98% -0.75%
==========================================
Files 60 60
Lines 4756 4813 +57
Branches 615 624 +9
==========================================
+ Hits 3507 3513 +6
- Misses 1108 1158 +50
- Partials 141 142 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@mgxd Thank you very much for taking care of this. Note that the final API of the smriprep PR (nipreps/smriprep#473) is different from the original one, particularly the part regarding TemplateFlow. I haven't examined if the code of this PR needs to be updated accordingly. |
|
Marking as draft to make quickly reviewing the PR list simpler. Please do not hesitate to mark ready for review when you think it's ready. |
|
While testing this locally with https://templateflow.s3.amazonaws.com/tpl-onavg/tpl-onavg_space-fsLR_hemi-L_den-10k_sphere.surf.gii |
|
@mgxd I think this is related to this issue: templateflow/tpl-onavg#1 |
| @article{onavg, | ||
| author = {Feilong, Ma and Jiahui, Guo and Gobbini, Maria Ida and Haxby, James V.}, | ||
| title = {A cortical surface template for human neuroscience}, | ||
| url = {https://www.nature.com/articles/s41592-024-02346-y}, |
There was a problem hiding this comment.
Does this need to be referenced anywhere? I don't see it in the boilerplate.
There was a problem hiding this comment.
Only when it's used in --output-spaces. Maybe the boilerplate hasn't been updated accordingly?
| return workflow | ||
|
|
||
|
|
||
| def init_wb_vol_surf_wf( |
There was a problem hiding this comment.
It looks like this is the first part of init_bold_fsLR_resampling_wf. Was the intent to factor that out so that it only needs to be run once when targeting multiple surface spaces?
There was a problem hiding this comment.
Exactly. We first resample the data to the subject's native space, then the native-space data can be resampled to multiple template spaces.
| resample_to_template = pe.Node( | ||
| MetricResample(method='ADAP_BARY_AREA', area_surfs=True), | ||
| name='resample_to_template', | ||
| mem_gb=1, | ||
| n_procs=omp_nthreads, | ||
| ) |
There was a problem hiding this comment.
Is there a reason not to pre- and post-mask, the same way fsLR does?
There was a problem hiding this comment.
Applying cortical mask at this step may cause missing data on surface.
There are several different existing cortical masks, and a vertex can be labeled as cortical by one and non-cortical by another. If the fsLR/HCP cortical mask is applied to data at this step, there will be missing values in data when we use other masks later. I'm inclined to keep all vertices, and the user can decide which cortical mask to use during the analysis.
|
|
||
| if name is None: | ||
| name = f'wb_surf_native_{template}_{density}_wf' | ||
| workflow = Workflow(name=name) |
There was a problem hiding this comment.
@mgxd If we need to trigger the citation, it would probably be by adding a workflow__desc__ here.
There was a problem hiding this comment.
yeah, we'll need to do something similar to
|
@mgxd Just a ping on those last couple comments, and did you have a chance to look for the citation in your outputs? |
…ectome workbench.
…nd init_wb_surf_surf_wf.
for more information, see https://pre-commit.ci
Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Chris Markiewicz <effigies@gmail.com>
25.2.0 (October 01, 2025) New feature release in the 25.2.x series. This release is an *fMRIPrep Long-Term Support (LTS)* release. The planned support window is 4 years, until October 2029. This release is an incremental improvement over 25.1.x, but includes some fixes and improvements that do not fit within our `bug-fix policy <https://www.nipreps.org/devs/releases/#bug-fix-releases>`__. Importantly, the change in interpolation in 25.1.0 introduced artifacts for some datasets. This release changes the default interpolation mode to ``grid-constant``, which resolves those problems while not reintroducing the issue the previous release sought to fix. This release also (finally) introduces per-session processing. The ``--session-label`` flag selects the sessions to process, and the ``--subject-anatomical-reference`` flag indicates whether and how to combine across sessions. Existing filters passed via ``--bids-filter-file`` may need to be updated or removed in favor of using these flags to achieve the desired behavior. We would like to thank the AMP-SCZ and ENIGMA consortia for testing out and providing feedback on this release. * FIX: Clean up output report language (#3529) * FIX: Default to grid-constant interpolation mode (#3516) * FIX: Adapt to transposed ndcoords in nitransforms (#3517) * FIX: Write out Freesurfer-derived outputs (#3512) * FIX: Add kwargs to _warnings.py (#3483) * ENH: Resample BOLD data to any surface template space using the Connectome Workbench (#3461) * ENH: Add boldref / sbref to source metadata (#3532) * ENH: Add dedicated session filtering, alternative anatomical template options (#3495) * ENH: Write out goodvoxels mask (#3513) * ENH: Add registration metadata to boldref-to-anat transforms (#3500) * ENH: Write out cortex mask GIFTIs (#3491) * ENH: Update transforms.py according to new transform chain of nitransforms (#3494) * RF/DOC: Improve and document command-line parser defaults (#3487) * DOC: Explain better SDC and B0FieldSource requirement (#2768) * DOC: Document `freesurfer` parameter in BOLD confound workflow init (#3504) * DOC: Add myself to contributor list (#3506) * DOC: Fix non-standard Input/Output docstring section management (#3505) * MNT: Split Dockerfile into base and pixi layers (#3521) * MNT: Replace conda with pixi and lock (#3503) * MNT: Update license metadata using SPDX expression (#3486) * MNT: no need to re-run `ruff check` after `ruff format` (#3480) * MNT: Update pre-commit ruff legacy alias (#3479)
…rface (#3544) Follow up on #3461 to include template information <details> <summary>Sampler boilerplate text</summary> The BOLD time-series were resampled onto the left/right-symmetric template “fsLR” using the Connectome Workbench (Glasser et al. 2013). The BOLD time-series were resampled onto the native surface of the subject using the “ribbon-constrained” method and then dilated by 10 mm.Grayordinates files (Glasser et al. 2013) containing 91k samples were also generated with surface data transformed directly to fsLR space and subcortical data transformed to 2 mm resolution MNI152NLin6Asym space. The BOLD series was resampled to OpenNeuro Average (onavg) surface template [Feilong et al. (2024); TemplateFlow ID: onavg] using the Connectome Workbench. All resamplings can be performed with a single interpolation step by composing all the pertinent transformations (i.e. head-motion transform matrices, susceptibility distortion correction when available, and co-registrations to anatomical and output spaces). Gridded (volumetric) resamplings were performed using nitransforms, configured with cubic B-spline interpolation. Non-gridded (surface) resamplings were performed using the Connectome Workbench.Grayordinate “dscalar” files containing 91k samples were resampled onto fsLR using the Connectome Workbench (Glasser et al. 2013). </details>
3 participants
Changes proposed in this pull request
Currently in fMRIPrep the Connectome Workbench is used to resample BOLD data to fsLR spaces, as part of the CIFTI workflow.
This PR allows resampling BOLD data to any surface template space with a similar workflow, as long as (a) the "space-fsLR" spheres exist for the template (e.g., "tpl-onavg_space-fsLR_hemi-R_den-41k_sphere.surf.gii") or (b) the template is "fsLR".
In the long run, we might want to generate alternative generic workflows, e.g., (a) using the SurfaceTransform class of nitransforms by @Shotgunosine and me, and (b) using FreeSurfer's resampling workflow.
This PR depends on a recent PR of smriprep and updating TemplateFlow's files on AWS S3.
Currently the wrong subfolder on S3 was updated for some unknown reason.
This generic resampling workflow might serve as the first step for the generic CIFTI workflow.
Documentation that should be reviewed
I've updated the workflows' docstrings accordingly, but feel free to make suggestions/edits.
@effigies @oesteban