Cardioception Breathwork HRD

This repository contains the breathwork study version of the Cardioception Heart Rate Discrimination task. It is configured for the Nonin USB pulse oximeter and adds a startup dialog for research assistants to enter:

• Participant ID
• Breathwork timing: 1 for before breathwork or 2 for after breathwork

The task can be run by double-clicking the launcher files in the repository root, or from the command line when troubleshooting.

Equipment

• A computer with Conda, Anaconda, or Miniforge installed
• A USB mouse
• A Nonin USB pulse oximeter
• This repository cloned locally

Install The Environment

The task uses one repo-local Conda environment:

conda-envs/cardioception-hrd

Set it up once on each computer.

macOS

Open Terminal in the repository root and run:

./scripts/setup_cardioception_env.sh

If macOS says the setup script is not executable, run:

chmod +x scripts/setup_cardioception_env.sh
./scripts/setup_cardioception_env.sh

Windows

Open Anaconda Prompt or Miniforge Prompt in the repository root and run:

scripts\setup_cardioception_env.bat

The setup script creates the environment, installs the task, and checks that the required packages can load.

Run By Double-Clicking

Connect the Nonin device and USB mouse before starting the task.

macOS

Double-click:

Run_HRD.command

If macOS blocks the file because it was downloaded, right-click Run_HRD.command, choose Open, and approve it once.

If the file is not executable, run this once from Terminal:

chmod +x Run_HRD.command

Windows

Double-click:

Run_HRD.bat

The launcher opens a command window, starts the HRD task, and keeps the window open if there is an error.

Desktop Shortcuts

You can create Desktop shortcuts to the launcher files:

• macOS: right-click Run_HRD.command, choose Make Alias, then move the alias to the Desktop.
• Windows: right-click Run_HRD.bat, choose Show more options, then Send to > Desktop (create shortcut).

Do not commit machine-specific Desktop shortcut files. Commit the launcher scripts instead.

Startup Dialog

When the task starts, a popup asks for:

• Participant ID
• Breathwork timing

Use:

• 1 - Before breathwork for the pre-breathwork HRD task
• 2 - After breathwork for the post-breathwork HRD task

The participant ID and breathwork timing must be correct before the task starts. If the popup cannot open on a lab computer, the launcher falls back to asking for the same fields in the command window.

Output Files

By default, data is saved under:

data/<participant-id><session>/

The default session is HRD plus the breathwork timing code:

• Participant 1 before breathwork saves to data/1HRD1/
• Participant 1 after breathwork saves to data/1HRD2/

The main trial file is updated after every completed trial:

<participant-id><session>.txt

The trial file includes:

• BreathworkPhaseCode
• BreathworkPhase

If the task is interrupted after at least one completed experimental trial, it also saves partial output files.

Run From Command Line

Command-line running is useful for troubleshooting, explicit serial ports, or non-default settings.

Activate The Environment

macOS:

conda activate ./conda-envs/cardioception-hrd

Windows:

conda activate .\conda-envs\cardioception-hrd

Basic Run

From the repository root:

python scripts/run_hrd_nonin.py

This still opens the startup dialog for participant ID and breathwork timing.

Bypass The Startup Dialog

Before breathwork:

python scripts/run_hrd_nonin.py --participant-id 1 --breathwork-phase 1

After breathwork:

python scripts/run_hrd_nonin.py --participant-id 1 --breathwork-phase 2

The older --subject-num flag still works as an alias for --participant-id.

Explicit Serial Port

The script tries to auto-detect the Nonin serial port. If auto-detection fails, pass the port manually.

macOS example:

python scripts/run_hrd_nonin.py --serial-port /dev/cu.usbmodemXXXX

Windows example:

python scripts/run_hrd_nonin.py --serial-port COM5

On Windows, the COM port can be checked in Device Manager.

On macOS, possible USB serial ports can be listed with:

ls /dev/cu.usb* /dev/tty.usb*

Useful Optional Flags

Run windowed:

python scripts/run_hrd_nonin.py --windowed

Skip the tutorial:

python scripts/run_hrd_nonin.py --skip-tutorial

Change trial counts:

python scripts/run_hrd_nonin.py --intero-trials 40 --extero-trials 20

Swap mouse response buttons:

python scripts/run_hrd_nonin.py --mouse-more-button left --mouse-less-button right

Show all command-line options:

python scripts/run_hrd_nonin.py --help

Troubleshooting

If the launcher says it cannot find the Python environment, install the environment first using the instructions above.

If setup partly failed or the environment seems broken, delete the environment folder and run the setup script again.

macOS:

rm -rf conda-envs/cardioception-hrd
./scripts/setup_cardioception_env.sh

Windows:

rmdir /s /q conda-envs\cardioception-hrd
scripts\setup_cardioception_env.bat

If startup stops with libsndfile.dll, _soundfile_data, or soundfile errors, the existing environment is missing PsychoPy's native audio dependency. From Anaconda Prompt or Miniforge Prompt in the repository root, run:

conda install --prefix .\conda-envs\cardioception-hrd -c conda-forge libsndfile pysoundfile "pandas>=2.2.3" requests tqdm

The double-click launchers run scripts\check_nonin_env.py before starting the task, so missing Python packages or native audio libraries should be reported before the task window opens.

If data already exists for the same participant and session, the task stops to avoid overwriting data. Use the correct breathwork timing, or use a unique participant ID/session if you are intentionally repeating a run. The error message lists the exact result folder and existing participant files to move/delete if the old run should be discarded.

If the Nonin port is not detected automatically, run from the command line with --serial-port.

When the Nonin device is missing, unplugged, busy, or not recognised, the task prints a Nonin pulse oximeter connection problem message. That message lists the serial ports currently visible to Python and gives the exact --serial-port command format to try next.

Analysis

Analysis materials remain in R_analysis/ and docs/source/examples/. For the breathwork task workflow, the key acquisition instructions are in this README.

Credit

This study workflow is based on Cardioception by Nicolas Legrand, Micah Allen, and the Embodied Computation Group. The acquisition workflow here has been adapted for the breathwork HRD protocol.