`entity-state-to-cognitive`

entity-state-to-cognitive scores cognitive load from gaze and pupil data with a bundled regression model. It emits the score as a series channel over a sliding window.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. The node reads the gaze and pupilometry components, builds features for each window, scales them with a fitted scaler and predicts with an XGBoost regressor. The prediction is clamped to the range 0 to 21. The model files ship inside the core-utils runner image under core-utils/ml_models/.

It produces a timeline, not a summary. For a session-level breakdown feed its output to cognitive-load-breakdown.

When to use

Use this node when a Next dashboard needs the CognitiveLoad gauge or a cognitive load line on a chart, and the capture includes eye-tracking gaze and pupil data.

Pipeline position


hydrate-protobuf-v2 (EntityState) -> entity-state-to-cognitive -> cognitive-load-breakdown
                                                                -> json-merge -> dashboard-v2

The node reads the latest output of one parent.

Configuration

Configuration is required. scalerPath and modelPath must be set.

Key	Type	Required	Default	Description
`scalerPath`	string	Yes	none	Path to the pickled scaler inside the runner container. The bundled file is `core-utils/ml_models/scaler_latest_2108.pkl`, resolved from the image working directory `/app`.
`modelPath`	string	Yes	none	Path to the XGBoost model JSON inside the runner container. The bundled file is `core-utils/ml_models/xgboost_regression_2108.json`.
`entriesPath`	string	No	`records[*]`	JMESPath (a query language for JSON) to the array of time-ordered records.
`entitiesPath`	string	No	`entity_state.entity`	JMESPath from each record to its entity object or array of objects.
`componentsPath`	string	No	`components`	Dotted path from an entity to its components array.
`gazeField`	string	No	`gaze`	Component field name for gaze data.
`pupilometryField`	string	No	`pupilometry`	Component field name for pupil data.
`timeField`	string	No	`packet_timestamp_unix_ms`	Dotted path to the record time stamp in milliseconds.
`realmName`	string	No	`overview`	Realm name.
`channelId`	string	No	`cognitive-load`	Channel id. A second channel named `<channelId>-timeline` is also emitted.
`channelName`	string	No	`CognitiveLoad`	Display name.
`windowSizeSeconds`	integer	No	`10`	Sliding window width in seconds.
`stepSizeSeconds`	integer	No	`1`	Step between consecutive windows in seconds.

⚠️

When the scaler or model cannot be loaded from the configured paths, the node logs a warning and falls back to an identity scaler and a model that always predicts 0. The node still succeeds, so check the paths when every score is zero.

Output

A data service payload with two series channels in group cognitive-load. Both carry the same points. The second channel id has the suffix -timeline and is the input that cognitive-load-breakdown reads by default.


{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "cognitive-load", "name": "Cognitive Load" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          { "id": "cognitive-load", "name": "cognitive-load", "groupId": "cognitive-load", "shape": "series", "data": [{ "timeMs": 1718000000000, "value": 3.2 }] },
          { "id": "cognitive-load-timeline", "name": "cognitive-load-timeline", "groupId": "cognitive-load", "shape": "series", "data": [{ "timeMs": 1718000000000, "value": 3.2 }] }
        ]
      }
    ]
  },
  "dashboard_users": []
}

timeMs is the window start, copied from the record time stamp without rebasing.
Pupil diameters of -1.0 are treated as missing.
Windows with too few samples or too little valid data are skipped.

Limitations

One parent, latest output only.
The model is trained for gaze and pupil features. Heart rate features are filled with a constant and do not influence the score.
Window and step sizes are integers in seconds.
The node fails when no window produces a score.

CognitiveLoad (Next) renders the series as a gauge.
cognitive-load-breakdown reduces the timeline to time in zone.
entity-state-to-adaptive-cognitive-load uses a personal-baseline heuristic instead of a trained model.

HEAT documentation team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.