Hyperface fMRI Dataset

This repository contains analysis code and quality assurance tools for the Hyperface fMRI dataset. The dataset consists of fMRI data collected while participants viewed dynamic face stimuli in a visual memory task.

Installation

This project uses uv for dependency management.

# Clone the repository
git clone https://github.com/mvdoc/hyperface-data-paper
cd hyperface-data-paper

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv sync

Data Access

The dataset is available on OpenNeuro and follows the BIDS standard:

• Raw data: ds007329
• fMRIPrep derivatives: ds007384
• FreeSurfer derivatives: ds007378

To download the data using datalad:

# Install the dataset and all derivatives (fMRIPrep, FreeSurfer) from OpenNeuro
datalad install -r data

# Download specific files as needed
datalad get data/sub-sid000005/

Quality Assurance

The repository includes a comprehensive QA pipeline for assessing data quality.

Motion Analysis

# Generate motion parameter plots
python scripts/qa/qa-plot-motion.py

# Generate interactive HTML reports
python scripts/qa/qa-generate-html-reports-motion.py

Temporal SNR Analysis

# Compute tSNR maps
python scripts/qa/qa-save-tsnr-volume.py

# Generate visualizations
python scripts/qa/qa-plot-tsnr.py

# Generate HTML reports
python scripts/qa/qa-generate-html-reports-tsnr.py

Inter-Subject Correlation

# Compute ISC
python scripts/qa/qa-save-isc.py

# Generate surface visualizations
python scripts/qa/qa-plot-isc.py

All outputs are saved to data/derivatives/qa/ following BIDS conventions.

Repository Structure

hyperface-data-paper/
├── data/                           # BIDS dataset (OpenNeuro ds007329)
│   ├── stimuli/                    # 707 video clips (4s each)
│   └── derivatives/
│       ├── fmriprep/               # fMRIPrep 25.1.4 (OpenNeuro ds007384)
│       ├── freesurfer/             # FreeSurfer 7.3.2 (OpenNeuro ds007378)
│       ├── qa/                     # QA outputs (generated by this repo)
│       ├── stimuli/                # Stimulus descriptors (embeddings, RDMs, ratings)
│       └── jiahui-2023/            # Data from Jiahui et al. (2023) PNAS
├── src/hyperface/                  # Python analysis package
└── scripts/qa/                     # QA pipeline scripts

Citation

If you use this dataset, please cite:

Visconti di Oleggio Castello, M., Jiahui, G., Feilong, M., de Villemejane, M., Haxby, J. V., & Gobbini, M. I. (2026). Hyperface: a naturalistic fMRI dataset for investigating human face processing. bioRxiv. https://doi.org/10.64898/2026.03.11.711073

License

BSD 2-Clause License. See LICENSE for details.