README.md

Neuroimaging Pattern Masks — Documentation

This docs/ directory is the documentation hub for the canlab/Neuroimaging_Pattern_Masks repository. It indexes every study folder, links to per-folder documentation (contents_description.md), and explains how to load each map with the CANlab Core Tools.

GitHub renders this page automatically when you open the docs/ folder. The file is also compatible with GitHub Pages (Jekyll) — to enable a public site, turn on Pages with source docs/ in repository settings.

For the project-level overview, see the top-level README.

---

What is in this repository

The repository collects three kinds of brain maps, each with its own top-level landing page:

Type	Top-level folder	Landing page
Multivariate signatures — pre-trained predictive patterns	Multivariate_signature_patterns/	README
Atlases & parcellations — labeled regions / networks	Atlases_and_parcellations/	README
CANlab meta-analyses — consensus maps across studies	CANlab_Meta_analysis_maps/	README
Neurosynth maps	Neurosynth_maps/	README
Individual-study maps	Individual_study_maps/	README
Spatial basis functions — continuous gradients / ICA components	spatial_basis_functions/	README
Templates — reference T1 templates	templates/	README

A web companion with figures and references is hosted at the CANlab Brain Patterns site.

Loading maps

Most maps can be loaded by keyword through CanlabCore:

% Multivariate signatures (returns fmri_data + names)
[obj, networknames, imagenames] = load_image_set('siips');     % SIIPS1
[obj, networknames, imagenames] = load_image_set('npsplus');   % NPS, SIIPS, PINES, Rejection, VPS, GSR...
[obj, networknames, imagenames] = load_image_set('painsig');   % NPS + SIIPS only

% Atlases (returns atlas object)
atl = load_atlas('canlab2024');
atl = load_atlas('canlab2023');
atl = load_atlas('glasser_fmriprep20');
atl = load_atlas('schaefer400');

See load_image_set.m and load_atlas.m in CanlabCore for the full keyword list.

Applying signatures to new data

The repo ships two convenience wrappers at the root of Multivariate_signature_patterns/:

• apply_all_signatures.m — applies a configurable set of signatures (NPS, SIIPS, PINES, VPS, Rejection, GSR, HR, …) to a cell array of fmri_data objects and returns a results table. Supports similarity_metric (dot-product / cosine / correlation), image_scaling (none / center / z-score / l2-norm), and a named image_set to choose which signature bundle to apply. Example:

  [SIG, sigtable] = apply_all_signatures(DATA_OBJ, ...
      'similarity_metric', 'cosine_similarity', ...
      'image_scaling', 'l2norm_images', ...
      'image_set', 'npsplus');

• apply_siips.m — SIIPS1-specific wrapper that accepts wildcards, filename lists, or fmri_data objects and returns whole-signature responses plus local responses for each of the 44 FDR-thresholded SIIPS subregions.

Both helpers internally call CanlabCore's apply_mask / canlab_pattern_similarity, but they are easier to drop into a batch pipeline than wiring those up by hand.

Per-study documentation

Each study folder contains:

• A primary-reference PDF named <lastauthor>_<year>_<keywords>.pdf (where available).
• A contents_description.md that describes the folder (overview, key images, loading instructions, file inventory, citations).
• A visualize_contents.m MATLAB script that regenerates cortical-surface, isosurface (where relevant), and montage figures into png_images/.
• The image files themselves (NIfTI / atlas .mat objects / signature .mat objects).
• Any existing author-authored README.md is preserved verbatim and linked from contents_description.md.

Shared rendering helpers used by every per-folder script live in docs/:

• canlab_render_patterns.m — surface + montage + isosurface for fmri_data patterns.
• canlab_render_atlas.m — montage + isosurface for atlas objects.
• run_all_multivariate.m — batch-re-renders every folder in a chosen category.

---

Multivariate signatures — all entries documented

