Prepare your own dataset¶
The tutorial hands you a ready-made dataset. This guide is the step that comes before it on your own data: arranging your recordings into the tree hypline expects, so that every command can find its inputs by convention. Once the tree is right, the commands run exactly as the tutorial shows.
The dataset layout describes the tree in full; this page is the practical checklist for building one from scratch.
What you supply, and what hypline fills in¶
Hypline reads a few things you must provide and writes everything else. Knowing the line between the two is most of the work:
| You supply | Hypline generates |
|---|---|
participants.tsv — the dyad ↔ subject map |
stimuli/…/transcript/ — transcripts |
Raw BOLD (optional) and events.tsv under sub-*/ |
features/ — features |
fMRIPrep outputs under derivatives/fmriprep/ |
confounds/ — stimulus confounds |
Stimulus audio under stimuli/…/audio/ |
derivatives/hypline/ — denoised BOLD |
events.json sidecars (optional metadata) |
results/ — models and evals |
nuisance/ regressors (optional) |
You never create anything in the right-hand column by hand. Get the left-hand column in place and the pipeline produces the rest.
1. Map subjects to dyads: participants.tsv¶
Hypline is a hyperscanning pipeline, so it needs to know which two subjects make
up each dyad. That mapping lives in participants.tsv at the dataset root — a
standard BIDS table with the required participant_id column plus a custom
dyad_id column:
participant_id dyad_id
sub-041 dyad-040
sub-042 dyad-040
sub-051 dyad-050
sub-052 dyad-050
This is the single source of truth that lets a dyad-keyed feature reach a
sub-keyed brain. Two subjects share a dyad_id exactly when they belong
to the same scanning pair.
In these examples the tens digit numbers the pair and the last digit marks its
role: dyad-040 is the pair, sub-041 and sub-042 its two partners. Hypline
does not require this; any IDs work as long as participants.tsv maps them.
Use real tabs
Every .tsv hypline reads must be separated by actual tab characters, not
spaces. A space-separated row collapses into one column and fails with a
misleading "missing column" error. This bites most often in
participants.tsv, since it is the first file hypline reads.
Hypline reads this participant-dyad mapping participants.tsv file from the
dataset root folder.
2. Add event information under sub-*/¶
Hypline reads each run's structure from BIDS events.tsv files stored in the
subject's func directory:
sub-041/ses-1/func/
├── sub-041_ses-1_task-conv_run-1_bold.nii.gz
└── sub-041_ses-1_task-conv_run-1_events.tsv
Sessions are optional
The ses-1/ level is optional. A dataset without sessions omits it entirely
(sub-041/func/), and hypline handles both. Keep it consistent across the
dataset.
The raw BOLD image may remain as part of your original BIDS dataset, but hypline
does not read it directly. Hypline reads the accompanying events.tsv and
obtains its imaging data from the fMRIPrep derivatives described in the next
section.
An events.tsv file can describe segments such as trials, blocks, or
conditions, as well as the subject's speaking turns. Hypline uses these
annotations when generating segment-level features, filtering runs or
conditions, and assigning transcript words to speakers. For an
unsegmented whole-run dataset, events.tsv may be omitted for every step
except encoding, which requires speaking-turn (turn_speaker) rows.
See Segments and metadata to learn how to create your events.tsv
files. That page explains the required columns, hypline's segment-labeling
convention, speaking-turn annotations, and how to attach descriptive
metadata through events.json.
3. Add your fMRIPrep outputs¶
Hypline does not preprocess BOLD; it takes in the output of
fMRIPrep. Run fMRIPrep yourself and place its
derivatives under derivatives/fmriprep/, in the per-subject shape it already
produces:
derivatives/fmriprep/sub-041/ses-1/func/
├── sub-041_ses-1_task-conv_run-1_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
└── sub-041_ses-1_task-conv_run-1_desc-confounds_timeseries.tsv
denoise reads the preprocessed BOLD and pulls its
nuisance regressors from fMRIPrep's own desc-confounds table, so both must be
present. The BOLD space you preprocessed into is the one you will pass to
denoise and encoding later.
4. Add the stimulus audio¶
The conversation audio is dyad-keyed (it belongs to the pair, not either
partner), so it goes under stimuli/, keyed by dyad:
stimuli/dyad-040/ses-1/audio/
└── dyad-040_ses-1_task-conv_run-1_audio.wav
This is the only stimulus area you fill by hand. From here
transcribe writes the transcripts and
featuregen writes the features, both back under
stimuli/ and features/ at the same dyad key.
Match filename entities to your event metadata
Before running the pipeline, check your audio filenames for entities
beyond identity and the segment entity (for example, block in
..._block-1_trial-3_audio.wav). These carry into transcript and
feature filenames and must be recorded in events.json, or
transcribe and featuregen stop with an error. Store descriptive
attributes, such as condition, in events.json rather than in
filenames. See Extra entities in filenames.
5. (Optional) Describe conditions and custom nuisance¶
Two optional inputs round out a dataset:
events.jsonsidecars attach descriptive metadata (condition, item, counterbalance group) to the segments declared inevents.tsv. This is what lets you filter oncondition-Reven thoughconditionnever appears in a filename. See Attaching metadata.nuisance/files hold run-level regressors you supply yourself that fMRIPrep never produced (physiological recordings, say) fordenoiseto regress out alongside the fMRIPrep columns. See thedenoisereference.
Both are optional. A dataset with neither still runs the full pipeline.
Check the tree before you run¶
Laid out, a minimal single-dyad dataset looks like this:
data/
├── participants.tsv
├── sub-041/ses-1/func/ # raw BOLD + events (you supply; raw BOLD not required)
├── sub-042/ses-1/func/
├── derivatives/fmriprep/ # fMRIPrep outputs (you supply)
│ ├── sub-041/ses-1/func/
│ └── sub-042/ses-1/func/
└── stimuli/dyad-040/ses-1/audio/ # conversation audio (you supply)
Everything else (features/, confounds/, derivatives/hypline/, results/)
appears as you run the commands. With this in place, follow the
tutorial from its transcription step onward; every
command takes data/ as its main positional argument and discovers its inputs from there.
Check
hypline transcribe data/ --audio-ext .wav should log one line per audio
file it finds. No dyads found means stimuli/ holds no dyad-*
directories; No subjects found from denoise means the
derivatives/fmriprep/ tree did not land where hypline looks.