Skip to content

Hypline dataset layout

Hypline's fMRI workflow starts with data already preprocessed with fMRIPrep. This guide assumes some familiarity with its BIDS organization: subjects (sub-*), optional sessions (ses-*), and functional runs stored under func/. Hypline reads the preprocessed BOLD data and confound files from derivatives/fmriprep/; it does not run fMRIPrep or require the original raw BOLD images.

Each data-processing command takes the dataset root as its main positional argument. You organize files according to hypline's conventions so that commands can find their inputs and write outputs without separate paths for every file.

We will explain how to prepare your data for hypline in three steps.

  1. Overview. This page explains the data structure: how hypline organizes subject-level brain data and dyad-level conversation data.
  2. Create. The second step reviews the files necessary for running hypline, including how to label meaningful segments of your data and provide metadata files. See Segments and metadata.
  3. Organize. To assemble your own data, files, and metadata files in the standardized hypline format, see Prepare your own dataset.

Once your dataset is ready, continue to the command-specific guides, beginning with hypline transcribe.

The root tree

A hypline dataset extends the BIDS structure with directories for conversation data and analysis outputs. The tree below shows both inputs and outputs; hypline creates the output directories as you run the corresponding commands.

<dataset-root>/
├── participants.tsv                         # dyad ↔ subject mapping
├── sub-041/ses-1/func/                      # events files (raw BIDS optional)
├── derivatives/
│   ├── fmriprep/sub-041/ses-1/func/         # fMRIPrep outputs (preprocessed BOLD)
│   └── hypline/sub-041/ses-1/func/          # hypline imaging derivatives (denoised BOLD)
├── stimuli/dyad-040/ses-1/
│   ├── audio/                               # audio recordings
│   └── transcript/                          # generated transcripts
├── features/dyad-040/ses-1/phonemic/        # generated features
├── confounds/dyad-040/ses-1/phonemic/       # generated confounds
├── results/sub-041/
│   ├── encodingModel-v1/                    # fitted encoding models
│   └── encodingEval-v1/                     # evaluation results
├── nuisance/sub-041/ses-1/physio-v1/        # nuisance regressors (optional)
└── logs/<command>/                          # per-ID run logs, written by every command
Who provides Files or directories Description
You participants.tsv Maps each subject to a dyad.
You sub-*/[ses-*]/func/*_events.tsv Timing and labels of events within each run. See Segments and metadata.
You (optional) sub-*/[ses-*]/func/*_events.json Descriptive metadata for each segment, such as condition.
You (generated by fMRIPrep) derivatives/fmriprep/ Preprocessed BOLD data and fMRIPrep confound files.
Hypline derivatives/hypline/ Denoised BOLD data, generated by denoise.
You stimuli/dyad-*/[ses-*]/audio/ Conversation recordings per dyad.
Hypline stimuli/dyad-*/[ses-*]/transcript/ Transcripts of the recordings.
Hypline, or you features/ and confounds/ Stimulus features and their associated confounds.
Hypline results/ Fitted encoding models and evaluation results.
You (optional) nuisance/ Additional run-level nuisance regressors, such as physiological recordings.
Hypline logs/ Per-subject or per-dyad logs for each command.

The derivatives/hypline/ tree mirrors fMRIPrep's sub-XX/[ses-YY/]func/ organization and carries its own dataset_description.json.

The optional regressors under nuisance/ are used by denoise alongside fMRIPrep's confounds. These differ from the stimulus confounds under confounds/, which are used in encoding analyses.

Sessions are optional

Examples here use a ses-1/ level under each subject (sub-041/ses-1/func/) to match the tutorial dataset. Datasets without sessions omit the level entirely (sub-041/func/). Hypline handles both cases.

Subject vs. Dyad

Hypline organizes files by either the individual subject or the shared conversation:

  • sub-keyed — derived from one subject: brain data (derivatives/fmriprep/, derivatives/hypline/), events files, additional nuisance regressors (nuisance/), and encoding results (results/). Each partner has their own BOLD data and fitted encoding model.
  • dyad-keyed — derived from the shared conversation between two partners: recordings and transcripts (stimuli/), stimulus features (features/), and stimulus confounds (confounds/). Each dyadic conversation run has one shared set that can be used to fit a separate encoding model for each partner. A dyad-040 audio file represents the shared recording.

You connect these identifiers through participants.tsv, a standard BIDS table at the dataset root. Alongside its participant_id column, add a custom dyad_id column:

participant_id   dyad_id
sub-041          dyad-040
sub-042          dyad-040

Here subjects 041 and 042 are partners in dyad-040. When fitting an encoding model for sub-041, hypline looks up that subject's dyad in this table and reads the features for dyad-040. This is the only way hypline knows which subjects make up which dyad; hypline does not pair them by matching numbers.

Every command except denoise reads this table and stops with an error if it is missing. Even dyad-level commands such as transcribe need it, because they read each partner's events file. A workflow that runs only denoise does not require it.

File-naming convention

Hypline follows BIDS filename conventions: entity-value pairs are joined by underscores (_), followed by a suffix and extension. For example:

sub-041_task-conv_run-1_space-T1w_desc-preproc_bold.nii.gz
\____________________________________________/ \__/ \_____/
                   entities                   suffix   ext

A filename begins with either sub or dyad. For run-level files, ses (when present), task, and run identify the session, task, and run. Generated run-level files retain these identifiers from their source files.

Category entities

Files stored under features/, confounds/, nuisance/, and results/ also carry a category entity that identifies their contents:

Entity Area Example
feat-<kind> features/ feat-phonemic, feat-semantic, feat-spectral, feat-syntactic
conf-<kind> confounds/ conf-phonemic, conf-semantic
nuis-<kind> nuisance/ nuis-physio
result-<kind> results/ result-encodingModel, result-encodingEval

The <kind> determines the subdirectory. For example, a phonemic feature (feat-phonemic) lives under features/dyad-040/ses-1/phonemic/.

Denoised BOLD files under derivatives/hypline/ instead follow standard BIDS-derivatives naming and use desc-denoised.

Recordings and transcripts use a filename suffix (_audio or _transcript) instead of a category entity. For example, dyad-040_ses-1_task-conv_run-1_audio.wav lives under stimuli/dyad-040/ses-1/audio/.

desc variants

Some commands accept a --desc label that tags an output as one variant among several. Variants live in their own subdirectory so they stay physically separate:

confounds/dyad-040/ses-1/
├── phonemic-onset/    # conf-phonemic_desc-onset — speech-onset indicator
└── phonemic-rate/     # conf-phonemic_desc-rate  — speech rate per TR

Similarly, result-encodingModel_desc-v1 is stored under results/sub-041/encodingModel-v1/. These directories let you keep multiple variants and select the one you want by name.

Why the convention matters

A standard naming and file structure convention means commands compose cleanly: each reads what earlier steps wrote, with no configuration file wiring inputs to outputs. It also keeps your dataset self-describing, since the directory tree itself records what has been generated and from what.

Where to go next

Continue to Segments and metadata for the required events and metadata formats, then follow Prepare your own dataset to assemble your files.

To select particular subjects, dyads, runs, or conditions when running commands, see Filter to specific runs or conditions.