Skip to content

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_band is 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_band appears 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; corr is subsettable by .sel(band=…, role=…).

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 .joblib blob.

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 None when unfolded (a single model).

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; None for a single model, whose OOS is the target subject's available cells minus its train set.

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 (kind, desc) selector. Iteration order fixes X's feature-band column layout, so it is load-bearing, not incidental.

confounds dict[str, tuple[str, str | None]]

Confound ref name -> its (kind, desc) selector. All confounds collapse into one shared ridge band, so within-band order is irrelevant (a single alpha covers them).

bold_space SurfaceSpace | VolumeSpace

Target BOLD space; surface (e.g. fsaverage6) or volume.

bold_desc str

desc entity of the target BOLD (e.g. denoised) — selects which derivative the model is fit against.

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. task is an ordinary corpus filter here; only sub/space/feat/desc are reserved and cannot appear.

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 (split=True) rather than only the summed prediction.

col_slices dict[str, slice]

Band key -> its column block in X. Empty at construction; train fills it from the assembled data. Build order is screens, features, confounds — the band axis labels downstream must match this order.

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 ColumnKernelizer that delays and linear-kernelizes each band (StandardScaler -> CellDelayer -> Kernelizer, screens skipping the scaler), scored by MultipleKernelRidgeCV.

train_cells set[CellKey]

Post-filter row_slices key set — the cells actually fit on.

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. run).

n int | Literal['loo']

Fold count, or the "loo" sentinel for leave-one-out.

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.