Skip to content

Overview

The pipeline

Hypline's commands form a modular pipeline. Once your files follow the hypline dataset layout, each command takes the dataset root as its main input and automatically finds the files it needs.

The workflow has three parts: (1) the stimulus branch prepares features describing the conversation; (2) the fMRIPrep branch prepares denoised BOLD responses; and (3) the encoding branch combines these inputs to fit and evaluate encoding models.

Command Branch Reads Writes
transcribe stimulus stimulus audio word-level transcripts
featuregen phonemic stimulus transcripts phonemic features (+ confounds)
featuregen semantic stimulus transcripts semantic features (+ confounds)
featuregen spectral stimulus stimulus audio spectral features (TR-aligned)
featuregen syntactic stimulus transcripts syntactic features
confoundgen phonemic stimulus phonemic features conf-phonemic confounds
confoundgen semantic stimulus semantic features conf-semantic confounds
denoise fMRIPrep preprocessed BOLD, fMRIPrep confounds denoised BOLD (desc-denoised)
encoding train encoding features, confounds, denoised BOLD fitted models (results/)
encoding analyze encoding fitted models, features, denoised BOLD eval scores (results/)

The stimulus and fMRIPrep branches can be run independently. Stimulus commands construct the predictors used by the encoding model, while denoise prepares the BOLD responses that serve as its targets. These inputs come together only when you run the encoding commands.

Features and their confounds in one step

featuregen phonemic generates the corresponding phonemic confounds by default, so you usually do not need to call confoundgen phonemic separately. See the featuregen guide.

You do not need to run the entire pipeline. Each command can be used independently as long as its required inputs already exist. For example, you can run transcribe only to generate transcripts, or denoise only to clean fMRIPrep BOLD data.

Example command set

For example, a basic analysis using phonemic features looks like this:

# stimulus branch: audio → transcripts → features
hypline transcribe data/ --audio-ext .wav
hypline featuregen phonemic data/

# fMRIPrep branch: preprocessed BOLD → denoised BOLD
hypline denoise data/ \
  --columns trans_x,trans_y,trans_z,rot_x,rot_y,rot_z,cosine

# encoding branch: fit the encoding model
hypline encoding train data/ \
  --data-filters task-conv \
  --features phonemic \
  --desc v1 \
  --fold-by run

After these steps, data/ contains the phonemic predictors, denoised BOLD responses and fitted encoding models under results/. To evaluate fitted models, use hypline encoding analyze. You can then load the resulting evaluation outputs in Python with load_eval / load_artifact.

You can also run any step on its own. Hypline skips outputs that already exist; use --force when you want to regenerate them. If a command reports No dyads found, No subjects found, or a per-ID failure, see When a filter matches nothing.