Cardioception Toolbox#
Cardioception is an open-source Python toolbox for studying how people perceive their own heartbeat. Built on PsychoPy, it provides four tasks: Heart Rate Discrimination, Heartbeat Counting, the Phase Adjustment Task, and Heartbeat Synchrony Discrimination.
The tasks examine different aspects of cardiac perception, from judgements of heart rate to the perceived timing of individual beats. They share a common session setup and output directory structure. The task pages explain each method’s procedure, measures, and limitations; the HRD tutorials cover data inspection and analysis.
Note
This is the official Cardioception, developed by Micah Allen and the Embodied Computation Group at Aarhus University, and originally funded by a Lundbeckfonden Fellowship to Micah Allen. It is the version cited in the publications listed on the cite page.
The tasks#
Task |
What participants do |
Main measures |
Reference |
Status |
|---|---|---|---|---|
Judge whether a sequence of tones is faster or slower than their own heart rate |
Bias and precision of heart rate judgements, with optional confidence ratings |
Established |
||
Count their heartbeats during intervals of different lengths |
Reported heartbeat counts relative to recorded counts |
Established |
||
Adjust the delay of tones until they match their perceived heartbeat |
The delay chosen, and its consistency across trials |
Plans et al., 2021; ECG version after Hodgetts et al., 2026 |
Beta |
|
Judge whether tones played at different delays after each heartbeat are synchronous with it |
Perceived timing of the heartbeat, and its temporal precision |
New in Cardioception; see the design page |
Beta |
|
Judge whether stimuli presented at one of two fixed delays after each heartbeat are simultaneous with it or delayed |
Discrimination of synchronous from delayed stimuli |
Coming soon |
||
Judge whether tones at one of several fixed delays, from 0 to 500 ms after each heartbeat, are simultaneous with it |
Proportion of tones judged simultaneous at each delay |
Coming soon |
Tasks in beta are close to feature complete and are still being rigorously validated.
The HRD and the HBC run with a USB pulse oximeter or with an ECG or PPG device over Lab Streaming Layer. The synchrony tasks time each tone from the R-wave, so they need an ECG over LSL. The tasks page sets the four available tasks side by side and explains what each can and cannot establish.
Where to go#
To get started, install the package, connect a recording device, then run a session. Each task page describes its procedure, parameters, and output files.
The changelog lists what changed in 1.0 and how to migrate scripts written for 0.7.
Analyzing your data#
Cardioception collects data; it does not analyze it. For HRD data, the companion Hierarchical Interoception toolbox, described in Courtin et al. (2026), provides validated psychometric models and normative priors. The tutorials walk through the workflow, from checking your data to fitting hierarchical models with covariates.
Help#
Report bugs and ask questions in the issue tracker. For questions about the tasks and study design, contact Micah Allen at micah@cfin.au.dk.
