`entity-state-to-adaptive-cognitive-load`

entity-state-to-adaptive-cognitive-load scores cognitive load against a rolling personal baseline. It uses gaze, pupil and heart-rate data and emits one series channel.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. That extraction emits one record per entity, so an eye tracker and a wearable produce separate records at the same time stamp. The node merges records by time stamp and matches entities by the components they carry (gaze, pupilometry, biometric_sensor), never by entity name. The merged rows feed a heuristic that adapts to the individual over the session.

It differs from entity-state-to-cognitive, which uses a trained model with fixed weights. No node consumes this output today other than a dashboard.

When to use

Use this node when the capture includes heart rate alongside eye tracking and you want a score that adapts to the individual rather than an absolute model score.

Pipeline position


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

The node reads the latest output of one parent.

Configuration

Configuration is optional.

Key	Type	Required	Default	Description
`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.
`biometricsField`	string	No	`biometric_sensor`	Component field name for biometric readings.
`heartRateReadingName`	string	No	`HeartRate`	Reading name inside the biometric component that carries heart rate.
`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	`adaptive-cognitive-load`	Channel id.
`channelName`	string	No	`Adaptive Cognitive Load`	Display name.
`groupId`	string	No	`cognitive-load`	Group id. The group display name is always `Cognitive Load`.

Output

A data service payload with one series channel.


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

timeMs is the start of each scoring window in Unix epoch milliseconds.
Missing pupil values are recorded as -1.0 and missing heart rate as not a number. The heuristic treats both as absent.
The personal baseline is reset for every task, so sessions processed by the same runner do not influence each other.

Limitations

One parent, latest output only.
The node fails when fewer than 10 seconds of samples are available, or when no entity carries any of the three components.
The score scale comes from the heuristic and is not the same as the entity-state-to-cognitive model scale. Do not mix the two on one gauge.

entity-state-to-cognitive scores with a trained model.
CognitiveLoad (Next) renders a series as a gauge.
ComposableChart (Next) renders the series as a line.

HEAT documentation team. Last updated 2 October 2026.

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