Skip to content

Make the Cerebrovascular Reactivity Mapping page (ch06) execute on the tutorial data - #87

Merged
tsalo merged 5 commits into
ME-ICA:mainfrom
eurunuela:fix-cvr-ch06-build
Nov 14, 2026
Merged

tsalo merged 5 commits into
ME-ICA:mainfrom
eurunuela:fix-cvr-ch06-build

Conversation

@eurunuela

@eurunuela eurunuela commented Jun 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem

content/06_Cerebrovascular_Reactivity_Mapping.md could not execute: every code cell referred to files that are not in the repository (../optcom.nii.gz, ../co2.phys, a manual classification table, masks), and no CO2 recording ships with the tutorial data.

Fix

The first version of this PR turned the code cells into static code blocks. Following the review comment, the page now executes instead, using files the book already produces:

  • tedana outputs from the Denoising with tedana page (optimally combined data, adaptive mask, mixing matrix), with tedana's automatic classification in place of the manual one.
  • A gray matter ROI built from the fMRIPrep segmentation, resampled onto the BOLD grid with the boldref-to-T1w transform.
  • Motion parameters from the fMRIPrep confounds.
  • A simulated CO2 recording, since these data have none. The page says so prominently, and the resulting maps are labeled as illustrations of the outputs, not CVR measurements. This is a placeholder until a suitable public dataset is found.

Three phys2cvr variants run (CO2 recording with peak detection, pre-made PETCO2 trace, ROI-average signal). The task-design variant stays a static block, because the data contain no respiratory task.

Other changes:

  • pyproject.toml: pin numpy<2.4. peakdet 0.6.1 (the latest release) fails in peakfind_physio with numpy 2.4.
  • content/references.bib: remove three duplicated entries. They stopped the parser, so the Cohen2025RS citation on this page did not resolve.
  • _config.yml: the page is no longer excluded from execution.
  • The broken link to a rica page that does not exist now points to the rica web app.

Known limitations

  • The ROI-average call runs with lagged_regression=False. With a bulk shift of zero, phys2cvr (0.28.4, and current master) builds an empty set of lagged regressors and fails.
  • The page takes about 45 minutes to execute (two lagged regressions of about 20 minutes each).

Verification

The page executes in a local build and is in the published execution cache, so CI renders it from there. The rendered page shows the three figures, no tracebacks, and resolved citations.

🤖 Generated with Claude Code

Every code cell in 06_Cerebrovascular_Reactivity_Mapping.md referenced
files absent from the repo (manual_classification.tsv, optcom.nii.gz,
co2.phys, masks, ROI) plus a bare `raise ValueError("SKIP")`, so the
chapter could never execute during the build. Jupyter Book halts a
notebook at its first error, so only the manual_classification.tsv
FileNotFoundError surfaced.

Convert all {code-cell} ipython3 blocks to plain ```python blocks
(matching 08_ICA_Based_Denoising.md), making this an illustrative
tutorial the reader runs on their own data, and drop the SKIP hack.

Verified: ch06 no longer appears in _build/html/reports/content/ and the
book build exits 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings June 9, 2026 11:07

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR makes Chapter 06 (“Cerebrovascular Reactivity Mapping”) non-executable during the Jupyter Book build by converting MyST {code-cell} blocks into illustrative fenced python code blocks, removing the build-stopping execution failures caused by missing example data files.

Changes:

  • Replaced {code-cell} ipython3 blocks with plain fenced ```python blocks so the chapter renders as a runnable-on-your-own-data guide.
  • Removed the raise ValueError("SKIP") execution hack by eliminating notebook execution of the chapter’s code blocks.
Comments suppressed due to low confidence (1)

content/06_Cerebrovascular_Reactivity_Mapping.md:48

  • The fenced code block after the third bullet is no longer indented, so it will render outside the list item in Markdown/Jupyter Book. Also the example writes accecpted_ic_timeseries.csv, which is inconsistent with later references to accepted_ic_timeseries.csv and will cause a FileNotFoundError for readers following the tutorial.
```python
import pandas as pd

# Assuming RICA was used for manual classification, read the downloaded file (adjusting path as necessary)
man_class = pd.read_csv('../manual_classification.tsv', sep='\t', header=0)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…as example

- The pandas example saved to '../accecpted_ic_timeseries.csv' (typo) while
  the phys2cvr calls read '../accepted_ic_timeseries.csv' — a reader following
  the tutorial would hit FileNotFoundError. Match the spelling.
- Indent the first code block so it renders inside the list item that
  introduces it (it was at column 0, rendering outside the list). Verified it
  parses as a fenced python block nested in the list item.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@eurunuela

Copy link
Copy Markdown
Contributor Author

Addressed the Copilot review feedback on the first code block (909b752):

  • Typo fixed — the example saved to accecpted_ic_timeseries.csv but the later phys2cvr calls read accepted_ic_timeseries.csv, so a reader following the tutorial would hit FileNotFoundError. Corrected the spelling so the saved and consumed filenames match.
  • Indentation — indented the block so it renders inside the bullet list item that introduces it (it was at column 0). Verified it parses as a fenced python block nested in the list item.

Both were pre-existing in the chapter; folded them in here since the reviewer flagged them on the block this PR touches.

@eurunuela
eurunuela requested a review from tsalo June 9, 2026 13:08
@eurunuela

Copy link
Copy Markdown
Contributor Author

This may be a me issue @tsalo @smoia . Feel free to close it if you can't reproduce the issue.

@smoia

smoia commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

No, sorry, I was about to write that it's a me issue as well now. I thought I copied another page example more closely, but probably I inserted some mistakes.

Is there any action item I need to take care of?

@tsalo

tsalo commented Jun 9, 2026

Copy link
Copy Markdown
Member

I was planning to work my way through this page and fix any missing paths, rather than disable the code cells. It may rely on files generated by the tedana workflow page (except for the manual classifications, which will need to be swapped out for the automatic ones from tedana).

@eurunuela

Copy link
Copy Markdown
Contributor Author

I don't have the bandwidth to fix the missing paths. This happens to be what I did to be able to build the book locally and I thought I'd open this to flag it. Again, feel free to work on it or close it.

@smoia

smoia commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

We'd also need a CO2 generated for and from peakdet. Is the automatically generated table from tedana the same as rica's?

One thing we can try in the next days speaking with César is if we can use an extract of the data from EuskalIBUR for this purpose (like a half or a quarter of brain of a subject), if you can accept more data.

The page executes again instead of showing static code. It builds its inputs
from the tedana tutorial outputs (automatic classification), a gray matter ROI
from the fMRIPrep segmentation, and a simulated CO2 recording, which stands in
until a public dataset with a real recording is available.

Pin numpy below 2.4, since peakdet 0.6.1 fails to find peaks with it, and
remove three duplicated entries from references.bib, which stopped the parser
before the entries that follow them.
@tsalo tsalo changed the title Fix Cerebrovascular Reactivity Mapping (ch06) build: make it illustrative Make the Cerebrovascular Reactivity Mapping page (ch06) execute on the tutorial data Nov 14, 2026
@tsalo
tsalo merged commit a4933aa into ME-ICA:main Nov 14, 2026
2 checks passed
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.

4 participants