From 6bda649b1b0c8eed372fb1953754b01cac154785 Mon Sep 17 00:00:00 2001 From: Micah Allen Date: Thu, 6 Nov 2025 11:58:27 +0100 Subject: [PATCH 1/5] docs: highlight hierarchical modelling toolbox --- README.md | 64 ++++++++++++++++++++++++------------------------------- 1 file changed, 28 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index e1230dc..05400ca 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ This repository reflects the version cited in peer-reviewed publications and is *** +# 📢 2025 Update – Hierarchical Modelling Toolkit + +> 📢 **New in 2025:** We released the [Hierarchical Interoception modelling toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception) alongside the preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full). This toolkit delivers turnkey hierarchical Bayesian analyses, normative priors, and power-analysis resources for Heart Rate Discrimination and related tasks. We strongly recommend using it to model data collected with Cardioception. + # Cardioception cardioception @@ -19,42 +23,12 @@ This repository reflects the version cited in peer-reviewed publications and is The Cardioception Python Package - Measuring Interoception with Psychopy - implements two measures of cardiac interoception (cardioception): 1. The **Heartbeat counting task** developed by Rainer Schandry1,2. This task cardiac measures 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. -2. The **Heart Rate Discrimination Task** 3 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. +2. The **Heart Rate Discrimination Task** 3 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 *Legacy analysis resources* 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 use the [Nonin 3012LP Xpod USB pulse oximeter](https://www.nonin.com/products/xpod/) together with [Nonin 8000SM 'soft-clip' fingertip sensors](https://www.nonin.com/products/8000s/). 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...). The documentation can be found under the following [link](https://embodied-computation-group.github.io/Cardioception/#). -## 📊 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](R_analysis/README.md). - -### 📈 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. - ## How to cite? If you are using cardioception in a publication we ask you to cite the following paper: @@ -167,6 +141,22 @@ call [path to your environment */conda.bat] activate pause ``` +# Hierarchical Interoception Modelling Toolbox + +To analyse Heart Rate Discrimination (HRD) and related interoceptive datasets collected with Cardioception, we now recommend the dedicated [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). The companion preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full) details the models, validation, and normative priors included in the release. + +Key resources provided by the toolbox: +- Hierarchical psychometric models for HRD and RRST data implemented in Stan/BRMS, with extensive recovery and validation tests. +- Normative priors and summaries derived from large reference datasets to plug directly into your own analyses. +- A power-analysis suite (R Markdown + Shiny app) for exploring sample-size/trial requirements under different effect sizes. + +**Quick start:** +1. Clone the repository and run `setup.R` to install dependencies. +2. Open `app & demo/BRMS demo.Rmd` for a full HRD workflow that can be adapted to Cardioception exports. +3. Launch the Shiny power-analysis app (`app & demo/shiny app.R`) to plan upcoming HRD studies. + +Please cite the preprint above when reporting results derived from the toolbox, and reference Cardioception for data acquisition. + # Tasks ## The Heartbeat Counting task @@ -183,11 +173,13 @@ By default, this task implements the version used in recent publications 3< This task implements an adaptive psychophysical procedure for estimating participants' ability to discriminate their heart rate. On each trial, participants attend to their heartbeat sensations for five seconds and estimate their average heart rate. Immediately following this period, a cardiac feedback stimulus of 5 tones is played at a particular BPM frequency. The frequency is determined as their estimated average BPM plus or minus an intensity value that is updated by an adaptive staircase procedure (up/down or psi). -# Analyses +# Legacy analysis resources + +The resources below remain available for teams who depend on the historical Cardioception workflows. For new projects, we recommend transitioning to the [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). -## 📊 Recommended: R Analysis +## 📊 R analysis scripts (maintained legacy) -**For comprehensive data analysis, we recommend using our R analysis scripts located in the `R_analysis/` directory.** +**R-based analyses live in the `R_analysis/` directory and continue to receive maintenance for backwards compatibility.** The R analysis provides: - **Individual subject analysis** with reaction time plots and signal detection theory metrics @@ -202,9 +194,9 @@ The R analysis provides: For complete documentation and examples, see the [R Analysis README](R_analysis/README.md). -## 📈 Python Analysis (Outdated) +## 📈 Python notebooks (archived) -*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 notebooks are provided for reference only and are no longer actively maintained. For hierarchical Bayesian modeling, use the Hierarchical Interoception toolbox or the R analysis scripts above.* ### Task reports From 0b77a17adfbb6e2cd5e3d2a92bb6b9e1b6fc57ac Mon Sep 17 00:00:00 2001 From: Micah Galen Allen <42416756+micahgallen@users.noreply.github.com> Date: Thu, 6 Nov 2025 12:02:10 +0100 Subject: [PATCH 2/5] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 05400ca..bc89594 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This repository reflects the version cited in peer-reviewed publications and is # 📢 2025 Update – Hierarchical Modelling Toolkit -> 📢 **New in 2025:** We released the [Hierarchical Interoception modelling toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception) alongside the preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full). This toolkit delivers turnkey hierarchical Bayesian analyses, normative priors, and power-analysis resources for Heart Rate Discrimination and related tasks. We strongly recommend using it to model data collected with Cardioception. +> 📢 **New in 2025:** We released the [Hierarchical Interoception modelling toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception) alongside the preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1). This toolkit delivers turnkey hierarchical Bayesian analyses, normative priors, and power-analysis resources for Heart Rate Discrimination and related tasks. We strongly recommend using it to model data collected with Cardioception. # Cardioception From a3b012b9ef9d8f28450a019d6fbb48bdd0c74f3c Mon Sep 17 00:00:00 2001 From: Micah Galen Allen <42416756+micahgallen@users.noreply.github.com> Date: Thu, 6 Nov 2025 12:02:26 +0100 Subject: [PATCH 3/5] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bc89594..3e94d3f 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ pause # Hierarchical Interoception Modelling Toolbox -To analyse Heart Rate Discrimination (HRD) and related interoceptive datasets collected with Cardioception, we now recommend the dedicated [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). The companion preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full) details the models, validation, and normative priors included in the release. +To analyze Heart Rate Discrimination (HRD) and related interoceptive datasets collected with Cardioception, we now recommend the dedicated [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). The companion preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full) details the models, validation, and normative priors included in the release. Key resources provided by the toolbox: - Hierarchical psychometric models for HRD and RRST data implemented in Stan/BRMS, with extensive recovery and validation tests. From f265ec8ac80b7beacce55fe0e4b9fa64e668cd2c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 11:02:47 +0000 Subject: [PATCH 4/5] Initial plan From 9e3ec82096b45741d5d85eaae7e3e062d62b4f35 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 11:07:04 +0000 Subject: [PATCH 5/5] docs: remove .full suffix from bioRxiv URL for consistency Co-authored-by: micahgallen <42416756+micahgallen@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e94d3f..12a9291 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ pause # Hierarchical Interoception Modelling Toolbox -To analyze Heart Rate Discrimination (HRD) and related interoceptive datasets collected with Cardioception, we now recommend the dedicated [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). The companion preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1.full) details the models, validation, and normative priors included in the release. +To analyze Heart Rate Discrimination (HRD) and related interoceptive datasets collected with Cardioception, we now recommend the dedicated [Hierarchical Interoception toolbox](https://github.com/embodied-computation-group/Hierarchical-Interoception). The companion preprint [*Hierarchical Bayesian Modelling of Interoceptive Psychophysics*](https://www.biorxiv.org/content/10.1101/2025.08.27.672360v1) details the models, validation, and normative priors included in the release. Key resources provided by the toolbox: - Hierarchical psychometric models for HRD and RRST data implemented in Stan/BRMS, with extensive recovery and validation tests.