You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Cardioception Python Package - Measuring Interoception with Psychopy - implements two measures of cardiac interoception (cardioception):
7
10
1. The *Heartbeat counting task* developed by Rainer Schandry<sup>1,2</sup>
8
-
2. a novel *Heart Rate Discrimination Task* implementing an adaptive psychophysical measure for measuring cardioception.
11
+
2. a novel *Heart Rate Discrimination Task* <sup>5</sup> implementing an adaptive psychophysical measure for measuring cardioception.
12
+
13
+
# How to cite Cardioception?
14
+
15
+
If you are using cardioception in a publication we ask you to cite the following paper:
16
+
17
+
>Legrand, N., Nikolova, N., Correa, C., Brændholt, M., Stuckert, A., Kildahl, N., Vejlø, M., Fardo, F., & Allen, M. (2021). The heart rate discrimination task: a psychophysical method to estimate the accuracy and precision of interoceptive beliefs. bioRxiv 2021.02.18.431871. https://doi.org/10.1101/2021.02.18.431871
18
+
19
+
If you are using Systole to interact with your recording device (this is the default behavior in cardioception), you might also cite the following reference:
20
+
21
+
> Legrand, N., & Allen, M. (2020). Systole: V 0.1.2—September 2020 (0.1.2) [Computer software]. Zenodo. https://doi.org/10.5281/ZENODO.3607912
9
22
10
-
Currently the toolbox natively supports 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/) as well as Remote Data Access (RDA) via BrainVision Recorder together with Brain product ExG amplifier [](https://www.brainproducts.com/>).
11
23
12
24
# Installation
13
25
14
-
* Cardioception can be installed using pip:
15
-
`pip install cardioception`.
26
+
* Cardioception can be installed uing `pip install cardioception`.
16
27
17
28
## Dependencies
18
29
19
-
We recommend to use the last install of Anaconda for Python 3.8 or latest (see https://www.anaconda.com/products/individual#download-section).
30
+
Cardioception has been tested with Python 3.7. We recommend to use the last install of Anaconda for Python 3.7 or latest (see https://www.anaconda.com/products/individual#download-section).
31
+
32
+
Make sure that you have the following packages installed and up to date before running cardioception:
33
+
34
+
*[psychopy](https://www.psychopy.org/) can be installed with `pip install psychopy`.
35
+
36
+
*[systole](https://systole-docs.github.io/) can be installed with `pip install systole`.
*[Systole](https://systole-docs.github.io/) can be installed using pip:
27
-
`pip install systole`.
53
+
**NOTE**
54
+
The version provided here are the ones used when testing and runing cardioception locally, and are often the last ones. For several packages however, older version might also be compatibles.
28
55
29
-
Notes: Cardioception will automatically copy the images and sound files necessary to run the task correctly (~ 200 Mo). These files will be removed if you uninstall the package using `pip uninstall cardioception`.
56
+
Cardioception will automatically copy the images and sound files necessary to run the task correctly (~ 200 Mo). These files will be removed if you uninstall the package using `pip uninstall cardioception`.
30
57
31
-
## Run tasks
58
+
## Physiological recording
32
59
33
-
Each task contains a `parameters` and a `task` submodule describing the experimental parameters and the Psychopy script respectively. Once the package has been installed, you can run the task (e.g. here the Heart rate Discrimination task) using the following code snippet:
60
+
Both the Heartbeat counting task (HBC) and the heart rate discrimination task (HRD) require access to physiological recording device during the task to estimate the heart rate or count the number of heartbeats in a given time window. Cardioception natively supports:
61
+
* 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/)
62
+
* Remote Data Access (RDA) via BrainVision Recorder together with [Brain product ExG amplifier](https://www.brainproducts.com/>).
63
+
64
+
The package can easily be extended and integrate other recording devices by providing another recording class that will interface with your own devices (ECG, pulse oximeters, or any king of recording that will offer precise estimation of the cardiac frequency).
65
+
66
+
# Run the tasks
67
+
68
+
Each task contains a `parameters` and a `task` submodule describing the experimental parameters and the Psychopy script respectively. Several changes and adaptation can be parametrized just by passing arguments to the parameters functions. Please refer to the API documentation for details.
69
+
70
+
## From the command line
71
+
72
+
*(forthcoming)*
73
+
## Using a script
74
+
75
+
Once the package has been installed, you can run the task (e.g. here the Heart rate Discrimination task) using the following code snippet:
@@ -69,10 +111,6 @@ This module is an implementation of the classic "heartbeat counting task" (HCT)<
69
111
70
112
By default, this task implement the version used in recent publications <sup>3</sup> in which a training trial of 20s is proposed, after which the 6 experimental trials of different time-windows (25, 30, 35,40, 45 and 50s) occurred in a randomized order. The trial length, the condition ('Rest', 'Count', 'Training') and the randomization can be controlled in the parameters dictionary.
71
113
72
-
73
-
## The Heartbeat Discrimination task
74
-
75
-
76
114
## The Heart Rate Discrimination task
77
115
78
116
<imgsrc= "images/HeartRateDiscrimination.png">
@@ -81,9 +119,14 @@ This task implements an adaptive psychophysical procedure for estimating partici
81
119
82
120
# Analyses
83
121
84
-
By default, the results will be saved in the `data` folder contained in each task folder.
122
+
Some of the default analyses and the Python code can be found in the report notebook templates (`./cardioception/notebooks/`). These notebooks will automatically save preprocessed data in the result folder.
85
123
86
-
The `notebooks` folder includes Jupyter notebooks documenting the recommended analyses steps for each tasks that can be used to generate reports.
124
+
More advanced subject and group-level Bayesian modeling approaches are described in the following notebooks.
125
+
126
+
| Notebook | Colab | nbViewer |
127
+
| --- | ---| --- |
128
+
| Fitting psychometric function with PyMC3 - Subject-level | [](https://colab.research.google.com/github/embodied-computation-group/Cardioception/blob/main/code/psychophysics_subjectLevel.ipynb?flush_cache=true) | [](https://nbviewer.jupyter.org/github/embodied-computation-group/Cardioception/blob/main/code/psychophysics_subjectLevel.ipynb?flush_cache=true)
129
+
| Fitting psychometric function with PyMC3 - Group-level | [](https://colab.research.google.com/github/embodied-computation-group/Cardioception/blob/main/code/psychophysics_groupLevel.ipynb?flush_cache=true) | [](https://nbviewer.jupyter.org/github/embodied-computation-group/Cardioception/blob/main/code/psychophysics_groupLevel.ipynb?flush_cache=true)
87
130
88
131
# Generate reports
89
132
@@ -109,6 +152,7 @@ for sub in subjects:
109
152
subprocess.call(command)
110
153
```
111
154
155
+
112
156
# References
113
157
114
158
1. Dale, A., & Anderson, D. (1978). Information Variables in Voluntary Control and Classical Conditioning of Heart Rate: Field Dependence and Heart-Rate Perception. Perceptual and Motor Skills, 47(1), 79–85. https://doi.org/10.2466/pms.1978.47.1.79
@@ -118,6 +162,8 @@ for sub in subjects:
118
162
3. Leganes-Fonteneau, M., Cheang, Y., Lam, Y., Garfinkel, S., & Duka, T. (2019). Interoceptive awareness is associated with acute alcohol-induced changes in subjective effects. Pharmacology Biochemistry and Behavior, 181, 69–76. https://doi.org/10.1016/j.pbb.2019.03.007
119
163
120
164
4. Hart, N., McGowan, J., Minati, L., & Critchley, H. D. (2013). Emotional Regulation and Bodily Sensation: Interoceptive Awareness Is Intact in Borderline Personality Disorder. Journal of Personality Disorders, 27(4), 506–518. https://doi.org/10.1521/pedi_2012_26_049
165
+
166
+
5. Legrand, N., Nikolova, N., Correa, C., Brændholt, M., Stuckert, A., Kildahl, N., Vejlø, M., Fardo, F., & Allen, M. (2021). The heart rate discrimination task: a psychophysical method to estimate the accuracy and precision of interoceptive beliefs. bioRxiv 2021.02.18.431871. https://doi.org/10.1101/2021.02.18.431871
121
167
122
168
# Development
123
169
This package was created and is maintained by [Nicolas Legrand](https://legrandnico.github.io/) and [Micah Allen](https://micahallen.org/) from the [ECG group](https://the-ecg.org/).
0 commit comments