AlphaMap — Analysis Pipeline

Reproducible analysis pipeline for the study:

Jiricek et al. Resting-state EEG alpha-BOLD coupling spatially follows cortical transcriptomic gradients of cell types and receptors. Currently under review (2026).

An earlier version is available as a preprint, under its original title:

Resting-state EEG alpha-BOLD coupling spatially follows cortical cell-type and receptor gradients. https://doi.org/10.64898/2026.04.14.718407

---

Repository structure

AlphaMap/
├── config.py              ← Python configuration (all paths + parameters)
├── config.m               ← MATLAB mirror of config.py
│
├── data/                  ← Input data (tracked in git)
│   ├── alpha_map/         AlphaMMPareas.mat, AlphaMMPareas.txt
│   ├── cortical_maps/     AllMapsMMP.mat  (82 maps × 180 HCP-MMP1 regions)
│   ├── hierarchy/         distMat180.mat, HCP-Multi-Modal-Parcellation-1.0.xml
│   ├── atlas/             HCP_MMP1_UniqueRegionList.csv, Yeo7_parcels_labeled.csv
│   ├── surrogates/        distanceMatMMP.txt + AlphaSurrogatesMMP_part{1,2}.mat (generated by Step 01, split for GitHub)
│   ├── pet/               receptors_MMP180_all19.csv + thumbs/ (precomputed, see below)
│   ├── gradient/          margulies_gradient_MMP180.csv (precomputed, see below)
│   └── controls/          surface renders used as row/column headers in Figure 3
│
├── pipeline/              ← Numbered scripts — run in order
│   ├── surrogates_01.py            ← Step 01: generate BrainSMASH surrogate maps
│   ├── statistics_02.m             ← Step 02: Spearman correlations + regression models
│   ├── figure2_plot_03.py          ← Step 03: Figure 2
│   ├── figure3_plot_05.py          ← Step 05: Figures 4 & 5
│   ├── partial_correlations_06.py  ← Step 06: specificity, partial correlations
│   ├── figure3_plot_07.py          ← Step 07: Figure 3
│   ├── moran_nulls_08.py           ← Step 08: second spatial null model
│   ├── figureS1_plot_09.py         ← Step 09: Figure S1
│   ├── dominance_10.py             ← Step 10: predictor importance
│   ├── pet_analysis_11.py          ← Step 11: PET receptor comparison
│   ├── figureS2_plot_12.py         ← Step 12: Figure S2
│   └── figureS3_plot_13.py         ← Step 13: Figure S3
│
├── tools/
│   └── fdr_bh.m           ← Benjamini-Hochberg FDR correction (MATLAB)
│
├── results/               ← All outputs (generated, not tracked)
│   ├── figures/           figure2_result1.png, figure3_gene.png, figure4_struct.png
│   ├── MultiRegression/   AlphaMultiRegression*.mat
│   └── RankDifferences/   AlphaRankDifferences.mat
│
└── workbench/             ← HCP Workbench binaries (not tracked — download once)

---

Prerequisites

Software

Package	Version	Install
Python	≥ 3.9	system / conda
MATLAB	≥ R2020b	—
HCP Workbench	1.5.0	download command below

Python packages

uv sync

---

After git clone — one-time setup

All input data is included in the repository. Only HCP Workbench needs to be downloaded separately.

Download HCP Workbench (Linux x86_64)

Download from humanconnectome.org/software/get-connectome-workbench or via command line:

cd path/to/AlphaMap
wget https://humanconnectome.org/storage/app/media/workbench/workbench-rh_linux64-v1.5.0.zip
unzip workbench-rh_linux64-v1.5.0.zip && rm workbench-rh_linux64-v1.5.0.zip

PATH is set automatically. All scripts call os.environ["PATH"] = config.WORKBENCH_BIN + ... at startup — no shell profile changes needed.

---

Pipeline — step by step

All commands from the project root.

Step 01 — Generate BrainSMASH surrogates

python pipeline/surrogates_01.py

• Generates 100,000 spatially autocorrelation-preserving surrogate maps.
• Skip logic: skips if the output file already exists.
• Output → data/surrogates/AlphaSurrogatesMMP.mat
• Runtime: ~2–4 h (first run); instant thereafter.

Step 02 — Statistical analysis (MATLAB)

run('pipeline/statistics_02.m')

• Spearman correlations between alpha-BOLD map and all 82 cortical maps.
• Surrogate p-values (two-sided), FDR (BH) and Bonferroni correction.
• Rank-difference computation for all 82 maps.
• Multiple linear regression — two models:
  • Gene model: FDR-significant maps (In3, GRIN2C, Ex5)
  • Structural model: T1/T2, cortical thickness, V1 geodesic distance
• Surrogate R² significance testing for both models.
• Outputs → results/RankDifferences/AlphaRankDifferences.mat, results/MultiRegression/AlphaMultiRegression*.mat

Step 03 — Figure 2

python pipeline/figure2_plot_03.py

• Panel A: Violin plots of surrogate distributions for top-10 maps.
• Panel B: P-value histogram across all 82 maps.
• Panel C: Scatter plots (alpha-BOLD vs top-5 significant maps, colour-coded by Yeo-7 network).
• Output → results/figures/figure2_result1.png ← Paper Figure 2

