Cardioception Toolbox#

Cardioception measures cardiac interoception in Psychopy. The package is built around the Heart Rate Discrimination task (HRD), a psychophysical method that estimates how accurately and how precisely people judge their own heart rate. It also ships the classic Heartbeat Counting task.

GitHub release pip GitHub license DOI

The tasks run with minimal equipment: a computer and a device that reads the participant’s pulse. They also work with richer setups (ECG, M/EEG, fMRI) when you have them.

Important

Install the package as cardioception-toolbox:

pip install cardioception-toolbox

This is the official package, maintained by the Embodied Computation Group at Aarhus University. It is the version described in this documentation and used in our publications. Make sure the package name you install is exactly cardioception-toolbox.

The import name is still cardioception, so existing scripts do not need to be edited:

from cardioception.HRD import task

See the user guide for conda environments, dependencies and the development version.

The tasks#

Heart Rate Discrimination task#

The HRD [Legrand et al., 2022] is an adaptive psychophysical measure. Participants attend to their heartbeat sensations, then hear tones played faster or slower than their true heart rate and judge which. Staircase procedures adjust that difference from trial to trial, which gives the bias (threshold) and the precision (slope) of the psychometric function. Both can be estimated online during the task or offline afterwards.

Heartbeat Counting task#

The HBC [Dale and Anderson, 1978, Schandry, 1981], also known as the heartbeat tracking task, asks participants to count their heartbeats over a fixed period. An accuracy score compares the reported count against the true number of beats.

The package keeps this task because much of the literature rests on it. For new studies we would point you to the HRD, which separates interoceptive bias from precision and is less confounded by beliefs about heart rate. The theory page sets out that argument in full.

Recording devices#

The default setup uses the Nonin 3012LP Xpod USB pulse oximeter with Nonin 8000SM ‘soft-clip’ fingertip sensors, which plugs into the stimulus PC over USB and needs no extra code. Remote Data Access through BrainVision Recorder is also supported, and you can add other devices by writing a recording class. The user guide has the details.

Analysing your data#

For HRD data we recommend the Hierarchical Interoception toolbox, described in Courtin et al. (2026). The tutorials walk through the workflow, from checking your data to fitting hierarchical models with covariates.

Where to go next#

  • User guide for installation, dependencies and running a task

  • Theory for what the two tasks measure and why

  • Tutorials for inspecting your data, then modelling it

  • API for the parameters and task functions

  • Cite for the references to use in a publication

Getting help#

For questions about the tasks or about data analysis, contact Micah Allen directly. To report a bug, open an issue on the GitHub page.

Note

This is the original Cardioception, created by Micah Allen and the Embodied Computation Group at Aarhus University between 2019 and 2022, funded by a Lundbeckfonden Fellowship to Micah Allen. It is the version cited in the peer-reviewed publications listed on the cite page. We cannot vouch for unofficial forks, so we recommend working from this repository for research, installation and citation.

Development#

Written and maintained by Micah Allen and the Embodied Computation Group, Aarhus University. Contact: micah@cfin.au.dk