Context modulates brain state dynamics and behavioral responses during narrative comprehension

Code, methodological notes, and figure notebooks for:

Yibei Chen, Zaid Zada, Samuel A. Nastase, F. Gregory Ashby, Satrajit S. Ghosh; Context modulates brain state dynamics and behavioral responses during narrative comprehension. Imaging Neuroscience 2026; 4 IMAG.a.1116. doi: https://doi.org/10.1162/IMAG.a.1116

Overview

Two groups of listeners heard the same audio recording of J.D. Salinger's Pretty Mouth and Green My Eyes, preceded by different short framing paragraphs — one priming an affair interpretation, one priming a paranoia interpretation. We fit Hidden Markov Models to Kong-2022 17-network time series to identify recurring brain states, clustered them across model sizes to find stable state patterns, and used Bayesian mixed-effects logistic regression to test how context modulates the coupling between brain-state occupancy and stimulus content.

Data and code

Resource	Location
Raw fMRI (source dataset)	Hasson-lab narratives via DataLad: https://datasets.datalad.org/?dir=/labs/hasson/narratives
Derived outputs (HMM fits, clusters, GLMM results)	OSF project osf.io/7aqth — 5 tarballs (6.3 GB) + provenance docs (OUTPUT_MAP.md, REPRODUCING.md, MANIFEST_sha256.txt)
Code (this repo, frozen)	Tag v1.0-published — Zenodo concept DOI (cite this), latest version (auto-updates)

Repository layout

• script/ — numbered analysis pipeline (postprocessing → HMM → clustering → GLMM).
• notebooks/ — figure notebooks (figure1.ipynb … figure5.ipynb), plus *_RR_* Review-&-Revision variants.
• results/ — auto-generated statistical tables.
• docs/ — methodological notes (three-scope GLMM design, consensus-pattern audit).
• data/ — atlas files and subject ID lists.

Reproducing the analysis

1. Set up the environment:

   conda env create -f environment.yml
   conda activate prettymouth

2. Fetch the raw fMRI data via DataLad from the source above.
3. Run the pipeline in numerical order (01_postproc → 09_brain_content_glmm). HMM and GLMM steps are SLURM array jobs; see AGENTS.md for commands and the full data-flow description.

For AI coding agents

If you are an AI coding agent (Claude Code, Codex, Cursor, …) working in this repository, read AGENTS.md before making changes. It documents the frozen-pipeline boundaries, known gotchas, and naming conventions used throughout.

Citation

When you use the code, the derived outputs, or the published findings, cite the paper. The GitHub repository, Zenodo code archive, and OSF data archive are all artefacts of this paper — linked by the version-of-record tag v1.0-published (commit 5d5d445) — not separate things to cite.

Chen Y, Zada Z, Nastase SA, Ashby FG, Ghosh SS. Context modulates brain state dynamics and behavioral responses during narrative comprehension. Imaging Neuroscience 2026; 4: IMAG.a.1116. doi:10.1162/IMAG.a.1116.

This paper's artefact cluster:

Artefact	Locator
Paper of record	10.1162/IMAG.a.1116
Code (this repo)	github.com/yibeichan/prettymouth @ v1.0-published
Code archive (Zenodo, concept DOI)	10.5281/zenodo.20369772 (v1.0 snapshot: 10.5281/zenodo.20369773)
Derived data archive (OSF, CC-BY-4.0)	osf.io/7aqth

Machine-readable metadata for both the code and the paper of record is in CITATION.cff.

You should also cite the source raw fMRI dataset (prior work by another group):

Nastase SA, Liu Y-F, Hillman H, Zadbood A, Hasson U, et al. (2021). The "Narratives" fMRI dataset for evaluating models of naturalistic language comprehension. Scientific Data 8: 250.

.
├── AGENTS.md
├── CITATION.cff
├── LICENSE
├── README.md
├── TREE.md
├── docs
│   ├── consensus_pattern_audit.md
│   └── glmm_three_scope_design.md
├── environment.yml
├── generate_tree.sh
├── notebooks
│   ├── RR_figure5_supplement.ipynb
│   ├── behav.ipynb
│   ├── figure1.ipynb
│   ├── figure2.ipynb
│   ├── figure3.ipynb
│   ├── figure4.ipynb
│   ├── figure4_RR.ipynb
│   └── figure5.ipynb
├── results
│   ├── behavioral_content_analysis.md
│   ├── behavioral_content_analysis_supplement.md
│   ├── cluster1_combined_2states_deviation_th080.md
│   ├── cluster2_combined_7states_deviation_th080.md
│   ├── cluster3_combined_2states_deviation_th080.md
│   └── cluster4_combined_6states_deviation_th080.md
└── script
    ├── 01_postproc.py
    ├── 01_postproc.sh
    ├── 02_extract_parcels.py
    ├── 03_get_networks.py
    ├── 04_single_group_hmm_ntw.py
    ├── 04_single_group_hmm_ntw.sh
    ├── 05_model_comp.py
    ├── 06_state_pattern_cluster.py
    ├── 07_RR_cluster_stability.py
    ├── 07_RR_cluster_viz.py
    ├── 07_RR_correlation.py
    ├── 07_RR_individual_states.py
    ├── 07_RR_summarize_consensus.py
    ├── 07_RR_test_plot.py
    ├── 07_extract_cluster_data.py
    ├── 07_map_cluster2stateseq.py
    ├── 08_behav_proc.py
    ├── 08_behav_proc_bin_1s.py
    ├── 08_stimuli_annot.py
    ├── 08_stimuli_annot_bin_1s.py
    ├── 09_behavior_content_glmm.py
    ├── 09_behavior_content_glmm_bin_1s.py
    ├── 09_brain_content_glmm.py
    ├── 09_brain_content_glmm.sh
    ├── 10_result2md.py
    ├── __init__.py
    └── utils
        ├── __init__.py
        ├── glmm.py
        ├── pattern_cluster.py
        └── result2md.py

6 directories, 53 files