Step 05 — Figures 4 & 5

python pipeline/figure3_plot_05.py

• Figure 4: Gene maps (In3, GRIN2C, Ex5) — signed rank differences, bar charts, R² histogram, variograms.
• Figure 5: Structural maps (T1/T2, cortical thickness, V1 geodesic distance) — same layout.
• Outputs:
  • results/figures/figure3_gene.png ← Paper Figure 4
  • results/figures/figure4_struct.png ← Paper Figure 5

---

Revision analyses (Steps 06–13)

Added in response to peer review. Steps 06–13 depend only on Step 01, not on the MATLAB step, and can be run in the order given.

Step 06 — Specificity: partial correlations

python pipeline/partial_correlations_06.py

• Partial Spearman correlations of the significant maps with alpha-BOLD, controlling for the T1/T2 ratio, the principal FC gradient, and both jointly.
• Attenuation reported as 1 − (r_partial / r_raw)². These partials are descriptive; no significance is computed for them, matching the paper.
• Output → results/partial_correlations.csv

Step 07 — Figure 3

python pipeline/figure3_plot_07.py

• Heatmap of the raw and partial correlations with the attenuation per cell.
• Output → results/figures/figure3_specificity.png ← Paper Figure 3

Step 08 — Second spatial null model

python pipeline/moran_nulls_08.py

• Moran spectral randomization under both BrainSpace procedures, singleton and pair.
• Re-tests the three significant maps, and all 82 maps with the FDR correction repeated separately for each null.
• Surrogates cached in data/surrogates/ (not tracked; ~1 s to regenerate).
• Output → results/moran_all82.csv

Step 09 — Figure S1

python pipeline/figureS1_plot_09.py

• Observed correlation against all three null distributions, per significant map.
• Output → results/figures/figureS1_null_distributions.png ← Paper Figure S1

Step 10 — Predictor importance

python pipeline/dominance_10.py

• Univariate r² and general dominance weights for both regression models.
• Output → results/dominance.csv

Step 11 — PET receptor comparison

python pipeline/pet_analysis_11.py

• Gene expression against matched PET density (19 pairings across nine receptor systems), and alpha-BOLD against all 19 PET maps with FDR within the PET family.
• Outputs → results/pet_gene_vs_pet.csv, results/pet_alpha_vs_pet.csv

Step 12 — Figure S2

python pipeline/figureS2_plot_12.py

• Full gene × PET correlation matrix, matched pairs boxed.
• Output → results/figures/figureS2_gene_vs_pet.png ← Paper Figure S2

Step 13 — Figure S3

python pipeline/figureS3_plot_13.py

• Alpha-BOLD against each of the 19 PET maps, against the BrainSMASH null.
• Output → results/figures/figureS3_alpha_vs_pet.png ← Paper Figure S3

Precomputed inputs

Two files are shipped ready-made so that neither the PET parcellation nor the surface renders have to be repeated:

file	how it was produced
data/pet/receptors_MMP180_all19.csv	The 19 PET volumes of Hansen et al. (2022) parcellated to MMP-180 by nearest-label parcel averaging, matching the alpha-BOLD pipeline. Receptors imaged with several tracers (5HT1b, D2, mGluR5, VAChT) are combined as a sample-size-weighted mean of the z-scored parcellated maps, following Hansen's own make_receptor_matrix.py.
data/gradient/margulies_gradient_MMP180.csv	Principal resting-state FC gradient of Margulies et al. (2016), obtained through neuromaps and parcellated to the same 180 parcels by averaging vertex values within each parcel.

data/pet/thumbs/ and data/controls/ hold surface renders used as figure panels, so Steps 07, 12 and 13 build without HCP Workbench.

Note: Tested on Linux. HCP Workbench is also available for macOS and Windows — see humanconnectome.org/software/get-connectome-workbench.

---

How to cite

If you use this code, please cite:

Jiricek, S., Chien, V.S.C., Schmidt, H., Koudelka, V., Marecek, R., Mantini, D., & Hlinka, J. Resting-state EEG alpha-BOLD coupling spatially follows cortical transcriptomic gradients of cell types and receptors. Currently under review (2026).

Until it appears, please cite the preprint, which carries the original title:

Jiricek, S., Chien, V.S.C., Schmidt, H., Koudelka, V., Marecek, R., Mantini, D., & Hlinka, J. Resting-state EEG alpha-BOLD coupling spatially follows cortical cell-type and receptor gradients. https://doi.org/10.64898/2026.04.14.718407

---

Configuration

All paths and parameters live in config.py and its MATLAB mirror config.m. Edit those files to adapt to a new machine — no other script needs to change.

Key parameters:

Symbol	Value	Meaning
N_SURROGATES	100,000	BrainSMASH surrogate count
NH	50	Variogram distance bins
ALPHA_BF	0.05	Bonferroni threshold
ALPHA_FDR	0.05	FDR threshold
ALPHA_UNCORR	0.01	Uncorrected threshold

Both config files derive BASE_DIR from their own file location at runtime, so the pipeline works without editing after cloning.

---

License

Copyright © 2026, Institute of Computer Science of the Czech Academy of Sciences

This software is made available under the AGPL 3.0 license. For other licensing options, contact hlinka@cs.cas.cz or licensing@cs.cas.cz.