Year	Study	Topic
2011	Wager — Placebo prediction (J Neurosci)	Placebo response
2015	Chang — PINES (PLoS Biol)	Picture-induced negative affect
2015	Kragel — Emotion BPLS (SCAN)	7 emotion categories
2015	Woo — Romantic Rejection (Nat Comms)	Social rejection
2016	Eisenbarth — Autonomic GSR/HR (J Neurosci)	Skin conductance, heart rate
2016	Krishnan — VPS (eLife)	Vicarious pain
2017	Ashar — Care / Distress (Neuron)	Empathic care vs distress
2017	Rosenberg — saCPM (Nat Neurosci)	Sustained attention (connectome)
2017	Woo — SIIPS1 (Nat Comms)	Cerebral pain (beyond nociception)
2018	Kragel — MFC generalizability (Nat Neurosci)	Pain × emotion × cognitive control
2018	Reddan — Threat ImEx (Neuron)	CS+ vs CS− threat conditioning
2019	Kragel — Emotion Schemas (Sci Adv)	20 emotion categories
2019	Lee — Back pain (PAIN)	Chronic-back-pain markers
2019	Matthewson/Woo — SCR pain (PAIN)	Skin-conductance + pain
2019	Yu/Koban — Guilt (Cereb Cortex)	Interpersonal guilt
2020	Geuter — Pain PDM mediation (Cereb Cortex)	Pain mediation directions
2020	Silvestrini/Rainville — aMCC pain × cognitive control (NeuroImage)	dACC pain / Stroop
2020	Van Oudenhove/Kragel — Somatovisceral (Nat Comms)	Visceral vs somatic
2020	Zhou — General vicarious pain (eLife)	NS / FE / general vicarious pain
2021	Čeko — MPA2 multiaversive (Nat Neurosci 2022)	5 aversive modalities
2021	van 't Hof — BASIC (Cereb Cortex)	Sexual-image classifier
2021	Zhou — Subjective fear VIFS (Nat Comms)	Subjective fear
2022	Coll — Pain × money decision value	Pain / money / shock value
2022	Koban — NCS Craving (Nat Neurosci 2023)	Drug & food craving
2023	Speer — Brain Reward Signature (BRS)	Reward signature
2024	FEPS — Facial Expressions of Pain (eLife)	Facial-expression-based pain
2026	Murillo — PiFoneM (J Pain)	Pain-induced fear / negative-affect

Atlases and parcellations — all entries documented

Year	Folder	Description
2006	Desikan-Killiany	Desikan-Killiany cortical atlas
2009	Destrieux	Destrieux gyral/sulcal cortical atlas
2011	Buckner 7networks	7 resting-state networks
2011	Yeo 17networks	17 resting-state networks
2012	Desikan-Killiany-Tourville (DKT)	DKT cortical atlas
2013	Shen/Constable 268	268-node functional parcellation
2014	Keuken 7T subcortex	7T high-resolution subcortex
2016	CIT168 amygdala v1.0.3	Amygdala subnuclei
2016	Fan Brainnetome 273	Brainnetome parcellation
2016	Glasser HCP-MMP1	360 multimodal cortical parcels (pilot)
2018	CIT168 reinf-learn v1.0.0	CIT168 subcortical v1.0.0
2018	CIT168 reinf-learn v1.1.0	CIT168 subcortical v1.1.0
2018	Iglesias thalamic	Iglesias thalamic nuclei
2018	Schaefer/Yeo multires	100–1000 parcel multi-resolution cortex
2018	Wager combined atlas	Original CANlab whole-brain composite
2019	Cartmell NAc core/shell	NAcc core / shell
2019	Kragel PAG	Periaqueductal gray subregions
2019	Wager pain pathways	Canonical ascending/descending pain
2019	Zheng pain connectivity modules	Pain connectivity modules
2020	Iglesias hypothalamus	Hypothalamic subregions
2020	JulichBrain v3.0.3	Cytoarchitectonic
2020	Pandora WM atlas	White-matter bundles
2020	Thiebaut de Schotten WM	White-matter atlas
2020	Tian subcortical v1.1	Multi-scale subcortex
2022	Hansen PET tracer maps	Neurotransmitter PET maps
2023	Bianciardi Brainstem Navigator v0.9	Brainstem nuclei
2023	CANlab atlas (2023)	CANlab combined atlas (2023)
2023	CANlab atlas CIFTI	CIFTI grayordinate version
2023	Harvard AAN brainstem	Ascending arousal network
2023	Levinson/Bari limbic brainstem	Limbic brainstem
2024	CANlab atlas (2024)	Latest CANlab combined atlas
2026	Pourmajidian mitochondrial energetic capacity	Mitochondrial energetic capacity
util	readme_and_summary	Cross-atlas summary materials

CANlab meta-analysis maps — all entries documented

