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.
- Overview. This page explains the data structure: how hypline organizes subject-level brain data and dyad-level conversation data.
- 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.
- 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. Adyad-040audio 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.