HOI lens fMRI

Higher-Order Interaction (HOI) Analysis on fMRI Data

---

This repository contains the analysis code and figure notebooks associated with the manuscript ``Charting Higher-Order Models of Brain Function Beyond Pairwise Interactions''(https://www.biorxiv.org/content/10.1101/2025.06.24.661306v1.abstract). We systematically compare information-theoretic and topological higher-order interaction (HOI) metrics on resting-state and task fMRI data from 100 unrelated Human Connectome Project (HCP) subjects.

Ten HOI metrics are evaluated across five complementary frameworks:

#	Method	Framework	Language
1	O-information & interaction information	Information theory (synergy/redundancy)	Python
2	Local higher-order TDA (RHOSTS)	Topological data analysis	Julia
3	Homological scaffold	Persistent homology	Julia
4	Partial Entropy Decomposition (PED)	Information decomposition	Python
5	Phi-ID (integrated information decomposition)	Integrated information	Python

Repository structure

HOI_lenses_analysis/
├── Code/               # Analysis pipelines (see Code/README.md)
├── Container/          # Singularity/Docker environment definition
└── Paper/              # Jupyter notebooks reproducing all figures (see Paper/README.md)

Data

Raw and processed fMRI time series are not included in this repository. They are available from:

• HCP dataset: Human Connectome Project (requires data use agreement)
• Processed data (pre-computed HOI outputs used by the figure notebooks): [Zenodo — link to be added]

The Paper/Figure2/data/SC/ folder contains structural connectome CSV files derived from HCP diffusion MRI (included here for convenience, ~5 MB). Small auxiliary reference arrays (neuroscience maps, hierarchies, etc.) are bundled directly in each Paper/Figure*/data/ folder.

Requirements

• Python ≥ 3.10 — package list: Container/requirements_python.txt
• Julia ≥ 1.10.2 — package list: Container/requirements_julia.txt

Installation

# 1. Install Python dependencies
pip install -r Container/requirements_python.txt

# 2. Navigate to Code/ and compile the Julia package
cd Code
sh compile_packages.sh

Running via Singularity / Docker

A minimal container environment is provided in Container/.

# Build the Singularity container
sudo singularity build my_container.sif Container/create_container.txt

# Open a shell inside the container
singularity shell my_container.sif

# Then compile Julia and run as usual
cd Code
sh compile_packages.sh
sh launch_HOIscript.sh

Running the analyses

The main entry point is Code/launch_HOIscript.sh (resting-state healthy-ageing dataset). Separate launch scripts are provided for HCP task conditions:

cd Code
sh launch_HOIscript.sh                  # resting state
sh launch_HOIscript_HCPrest.sh          # HCP resting state
sh launch_HOIscript_HCP_EMOTION.sh      # HCP emotion task
# ... (see Code/ for the full list)

Code contributors: Andrea Santoro and Matteo Neri.

Edit the input/output paths at the top of each script before running.