Skip to content

interpretation.md

Latest commit

 

History

History
71 lines (55 loc) · 3.93 KB

interpretation.md

File metadata and controls

71 lines (55 loc) · 3.93 KB
Raw

Interpreting cortex-score output

This document states plainly what a ScoreResult is and is not, so the numbers are used honestly. If anything here conflicts with marketing copy, this document wins.

What the numbers are

cortex-score summarizes predictions from TRIBE v2, a brain-encoding model trained on fMRI recorded while people watched videos. For a given clip it estimates a per-vertex cortical response on the fsaverage5 surface for an average subject, then aggregates that to the Yeo-17 parcellation and rolls it up into five dashboard groups.

Each network's mean_energy / peak_energy is the mean / max over time of the within-clip z-scored response magnitude for that group's parcels.

What the numbers are NOT

  • Not a brain scan. No real brain is measured. These are model predictions.
  • Not viewer engagement. They do not measure whether a real viewer paid attention, enjoyed, or remembered anything.
  • Not clinically meaningful. Nothing here is diagnostic or medical.
  • Not comparable across clips by default. Normalization is within_video: each parcel is z-scored against its own timeline in that one clip. A 0.89 "language" score on clip A and a 0.89 on clip B are not on the same axis. Cross-clip comparison needs a shared reference distribution (the reserved normalization.scope == "reference_distribution" mode).

The 5-network grouping is a product choice

The five groups (visual, language, faces, attention, motion) are a product-design grouping of Yeo-17 parcels, recorded in every result as network_group_source: "cortexia-network-groups-v1" and SHA-fingerprinted in data/manifest.json. They are not a canonical neuroscientific localization, and the group names are conveniences, not claims that the named function is what those parcels do.

Group Yeo-17 parcels Honest reading
visual VisCent, VisPeri The most defensible group: these are the visual networks in Yeo-17.
motion SomMotA, SomMotB Somatomotor networks; "motion" is a loose, content-facing label.
attention DorsAttnA, DorsAttnB, SalVentAttnA, ContA A blend of dorsal/ventral attention and a control network - broad, not a single attention system.
language ContB, TempPar Not a standard language network. Real language localizers (e.g. the Fedorenko language network) are defined differently; this is a proxy built from a control + temporo-parietal parcel. Treat as exploratory.
faces SalVentAttnB, DefaultC Not a face-selective region. There is no FFA/face-localizer here; this is a social-context proxy from a salience/ventral-attention and a default-mode parcel. Treat as exploratory.

faces and language are the weakest mappings and are labeled "exploratory" in their result description fields for exactly this reason. Do not present them as measured face- or language-selectivity.

The opt-in Schaefer-400 detail

ScoreConfig(include_schaefer_parcels=True) adds per-Schaefer-2018-parcel metrics, each tagged with its parent Yeo-17 network. This is finer-grained but carries the same caveats: predicted, within-clip-normalized, average-subject. Finer granularity is not more "real."

Machine-readable caveats

Every result already carries the caveat in-band, so a downstream consumer never has to trust out-of-band docs:

  • framing_disclaimer - the "does not measure real viewer engagement" sentence, verbatim, in every ScoreResult.
  • network_group_source - pins the grouping as a versioned product artifact.
  • each NetworkScore.description - flags the exploratory groups.
  • normalization.scope - makes the within-clip limitation explicit.

We deliberately did not add a separate free-text "caveat" field: the disclaimer + group source + per-network descriptions already encode this, and a redundant field would be one more thing to drift out of sync.