Skip to content

Add external regressor and task analysis pages - #101

Merged
tsalo merged 1 commit into
mainfrom
external-regressors-and-task-analysis
Nov 15, 2026
Merged

tsalo merged 1 commit into
mainfrom
external-regressors-and-task-analysis

Conversation

@tsalo

@tsalo tsalo commented Nov 15, 2026

Copy link
Copy Markdown
Member

Closes #94. Closes #71.

Changes

Two new executed pages, both using the localizerDetection run of DIVA (ds002278), sub-Blossom, ses-02:

  • 09_External_Regressors.md (Add examples of external regressors for tedana decision trees #94) builds each of the four kinds of external regressors from the issue and uses them in a tedana decision tree.
    • Physiological: RETROICOR (cardiac and respiratory), respiration variation convolved with the Birn et al. (2008) response function, and heart rate convolved with the Chang et al. (2009) response function.
    • ROI time series: the lateral ventricles, M1 (the right hand knob, since the participant tapped with the left hand), A1 and V1. These are warped from MNI to run space with nitransforms and the fMRIPrep transforms, then averaged over the optimally combined data.
    • fMRIPrep confounds: the six motion parameters and their derivatives.
    • Task: motor, auditory and visual are modeled separately, so a motor/auditory block counts toward both.
    • The tree: adapted from tedana's demo external-regressor tree, with an added physio partial model. The baseline is the same tree with the external-regressor nodes removed, and both runs share one ICA, so any difference comes from the external regressors alone. Comparing against minimal instead flipped components for unrelated reasons.
  • 10_Task_Analysis.md (Incorporate task analysis #71) fits the same GLM to four versions of the data: echo 2, the optimal combination, the optimal combination with the rejected components in the design, and the tedana-denoised data.
    • It compares the maps and the z-statistics in each ROI.
    • It uses the motor - visual and visual - motor contrasts, because every block is one or the other.
  • book_utils.load_diva(), the DIVA section of 00_Download_Data.md, three references and the TOC entries.

Notes for reviewers

  • Dataset for Incorporate task analysis #71: Incorporate task analysis #71 suggests ds007661. I used the same DIVA run as Add examples of external regressors for tedana decision trees #94 instead, so both pages share one dataset and the task page can reuse the ROIs and tedana outputs.
  • The derivatives are not public yet. They come from a development version of fMRIPrep 25.2 run with --me-output-echos. For now, 00_Download_Data.md tells readers to run fMRIPrep on sub-Blossom themselves.
  • The physio StartTime has the wrong sign. The sidecar says +9.0 s, but the trigger channel is high for exactly 300 × 1.5 s, starting 9.065 s into the recording. The page derives the offset from the trigger.
  • The ECG has a gradient artifact at about 10.7 Hz plus harmonics. It is band-passed at 0.5–8 Hz before R-peak detection.
  • Why sub-Blossom: sub-Bubbles had a weak V1 response, and sub-Buttercup's ECG is swamped by the gradient artifact.
  • The atlases are in a different space. The nilearn atlases are in MNI152NLin6Asym, while the fMRIPrep transform is from MNI152NLin2009cAsym. The page notes this mismatch.
  • CI cache: the new pages execute in about 35 and 7 minutes. CI will render them only after the local execution cache is uploaded with make publish-cache, which I have not done yet.

Testing

  • make book builds with no warnings.
  • make check-cache reports 22 of 22 notebooks cached.

🤖 Generated with Claude Code

Add two pages that use the localizerDetection run of DIVA (ds002278) sub-Blossom:

- 09_External_Regressors: build physiological (RETROICOR, RV, HR), ROI
  (ventricles, M1, A1, V1 warped from MNI with nitransforms), motion and
  task regressors, and use them in a tedana decision tree. The baseline
  is the same tree without the external-regressor nodes, on a shared ICA.
- 10_Task_Analysis: fit the same GLM to echo 2, the optimal combination,
  the optimal combination with rejected components in the design, and the
  denoised data.

Also add load_diva() to book_utils, the DIVA download instructions, the
new references and the table of contents entries.
@tsalo
tsalo merged commit 414983b into main Nov 15, 2026
4 checks passed
@tsalo
tsalo deleted the external-regressors-and-task-analysis branch November 15, 2026 13:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add examples of external regressors for tedana decision trees Incorporate task analysis

1 participant