Fix pySPFM notebook: switch to Schaefer atlas, fix memory and path issues

[eurunuela]

Summary

• Switches the pySPFM deconvolution notebook from voxel-wise processing (~218k voxels) to parcel-wise processing using the Schaefer 1000-parcel atlas, making the notebook runnable on a laptop without running out of memory
• Fixes ../DATA → ../data (case-sensitive path, was silently broken on Linux/CI)
• Removes the dead n_jobs=-1 argument (pySPFM v2.0.1 hardcoded scheduler="synchronous" — a fix has been opened upstream at Wire n_jobs to Dask threaded scheduler in all voxel-wise solvers Paradigm-Free-Mapping/pySPFM#152)
• Includes executed .ipynb output so the book build can use the cache

Why parcel-wise?

Running pySPFM voxel-wise on the full brain mask builds a Dask graph with ~218k delayed objects, holds all results in memory simultaneously, then allocates ~2.6 GB each for the fitted signal and residuals. On a 16 GB machine already under memory pressure this reliably kills the Jupyter kernel.

Using NiftiLabelsMasker with the Schaefer 1000-parcel atlas reduces the input matrix from (1815, 218485) to (1815, 1000) — ~14 MB vs ~1.6 GB. The full multi-echo deconvolution workflow is still demonstrated across the whole brain.

Test plan

• Notebook executes locally without kernel dying (jupyter execute content/05_3dMEPFM.ipynb)
• All four output files written: out_activity.nii.gz, out_lambda.npy, out_fitted.npy, out_residuals.npy
• jb build . passes in CI

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the pySPFM deconvolution tutorial to run in a parcel-wise workflow (Schaefer 1000 atlas) to reduce memory usage, fixes a case-sensitive data path, and adds an .ipynb version of the notebook for builds/caching.

Changes:

• Switch notebook deconvolution from voxel-wise to parcel-wise using NiftiLabelsMasker + Schaefer 2018 (1000 ROIs).
• Update ../DATA to ../data for Linux/CI compatibility.
• Add content/05_3dMEPFM.ipynb counterpart to the existing MyST/Jupytext .md notebook.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
content/05_3dMEPFM.md	Refactors the workflow to Schaefer-parcel time series and uses SparseDeconvolution; updates data path and output-writing logic.
content/05_3dMEPFM.ipynb	Adds an .ipynb version of the same tutorial content for execution/build purposes.

---

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

[handwerkerd]

I'm seeing two possibly related issues:

1. The new atlas is being downloaded to the top of my user directory tree (i.e. /Users/handwerkerd/nilearn_data) and not a gitignored directory in this repo. This might cause problems in some systems & is a bit annoying.
2. The script crashed on build during the third cell (maybe due to issues with the file path). This also seems like a file path issue.

---------------------------------------------------------------------------
IndexError                                Traceback (most recent call last)
Cell In[3], line 15
     11     labels_img=atlas.maps,
     12     resampling_target='data',
     13     standardize=False,
     14 )
---> 15 masker.fit(data_files[0])
     16 
     17 # Load each echo and extract parcel-averaged timeseries, then concatenate
     18 # along the time axis to form the multi-echo input matrix.

IndexError: list index out of range

[eurunuela]

I'm working on improving the notebook regardless. This is still not ready to be merged.