Cardioception#

🧠 Official Repository Notice#

This is the original and officially maintained version of the Cardioception software package, co-created by Micah Allen and the Embodied Computation Group at Aarhus University (2019–2022). Development of this package was funded by a Lundbeckfonden Fellowship to Micah Allen.

This repository reflects the version cited in peer-reviewed publications and is actively maintained by the Embodied Computation Group.

⚠️ We cannot guarantee the accuracy, validity, or scientific reproducibility of any unofficial forks or versions of this software. Please use this repository for all scientific work, installations, and citation.

The Cardioception Python Package - Measuring Interoception with Psychopy - implements two measures of cardiac interoception (cardioception):

The Heartbeat counting task (HBC), also known as the Heartbeat tracking task, developed by Rainer Schandry [Dale and Anderson, 1978, Schandry, 1981]. This task measures cardiac interoception by asking participants to count their heartbeats for a given period of time. An accuracy score is then derived by comparing the reported number of heartbeats and the true number of heartbeats.
The Heart Rate Discrimination task [Legrand et al., 2022] implementing an adaptive psychophysical measure of cardiac interoception where participants have to estimate the frequency of their heart rate by comparing it to tones that can be faster or slower. By manipulating the difference between the true heart rate and the presented tone using different staircase procedures, the bias (threshold) and precision (slope) of the psychometric function can be estimated either online or offline (see Analyses below), together with metacognitive efficiency.

These tasks can run using minimal experimental settings: a computer and a recording device to monitor the heart rate of the participant. The default version of the task uses the Nonin 3012LP Xpod USB pulse oximeter together with Nonin 8000SM ‘soft-clip’ fingertip sensors. This sensor can be plugged directly into the stim PC via USB and will work with Cardioception without any additional coding required. The tasks can also integrate easily with other recording devices and experimental settings (ECG, M/EEG, fMRI…).

📊 Data Analysis#

🎯 Recommended: R Analysis#

For comprehensive data analysis, we recommend using our R analysis scripts located in the R_analysis/ directory.

The R analysis provides:

Individual subject analysis with reaction time plots and signal detection theory metrics
Group-level hierarchical analysis
Bayesian analysis using Stan models
Comprehensive visualization of results

🚀 Quick Start:

Individual subject analysis: See R_analysis/Example scripts/Example_analysis_simple.Rmd
Group-level analysis: See R_analysis/Example scripts/Example_analysis_Hierarchical.Rmd
Bayesian analysis: See R_analysis/Example scripts/Example_analysis_bayesian.Rmd

For complete documentation and examples, see the R Analysis README.

📈 Python Analysis (Outdated)#

Python analysis examples are available but are outdated and may not be maintained. For hierarchical Bayesian modeling, we strongly recommend using the R analysis approach above.

Python users can find examples in the documentation, but these are primarily for reference. The Python analysis includes:

Basic preprocessing and reporting functions
Template notebooks for data visualization
Outdated Bayesian modeling examples

⚠️ Important: Users interested in hierarchical Bayesian modeling should refer to the R analysis code, which provides more comprehensive and up-to-date implementations.

Looking for help?#

If you have questions regarding the tasks or want discuss data analysis, please contact Micah Allen directly.

If you want to report a bug, you can open an issue on the GitHub page.

Development#

Authors: Nicolas Legrand and Micah Allen, 2019-2022. Contact: micah@cfin.au.dk Maintained by the Embodied Computation Group, Aarhus University.