Encoding results¶
The encoding CLI produces two kinds of results:
- evals from
analyze, containing the per-voxel encoding scores used for downstream analysis; - model artifacts from
train, containing fitted models and the recipe used to construct them.
Load both from hypline.encoding:
from hypline.encoding import load_eval, load_artifact
Load an eval¶
An eval (analyze's output) loads as an
xarray.Dataset. This is the usual starting
point for downstream analysis because it contains the per-voxel encoding scores.
ds = load_eval("data/results/sub-041/encodingEval-selfeval/sub-041_result-encodingEval_desc-selfeval.nc")
The main variable is corr, a four-dimensional array:
ds["corr"].dims # ('fold', 'band', 'role', 'voxel')
| Axis | What one position along it means |
|---|---|
fold |
One cross-validation fold — the model scored on the data it held out. |
band |
One part of the model: the task offset, a feature, or the confounds. |
role |
Which turns were scored: production, comprehension, or either. |
voxel |
One location in the brain. |
Three of the four carry named labels you can select on; voxel is a bare
integer index, since an eval has no real voxel identifiers to attach. The sections
below explain these dimensions and how to select the scores needed for an analysis.
band: the parts of the model¶
An encoding model is a banded ridge: each feature gets its own band, and
analyze reports a separate score for each. The band labels are, in order, a
reserved task band, then one label per feature, then a single confounds band if
the model had any confounds:
ds.coords["band"].values
# array(['screens_band', 'phonemic', 'semantic', 'confounds_band'], dtype=object)
screens_bandis always first and always present. It carries the production and comprehension task offsets — the part of the model that soaks up the average difference in signal between speaking and listening, so the feature bands do not have to.- A band per feature, named exactly as you passed it to
--features(phonemic,semantic-gpt3, and so on). This is usually what you care about: each feature's own contribution to predicting the brain. confounds_bandappears only when the model was trained with--confounds. Every confound shares this one band.
Select a single feature's scores by name:
ds["corr"].sel(band="semantic")
The production/comprehension split does not add bands
Training with the default prod/comp split does not create separate
production and comprehension bands. It widens each existing band so the model
can learn different weights for the two states, but the band labels stay the
same. The production-versus-comprehension split you score on lives on the
role axis below, not here.
role: which turns were scored¶
A conversation alternates between the target subject speaking and listening, and a model can predict those two states differently. So every score is also broken out by role, derived from the target subject's own turns:
prod— rows where the target was speaking, and only those.comp— rows where the target was listening, and only those.both— either: any row with speech active, from the target or the partner.
ds["corr"].sel(role="prod") # scores during the target's own speech
prod and comp are kept strictly separate. The model's
FIR delays let one turn's signal spill onto the first
rows of the next, and those boundary rows are dropped from both so neither role
is contaminated. both keeps them, which is why it is not simply prod plus
comp. A role with no rows in a fold (a run where the target never listened,
say) scores NaN, not zero. That way it can be skipped when you average across
folds rather than dragging the average down.
fold: the cross-validation folds¶
fold is a plain integer index, 0 upward. It does not tell you which run
each fold held out; that lives in the dataset's attributes, one list of cells
per fold:
ds.attrs["fold_cells"][0] # the cells fold 0 was scored on (its held-out run)
To collapse the folds into one score per voxel, average across them — and use a
NaN-aware mean so an empty role in one fold does not poison the result:
ds["corr"].mean("fold", skipna=True)
The attributes: what analysis this is¶
The scores alone do not say whose model, whose speech, or whose brain produced
them. That provenance rides along in ds.attrs, so an eval file is
self-describing wherever it ends up:
ds.attrs["model_sub"] # whose trained weights were used
ds.attrs["source_sub"] # whose speech built the prediction inputs
ds.attrs["target_sub"] # whose brain the scores are measured against
ds.attrs["test_on"] # 'OOS' for out-of-sample, else the cells named with --test-on
ds.attrs["delays"] # the FIR delays the model used, in TRs
ds.attrs["bold_space"] # the BOLD space it was scored in
The identities of source, model, and target determine what an eval means.
The same model file says very different things depending on how source, model,
and target line up, and that choice has its own page:
Choosing source and model.
What the scores are, and are not¶
The values in corr are himalaya split scores: each band's own share of the
joint prediction's accuracy. Two things follow from that, and both are easy to
get wrong:
- A split score is not a plain Pearson correlation and need not land in
[-1, 1]. A single band's value can even be negative. Read it as that band's relative encoding strength, not as a fraction of variance explained. - The scores are a decomposition of the joint model's correlation, so the bands
do sum to it:
r_joint = r_screens + r_semantic + … + r_confounds. That makes the sum the joint model's score — but a single band's share is not itself a correlation, so do not read one band's value on that scale.
A first look at your eval
Loaded, a typical within-brain eval subsets like this — the production score for one feature, averaged over folds:
ds["corr"].sel(band="semantic", role="prod").mean("fold", skipna=True)
From here, Choosing source and model explains how the subject wiring behind an eval changes what a score like this tells you.
To compare within-brain, cross-brain, and pseudo-dyad evals, see Compare cross-brain fits with a baseline.
Load a model artifact¶
A model artifact (train's output) loads as an EncodingArtifact, which
contains the fitted weights and the recipe needed to inspect or reuse the model:
artifact = load_artifact("data/results/sub-041/encodingModel-v1/sub-041_result-encodingModel_desc-v1.joblib")
artifact.recipe # the XRecipe: features, confounds, delays, alphas, split, …
artifact.models # one FittedModel per fold (its pipeline + the cells it was fit on)
artifact.fold # the FoldSpec, or None for a single unfolded model
load_artifact warns, but does not fail, if the artifact was
written by a different hypline version. Treat this as provenance
information rather than a hard incompatibility.
API reference¶
API documentation for loading, inspecting, and saving encoding results.
Loading¶
hypline.encoding.load_eval ¶
load_eval(path: str | Path) -> xr.Dataset
Open a saved eval netCDF and return the subsettable xr.Dataset.
The controlled read path (mirrors save_eval): pins the engine and parses
fold_cells back from its JSON string to list[list[CellKey]] — reconstructing
each cell via CellKey(**cell) so loaded keys hash and compare against live
ones (a plain dict never would, since CellKey.__eq__ rejects non-CellKey).
Kept thin — no analysis logic — so the storage boundary stays in exactly these
two functions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to a saved eval netCDF file. |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
The eval dataset; |
hypline.encoding.load_artifact ¶
load_artifact(path: str | Path) -> EncodingArtifact
Load an encoding artifact from its .joblib blob.
Logs a warning (does not fail) on a hypline_version mismatch read from the
sidecar — a version skew is a provenance signal, not a hard incompatibility here.
A missing sidecar silently skips the version check.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the artifact |
required |
Returns:
| Type | Description |
|---|---|
EncodingArtifact
|
The artifact with fitted weights as numpy arrays (converted at save time), so it loads and predicts without torch or CUDA. |
Result types¶
The artifact structure and its parts.
hypline.encoding.EncodingArtifact
dataclass
¶
On-disk encoding result: a shared recipe plus one-or-more fitted models.
Filters that shaped the cell set live on recipe.bids_filters (X identity),
not here.
Attributes:
| Name | Type | Description |
|---|---|---|
recipe |
XRecipe
|
Shared X identity; every model here was built from it. |
sub_id |
str
|
Subject the models were fit on. |
fold |
FoldSpec | None
|
Fold configuration these models were produced under, or |
models |
list[FittedModel]
|
The fitted models: one when unfolded, one per fold otherwise. |
universe |
set[CellKey] | None
|
Bounds the OOS cell set for fold groups; |
hypline.encoding.XRecipe
dataclass
¶
Everything needed to rebuild X identically on another subject.
One source of truth for X identity so the train-time writer and the
predict-time rebuilder cannot drift. device is excluded — it is a
runtime/hardware choice, not part of X identity, and stays on
EncodingConfig.
Attributes:
| Name | Type | Description |
|---|---|---|
features |
dict[str, tuple[str, str | None]]
|
Feature ref name -> its |
confounds |
dict[str, tuple[str, str | None]]
|
Confound ref name -> its |
bold_space |
SurfaceSpace | VolumeSpace
|
Target BOLD space; surface (e.g. |
bold_desc |
str
|
|
downsample |
FeatureDownsampleMethod
|
Method mapping feature time series onto the BOLD TR grid. |
bids_filters |
list[str]
|
Extra BIDS filters constraining the cell set — the sole record of
which tasks/runs/conditions shaped X. |
delays |
list[int]
|
FIR delays (in TRs) stacked per regressor, giving the model its HRF lag basis. |
alphas |
list[float]
|
Ridge penalties searched per band during inner-CV. |
split |
bool
|
Whether himalaya keeps per-band prediction shares ( |
col_slices |
dict[str, slice]
|
Band key -> its column block in X. Empty at construction; |
hypline.encoding.FittedModel
dataclass
¶
One fitted model and the cell set it was fit on.
Attributes:
| Name | Type | Description |
|---|---|---|
pipeline |
Pipeline
|
The fitted banded-ridge pipeline: a |
train_cells |
set[CellKey]
|
Post-filter |
hypline.encoding.FoldSpec
dataclass
¶
One fold configuration: the cell axis to fold over and the fold count.
Internal carrier for the paired fold_by/n_folds constructor args; the
public surface stays flat.
Attributes:
| Name | Type | Description |
|---|---|---|
by |
str
|
Cell axis to fold over (e.g. |
n |
int | Literal['loo']
|
Fold count, or the |
Saving¶
The CLI commands write results for you. Use these functions directly if you need to save an eval or model artifact yourself.
hypline.encoding.save_eval ¶
save_eval(ds: Dataset, path: str | Path) -> None
Write an analyze Dataset to self-contained netCDF-4 at path.
The single storage seam (with load_eval): serializes the one nested value
fold_cells to a JSON string (netCDF attrs hold only scalars/strings/numeric
arrays), leaving the rest of ds — which analyze already built with
attr-safe values — untouched. Does not mutate the caller's ds.
Each CellKey serializes via dict(cell.items()); load_eval inverts this
with CellKey(**cell), so the round-trip is lossless and both sides stay live
CellKeys (entity values are uniformly str — filename entities by parse,
sidecar metadata by _validate_segment_records — so JSON preserves them
exactly).
hypline.encoding.save_artifact ¶
save_artifact(artifact: EncodingArtifact, path: str | Path) -> None
Dump artifact to path (.joblib) plus a non-pipeline JSON sidecar.
Forces fitted weights to numpy before the joblib dump (see _numpyfy_fitted)
so the blob loads without torch. The sidecar mirrors everything except the
pipeline — recipe, per-model train cell sets, fold, universe, and
hypline_version — making provenance greppable without unpickling.