Skip to content

hypline encoding

Fit and test voxelwise ridge encoding models, the step that joins the two sides the rest of the pipeline prepares. train maps stimulus features (X) onto denoised BOLD (Y) per subject; analyze tests one subject's model against another subject's brain (or a held-out run of the same subject's brain), across production and comprehension turns. encoding is a group of subcommands.

hypline encoding <command> <dataset-root> [OPTIONS]
Subcommand Does
train Fit a per-subject ridge model from features (+ optional confounds)
analyze Test a model's predictions against a target subject's BOLD, within or across subjects

Both commands read from the dataset root and write to a new results/ area (see Outputs). Results load back as live Python objects rather than flat tables; read them for downstream analysis with the Encoding results API.

The banded ridge model

Each feature becomes its own ridge band (its own regularization strength); all confounds share one trailing band, partialled out in the same fit so a feature cannot claim variance a confound explains. In a dyadic conversation a subject alternates between producing speech and comprehending the partner's, so by default train duplicates every feature and confound regressor into a production copy and a comprehension copy and learns separate weights for each (--no-split keeps one shared copy). Either way, two intercept-like production/comprehension task boxcars always ride a reserved band that absorbs the mean BOLD offset between the two states — --no-split drops the per-regressor duplication, not this band. How the encoding model works unpacks this at more length.


encoding train

Fit a voxelwise ridge encoding model per subject, writing one model artifact per subject to results/.

hypline encoding train <dataset-root> \
  --features … --desc … --fold-by … [OPTIONS]

Inputs

  • Features under features/ — the predictors, generated by featuregen. Named by --features as <kind>[-<desc>] refs; each ref becomes its own ridge band.
  • Confounds under confounds/ (optional) — stimulus-derived nuisance regressors, generated by confoundgen. Named by --confounds; all share one band. Must be saved at TR level.
  • Denoised BOLD under derivatives/hypline/ — the target, produced by denoise. Selected by --bold-space and --bold-desc (default denoised).

Features are dyad-keyed and BOLD is subject-keyed, so train bridges them through participants.tsv — see Subject vs. Dyad.

Extra entities in feature filenames

If encoding train stops with Filename has '<key>-<value>', but events.json does not define '<key>', a feature filename selected by --features carries an entity that events.json does not record. transcribe and featuregen run the same check, so this usually means events.json changed after the features were generated. See Extra entities in filenames for how to fix it. If you remove the entity instead and it came from your audio filenames, rename those too and regenerate the transcripts and features.

Options

Option Description Default
--features Comma-separated feature refs as <kind>[-<desc>] (e.g. semantic-gpt3,phonemic-noArt); each becomes its own ridge band — required —
--desc Variant label for this model (alphanumeric); output lands under results/sub-XX/encodingModel-<desc>/ — required —
--fold-by Cross-validation grouping axis: a BIDS entity to fold on (e.g. run), or none for a single unfolded model — required —
--n-folds Number of folds: an integer (>=2) or loo. Defaults to loo with --fold-by <entity>; omit with --fold-by none loo (with --fold-by <entity>)
--confounds Comma-separated confound refs as <kind>[-<desc>] (e.g. phonemic-onset,phonemic-rate); all share one band none
--bold-space BOLD space to train on: fsaverage5, fsaverage6, MNI152NLin6Asym, MNI152NLin2009cAsym fsaverage6
--bold-desc BOLD desc entity selecting the input runs denoised
--downsample Feature-to-TR downsampling: mean or sum mean
--delays Comma-separated FIR delays in TRs 0,1,2,3,4,5
--alphas Comma-separated ridge alphas to search 1–1e12 log grid (13 points)
--device Compute device for the fit: cpu or cuda cpu
--no-split Fit one shared set of weights for production and comprehension instead of a separate set for each off
--sub-ids Comma-separated subject IDs to train (e.g. 041,042); omit for all all
--data-filters Comma-separated BIDS entity filters bounding the training corpus, including task selection (e.g. task-conv) — there is no dedicated task flag; see Filter to specific runs or conditions none
--force Overwrite existing outputs (default skips them) off

--fold-by and --n-folds

--fold-by <entity> defaults to leave-one-out (n_folds='loo'), so --n-folds is optional there — pass it only to override the count. The one invalid pairing is --fold-by none with an explicit --n-folds, which raises an error. --fold-by none fits a single model over the whole corpus; --fold-by run --n-folds 5 fits five cross-validated models grouped by run.

Pooling multiple tasks

A fit that spans more than one task shares one set of ridge weights across them, collapsing task-specific responses. train warns when it detects this without a task-level opt-in. To fit one task, narrow via --data-filters task-<label>. To pool tasks on purpose, name them with a task-* filter or fold across them with --fold-by task.

Example

Fit a single model per subject from semantic features plus phonemic-timing confounds, over the conv task:

hypline encoding train data/ \
  --data-filters task-conv \
  --features semantic-gpt3 \
  --confounds phonemic-onset,phonemic-rate \
  --desc v1 \
  --fold-by none

Cross-validate by run — leave-one-out by default, on a GPU:

hypline encoding train data/ \
  --data-filters task-conv \
  --features semantic-gpt3 \
  --desc cv \
  --fold-by run \
  --device cuda

encoding analyze

Test a trained model's predictions against a target subject's actual BOLD, per role (production / comprehension / both). Three subject roles are independent:

  • model (--model-sub) — whose trained weights are loaded.
  • source (--source-sub) — whose features build the prediction inputs (X).
  • target (--target-sub) — whose actual BOLD is the comparison (Y).

Any combination is valid within one study: all three the same subject is a within-brain fit; partners in one dyad share a conversation across different brains; different dyads are a scramble/null control (analyze warns). The values self and partner are accepted for --model-sub / --source-sub, resolved relative to --target-sub via participants.tsv. For how these pairings map to within-brain, cross-brain, and pseudo-dyad analyses, see Choosing source and model.

hypline encoding analyze <dataset-root> \
  --target-sub … --model-sub … --model-desc … --desc … [OPTIONS]

Options

Option Description Default
--target-sub Subject whose actual BOLD and production/comprehension turns are tested against — required —
--model-sub Subject whose trained model is loaded: an ID, or self/partner (relative to --target-sub) — required —
--model-desc The --desc passed to encoding train (its encodingModel-<desc> tag) — required —
--desc Variant label for this eval (alphanumeric); output lands under results/sub-<target>/encodingEval-<desc>/ — required —
--source-sub Subject whose regressors drive the prediction: an ID, or self/partner self
--test-on Comma-separated BIDS entity filters naming which cells to test (e.g. run-6, or run-6,run-8); omit to test each model's out-of-sample cells out-of-sample cells
--force Overwrite existing outputs (default skips them) off

The output is per-fold, per-band, per-role, per-voxel scores. These are himalaya split scores (each band's own contribution to the joint prediction), so a band's value is not a plain Pearson correlation and need not fall in [-1, 1]. Roles are derived from the target's turns: prod and comp are the exclusive pure-production / pure-comprehension rows, and both is the union of any speech-active row. A role with no rows scores NaN rather than zero.

Example

Test subject 041's own model against its own BOLD (a within-brain fit). With default --test-on, analyze tests each model's out-of-sample cells, so the model must be folded. A --fold-by none model trained on every cell has no held-out cells and raises here; name cells with --test-on, or use a folded model as below:

hypline encoding analyze data/ \
  --target-sub 041 \
  --model-sub self \
  --model-desc cv \
  --desc selfeval

Test subject 041's BOLD using the partner's model and features (a cross-brain, shared-conversation eval) on run 6:

hypline encoding analyze data/ \
  --target-sub 041 \
  --model-sub partner \
  --source-sub partner \
  --model-desc v1 \
  --desc crosseval \
  --test-on run-6

Outputs

Both commands write to a new top-level results/ folder, keyed by subject (one analysis output consumes many runs across sessions, so results carry no source-run or session entity):

<dataset-root>/results/
├── sub-041/encodingModel-v1/
│   ├── sub-041_result-encodingModel_desc-v1.joblib   # train: fitted model artifact
│   └── sub-041_result-encodingModel_desc-v1.json     # provenance sidecar (greppable)
└── sub-041/encodingEval-selfeval/
    └── sub-041_result-encodingEval_desc-selfeval.nc # analyze: per-voxel scores (netCDF-4)
  • encodingModel-<desc>/ (train) — the fitted model as a .joblib file, plus a JSON sidecar mirroring the recipe and provenance without unpickling.
  • encodingEval-<desc>/ (analyze) — the eval as a self-describing netCDF-4 file any tool can read, carrying provenance (model_sub, source_sub, target_sub, delays, bold_space, test_on, …) in its attributes.

Common errors

What you see Cause Fix
omit --n-folds with --fold-by none --n-folds was given alongside --fold-by none, which fits a single unfolded model. Drop --n-folds, or fold on an entity with --fold-by <entity>.
n_folds='loo' needs >= 2 groups to fold; got 1 --fold-by names an entity with only one value in the training corpus, so there is nothing to leave out. Widen the corpus (task/filters), or fit unfolded with --fold-by none.
n_folds=N exceeds the M group(s) found for the fold_by entity (train) --n-folds is larger than the number of distinct --fold-by values available. Lower --n-folds to at most the group count, or use loo.
No regressor files match the given filters / No BOLD files match the given filters (train) --features, --data-filters, --bold-space, or --bold-desc selected nothing. Confirm the features and desc-denoised BOLD exist and that the filters are not too narrow.
empty out-of-sample set — pass test_on to name cells (analyze) The model was trained unfolded (--fold-by none), so it has no held-out cells to test. Test a folded model, or name cells explicitly with --test-on.
test_on matched no available cells: … (analyze) --test-on names cells the source subject does not have. Check the --test-on filter against the runs/conditions that exist.
test_on entities […] not found on any available cell … check for a typo (analyze) A --test-on filter uses an entity that no cell carries. Fix the entity name (e.g. run-6, not ses-1).
Log warns source (…) and target (…) are different dyads (analyze) The source and target belong to different dyads — a scramble/null control. Expected for a null control; otherwise fix --source-sub so it shares the target's dyad.
No subjects found (train) No subjects under derivatives/fmriprep/; train discovers subjects there, not in derivatives/hypline/ (a missing desc-denoised BOLD shows up as a per-subject failure instead). Confirm the fMRIPrep outputs are under derivatives/fmriprep/.

Loading results in Python

Both commands write Python objects, not tables. Load them back for downstream analysis with the Encoding results API: load_eval for an eval, load_artifact for a fitted model.