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/

Stimuli

The video stimuli are short clips cut from publicly available YouTube videos and cannot be redistributed for copyright reasons, so they are not included in the OpenNeuro dataset. To reconstruct the stimulus set from the original sources, use the pipeline in scripts/stimuli/:

pip install yt-dlp                              # ffmpeg must also be on PATH
python scripts/stimuli/generate_stimuli.py      # re-cut clips -> ./regenerated_stimuli/
python scripts/stimuli/verify_stimuli.py        # verify against released fingerprints

Source videos are removed from YouTube over time; as of July 2026, 486 of the 707 clips can be regenerated. See the stimuli README for the per-run breakdown and verification details.

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)
│   └── 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
    ├── stimuli/                    # Regenerate & verify the video stimuli
    └── presentation/               # Experiment presentation code

The raw video stimuli are not part of the dataset — they are short clips from publicly available YouTube videos and cannot be redistributed for copyright reasons. Reconstruct them from the original sources with scripts/stimuli/ (see Stimuli).

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.