Installation#

These six steps take you from installing Python to running a test session and checking a pulse signal. Example output is included so you can check your progress.

Cardioception requires Python 3.10 or 3.11. The upper limit reflects the availability of prebuilt wheels for pywinhook, which extend only to Python 3.11. The package’s version requirement prevents installation with other Python versions.

1. Install Python 3.10 or 3.11#

Download it from python.org/downloads. Pick 3.11.9 or 3.10.11: later point releases of 3.10 and 3.11 are source-only and have no Windows installer. On Windows, tick Add Python to PATH in the installer. If you already use Anaconda, skip to the conda route instead.

python --version

Python 3.10.11

Anything outside 3.10 and 3.11 means you are running a different interpreter. On Windows, py -3.10 --version selects one explicitly.

2. Make a virtual environment#

python -m venv cardioception-env
cardioception-env\Scripts\activate     # Windows
source cardioception-env/bin/activate  # macOS and Linux

After activation, the terminal prompt begins with (cardioception-env). Run the installation commands and tasks from this environment. If you close the terminal, activate the environment again before continuing.

Warning

On Windows, keep this folder somewhere short, such as C:\Users\you\cardio. Some dependencies create deeply nested paths, and Windows refuses paths over 260 characters unless long path support is enabled.

3. Install Cardioception#

Important

Version 1.0 is not on PyPI yet, so pip install cardioception-toolbox still installs 0.7.2. Until 1.0 is released, install it from the dev branch, with the LSL extra if you need it:

pip install "cardioception-toolbox[lsl] @ git+https://github.com/embodied-computation-group/Cardioception@dev"

The commands below are the ones that will apply once 1.0 is released.

pip install cardioception-toolbox

Successfully installed cardioception-toolbox-1.0.0 psychopy-2026.2.2 systole-core-0.3.1 ...

Expect this to take a few minutes: the package is small, but it pulls in PsychoPy and its Qt stack. On disk it expands to roughly 140 MB, almost all of it the pre-generated tone files the Heart Rate Discrimination task plays. The distribution is named cardioception-toolbox; the import name is cardioception.

To read ECG or PPG from a Lab Streaming Layer stream, install the extra as well:

pip install "cardioception-toolbox[lsl]"

The development version installs from the dev branch with pip install git+https://github.com/embodied-computation-group/Cardioception.git@dev.

4. Check that it imports#

The install can succeed while the package still fails to load, so check directly:

python -c "from cardioception.HRD import task; print('ok')"

ok

If the import raises an error, compare the message with the entries in Troubleshooting.

5. Run a task without hardware#

Save this as try_hrd.py and run it with python try_hrd.py. setup="test" replays a recorded pulse, so no device is needed:

from cardioception.HRD.parameters import getParameters
from cardioception.HRD import task

parameters = getParameters(participant="sub01", session="pilot", setup="test", nTrials=10)
task.run(parameters, confidenceRating=True, runTutorial=False)
parameters["win"].close()

A window opens and runs ten trials; respond with the mouse buttons. PsychoPy’s audio backend can ignore the system volume, so turn the speakers or headphones down first. The task saves the results in data/sub-sub01/ses-pilot/run-<timestamp>/.

6. Check the pulse signal#

This step is for the USB pulse oximeter. For an ECG or PPG device over LSL, skip it and go to Recording devices.

Plug the oximeter in, put a finger in the sensor and confirm the computer sees a real signal:

python -m cardioception.check_device

Using the only serial port found: COM3 (USB Serial Port (COM3))
Recording 20 s from COM3. Keep a finger in the sensor.

  samples            1500 (20.0 s)
  signal amplitude   242.7      (needs > 20)
  beats detected     29
  heart rate         87 BPM
  beat intervals     0.60 to 0.80 s, sd 0.045   (needs sd < 0.15)

  VERDICT: clean physiological signal
  Ready to collect data.

Check the signal amplitude as well as the detected beats: noise from an empty sensor can produce a plausible beat count. Recording devices explains the possible results and command options. It also covers ECG and PPG over LSL, which this command does not test.

Next step#

Continue to Recording devices to connect the device your tasks will use.

The conda route#

environment.yml at the root of the repository replaces steps 1 to 3 on Windows for people who already have Anaconda or Miniconda. It pins the interpreter to 3.10 and installs pywinhook from conda-forge, which saves building it from source. pywinhook exists only for Windows, so on Linux use environment_linux.yml, which leaves it out. There is no file for macOS; use the venv route there.

git clone https://github.com/embodied-computation-group/Cardioception.git
cd Cardioception
conda env create -f environment.yml
conda activate cardioception

Then carry on from step 4. If you do not already use conda, the venv route above involves one fewer tool.

Legacy versions#

Older versions stay available for studies that started on them.

The 0.7 line, the last before the 2026 rewrite, is kept as the legacy/0.7 branch and the v0.7.2 tag:

pip install cardioception-toolbox==0.7.2

The 0.4 line dates from the period of the Heart Rate Discrimination paper [Legrand et al., 2022] and is tagged v0.4.0 to v0.4.5. The paper’s data were collected between July and November 2020 with development code that declared version 0.3.0, before any release was tagged, and the HRD changed between the two sessions. The paper’s analysis code and data are in CardioceptionPaper; v0.4.0 (April 2021) is the first tagged release after it. The 0.4 releases pin the dependencies of their time (v0.4.5 requires PsychoPy 2020.1.2), so expect to need an older Python:

pip install git+https://github.com/embodied-computation-group/Cardioception@v0.4.3

These versions write to the old flat layout, data/<participant><session>/, rather than to the per-run directories described under Running a session. The changelog describes the change and what it means for analysis scripts.

Troubleshooting#

Error	Cause and fix
`ERROR: Package requires a different Python: 3.x not in '>=3.10,<3.12'`	Working as intended. Install 3.10 or 3.11 and build the environment from it.
`error: command 'swig.exe' failed`	Python 3.12 or later on Windows, where `pywinhook` has no wheel and tries to build from source. Use 3.10 or 3.11, or take the conda route, which supplies it prebuilt.
`ModuleNotFoundError: No module named 'pkg_resources'`	An older Cardioception with PsychoPy 2022.2.5, which imported it. Upgrade, or pin `setuptools<81`.
`OverflowError: line number table is too long`	An older PsychoPy on Python 3.10 or later. Upgrade Cardioception.
`Could not install packages due to an OSError: [Errno 2] No such file or directory: '...'` with a very long path	The Windows 260-character path limit. Move the environment somewhere shallower, or enable long path support.
`Can't connect to HTTPS URL because the SSL module is not available`	The virtual environment was built from an Anaconda interpreter. Build it from a python.org install, or use the conda route instead of `venv`.
`SerialException: could not open port`	Wrong port name, or another program is holding the device. Close anything else reading it and run `python -m cardioception.check_device --list`.
Task runs but the recording is flat	Almost always the sensor rather than the software. Re-run step 6 and read the amplitude.

If none of these match, open an issue with the full error, your operating system, and the output of python --version and pip list.