Skip to content

README.md

Latest commit

 

History

History
102 lines (87 loc) · 7.43 KB

README.md

File metadata and controls

102 lines (87 loc) · 7.43 KB

Multivariate signature patterns

Pre-trained multivariate fMRI brain patterns ("signatures", "neuromarkers") that can be applied to new individual-subject contrast maps to generate predicted scores (e.g., pain intensity, emotion rating, craving). Each sub-folder contains one published signature with its weights, supporting files, and a per-folder contents_description.md.

See the docs README for the documentation conventions used throughout the repo, and the CanlabCore Tools for the object-oriented MATLAB toolbox these signatures are designed to be used with.

Applying signatures to new data

Two convenience wrappers live at the root of this folder:

  • 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.

    [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. See the SIIPS folder (2017_Woo_SIIPS1/contents_description.md) for examples.

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

For a single signature, the most direct call is:

[obj, networknames, imagenames] = load_image_set('siips');     % keyword from load_image_set.m
new_data = fmri_data('my_contrast.nii');
sig_response = apply_mask(new_data, obj, ...
                         'pattern_expression', 'ignore_missing');

Sub-folders

Every sub-folder below contains contents_description.md (per-study overview, references, file inventory, and loading instructions), visualize_contents.m (regenerates png_images/), and the signature files themselves.

Year Study Topic CanlabCore keyword
2011 Wager — Placebo prediction (J Neurosci) Placebo response (no keyword — load .img directly)
2015 Chang — PINES (PLoS Biol) Picture-induced negative affect pines
2015 Kragel — Emotion BPLS (SCAN) 7 emotion categories kragelemotion
2015 Woo — Romantic Rejection (Nat Comms) Social rejection rejection
2016 Eisenbarth — Autonomic GSR/HR (J Neurosci) Skin conductance, heart rate gsr, hr
2016 Krishnan — VPS (eLife) Vicarious pain vps
2017 Ashar — Care / Distress (Neuron) Empathic care vs distress (load .nii directly)
2017 Rosenberg — saCPM (Nat Neurosci) Sustained attention (connectome) (load .mat directly)
2017 Woo — SIIPS1 (Nat Comms) Cerebral pain (beyond nociception) siips
2018 Kragel — MFC generalizability (Nat Neurosci) Pain × emotion × cognitive control in MFC kragel18, pain_cog_emo
2018 Reddan — Threat ImEx (Neuron) CS+ vs CS− threat conditioning csplus
2019 Kragel — Emotion Schemas (Sci Adv) 20 emotion categories kragelschemas
2019 Lee — Back pain (PAIN) Chronic-back-pain markers (S1, PCASL, HFHRV) (load directly)
2019 Matthewson/Woo — SCR pain (PAIN) Skin-conductance + pain (see Readme.rtf)
2019 Yu/Koban — Guilt (Cereb Cortex) Interpersonal guilt guilt
2020 Geuter — Pain PDM mediation (Cereb Cortex) Pain mediation directions pdm, pain_pdm
2020 Silvestrini/Rainville — aMCC pain × cognitive control (NeuroImage) dACC pain / Stroop patterns stroop
2020 Van Oudenhove/Kragel — Somatovisceral (Nat Comms) Visceral vs somatic pain (load .mat directly)
2020 Zhou — General vicarious pain (eLife) NS / FE / general vicarious pain (helper load_zhouvps)
2021 Čeko — MPA2 multiaversive (Nat Neurosci 2022) 5 aversive modalities mpa2, multiaversive
2021 van 't Hof — BASIC (Cereb Cortex) Sexual-image classifier (load .nii directly)
2021 Zhou — Subjective fear VIFS (Nat Comms) Fear from video (helper load_vifs)
2022 Coll — Pain × money decision value Pain / money / shock-intensity value (load directly)
2022 Koban — NCS Craving (Nat Neurosci 2023) Drug & food craving ncs
2023 Speer — Brain Reward Signature (BRS) Reward signature (load .nii directly)
2024 FEPS — Facial Expressions of Pain (eLife) Facial-expression-based pain (load .nii directly)
2026 Açıl — Mentalizing: Self / Other (Nat Comms) Mentalizing about self vs. other (MS, MS-Self, MS-Other, MS-SvO) selfother
2026 Murillo — PiFoneM (J Pain) Pain-induced fear of neck movement pifonem, fearofneckpain

Conventions

  • Each sub-folder has the same shape: contents_description.md, visualize_contents.m, NIfTI / .mat data, a PDF of the primary reference (where redistributable), and a png_images/ directory with regenerated surface / montage / isosurface figures.
  • The shared rendering helpers live in ../docs/canlab_render_patterns.m (and canlab_render_atlas.m).
  • To regenerate every signature's PNGs in one MATLAB session, run ../docs/run_all_multivariate.m.