Year	Folder
2003	Wager — Emotion 64 studies (NeuroImage)
2003	Wager — Working memory 60 studies (CABN)
2004	Wager — Attention switching 31 studies
2007	Etkin — Anxiety disorders (AJP)
2007	Nee — Inhibition 47 studies
2008	Kober — Emotion 163 studies (NeuroImage)
2011	Agency meta-analysis
2011	Meissner — Placebo masks (J Neurosci)
2011	Yarkoni — Neurosynth (Nat Methods)
2012	Denny — SOMA self/other
2014	Buhle/Silvers — Reappraisal meta
2015	Satpute/Barrett — Emotion valence
2015	Wager/Kang — Emotion meta BSPP
2016	de la Vega — Neurosynth mPFC parcellation
2016	Neurosynth/Wager — Social-affective
2016	Pauli — Basal-ganglia parcels (PNAS)
2017	Ashar — Placebo review
2017	de la Vega — Neurosynth cortical parcellation
2018	Kraynak/Gianaros — Immune meta
2018	Sha — Common networks of psychopathology
2021	Zunhammer — N=603 pain placebo
2024	Quah/Saggar — RDoC factor maps (Nat Comms 2025)

Neurosynth maps

• 2016 Neurosynth 100 topics (v4/v5) — pilot
• mkda/ — MKDA per-term kernel-density maps
• scripts/ — Helper scripts
• topic_terms_csv/ — Per-topic term-frequency CSVs

Individual-study maps

• 2024 Bo — Emotion regulation Bayes factor (Nat Neurosci) — pilot
• 2026 Miao — Social/ToM Bayes factor

Spatial basis functions

• Margulies — Principal cortical gradient (PNAS 2016) — pilot
• HCP 91k
• HCP group ICAs
• Transcriptomic gradients
• Mitochondrial profile maps (Mosharov 2025)

Templates

• templates landing page — overview of MNI templates included.
• cerebellum/
• transforms/

---

Conventions used in this documentation

Per the contribution guidelines, every study folder follows the same layout. The contents_description.md in each folder is the canonical entry point and contains:

1. Overview — what the resource is, in a few lines, with the primary reference linked at the publisher's site (and citations to any secondary references found in the folder).
2. Key images — 1–2 representative figures (montage, surface, or isosurface) taken from the CANlab Brain Patterns site or generated by visualize_contents.m. Pre-rendered figures already present in folders (e.g., images_and_regions/, figures/, png_images/) are embedded directly.
3. How to load — the exact load_atlas() / load_image_set() call, or the filename to pass to fmri_data() / atlas() directly.
4. Construction scripts — links to constructor scripts in the folder or in CanlabCore.
5. File inventory — every NIfTI / .mat / .m in the folder with one line each. Individual .png files are not listed (they are embedded as key images instead).
6. Citations — primary and secondary papers, plus links.

Existing author-authored README.md / Readme.md / Readme.txt files in sub-folders are preserved verbatim and linked from the new contents_description.md, mirroring the Glasser-folder pattern.

Regenerating figures

After modifying any folder, regenerate its PNGs:

cd /path/to/Atlases_and_parcellations/2016_Glasser_Nature_HumanConnectomeParcellation
visualize_contents();   % writes png_images/<label>_{surface,montage,isosurface}.png

To re-render every signature in one MATLAB session:

addpath('/path/to/Neuroimaging_Pattern_Masks/docs');
run_all_multivariate('Multivariate_signature_patterns');    % or any other category

Adding a new study folder

1. Create the folder under the appropriate category with name YYYY_<lastauthor>_<keywords>.
2. Drop in the NIfTI / .mat files plus a copy of the primary reference PDF (filename: <lastauthor>_<year>_<keywords>.pdf).
3. Copy a visualize_contents.m from a similar folder and adapt the imgs cell.
4. Run it once locally to generate png_images/.
5. Write contents_description.md following the sections above.
6. Add the entry to the appropriate category list in the top-level landing page (e.g., Atlases_and_parcellations/README.md) and to the master list in this docs/README.md.
7. If applicable, add a keyword to the switch in CanlabCore/Data_extraction/load_image_set.m or load_atlas.m.

---

Documentation status

Every study folder in the repository now has a contents_description.md and (in nearly all cases) a visualize_contents.m. Top-level landing pages list each subfolder and link to its docs.

PDF coverage: 30+ PDFs are checked in directly. For a few paywalled papers (Reddan 2018 Neuron, Speer 2023 J Neurosci, Coll 2022, Kragel 2015 SCAN) the DOI link is recorded but no local PDF is present.

MATLAB / PNG coverage: every visualize_contents.m writes its output to png_images/. The full batch is reproducible by running docs/run_all_multivariate.m once per category.

If a folder you need is missing something, the underlying image files and any pre-existing README.md / create_*.m script in that folder remain authoritative — the new docs are an additional indexing / discovery layer, not a replacement.