Running a session#

All four tasks use the same basic workflow: the parameters submodule builds a settings dictionary, and the task submodule uses it to run the session. This page covers the shared session settings and output structure. Each task page provides a complete example.

The wrappers#

The wrappers folder of the repository has a ready-to-run script for each task. Each opens a dialog for the session settings, then runs the task with the defaults of the published version:

python wrappers/hrd.py

Wrapper	Task	Device	Dialog fields
`hrd.py`	HRD	pulse oximeter	participant, session, serial port, setup, response device, language
`hrd_lsl.py`	HRD	ECG or PPG over LSL	participant, session, stream, channel, signal type, response device, language
`hbc.py`	HBC	pulse oximeter	participant, session, serial port, setup, language
`pat_lsl.py`	PAT	ECG over LSL	participant, session, stream, channel, mode, exteroceptive control, language
`hsd_lsl.py`	HSD	ECG over LSL	participant, session, stream, channel, axis, response device, language

A pip install does not include this folder. Download the one you need from the table, save it in your own folder and edit it there.

Before each session#

Check the recording device: python -m cardioception.check_device for the oximeter, or the live stream in the device’s own program for LSL.
Do a dry run before the participant arrives, with the test setup of the HRD and HBC wrappers or on yourself, to confirm the task starts and saves.
Set the volume with the participant’s headphones on.
Confirm the serial port or the stream name and channel the wrapper will ask for.

Where the data goes#

Each run gets its own directory under data/ in the working directory, or under resultPath when it is given:

data/sub-<participant>/ses-<session>/run-<YYYYMMDD-HHMMSS>/
  manifest.json
  session.log
  sub-<participant>_ses-<session>_run-<timestamp>_final.txt
  ...

The timestamp distinguishes successive runs. File names also include the participant, session, and run identifiers, so files remain identifiable when copied out of their original directory.

The task writes manifest.json when it builds the parameters, before the first trial. The manifest records the task and package version, start time, random seed, response device, language, setup, confidence scale, and recording device. These settings remain available even if the session is aborted. session.log records console messages with timestamps.

The task writes *_final.txt when the session ends, with one row per trial. The HRD, HBC, and HSD also save the accumulated trial rows to *_behaviour.txt after each trial. Additional files include physiological recordings, staircase posteriors, and parameters. These vary by task and are described on the individual task pages.

The seed of the session’s random generator is drawn when none is given and recorded in the manifest. Passing it back as seed= draws the same session again.

Languages#

The instructions are shown in the language passed as language, which names a YAML file in the task’s texts/ folder:

Task	Languages
HRD	`english`, `danish`, `danish_children`, `french`, `german`
HBC	`english`, `german`
PAT	`english`, `danish`
HSD	`english`

english is the default everywhere. Each task’s languages.available() returns the list, and an unknown language raises an error before any window opens. To add a language, copy english.yaml, translate the values and pass the new file’s name.

Confidence scales#

Confidence ratings use a cardioception.scales.ConfidenceScale object. Four scales are included:

Scale	Kind	Range
`VAS_0_100`	continuous slider	0 to 100
`DISCRETE_1_7`	discrete	1 to 7
`DISCRETE_1_10`	discrete	1 to 10
`VAS_SIGNED_100`	continuous, signed	-100 to 100

The HRD defaults to VAS_0_100 with the mouse and DISCRETE_1_10 with the keyboard; the HBC to DISCRETE_1_7; the PAT and HSD to DISCRETE_1_10. A default scale takes its end labels from the chosen language. Pass confidenceScale= to use another, with with_labels to set the labels:

from cardioception.scales import VAS_0_100

parameters = getParameters(..., confidenceScale=VAS_0_100.with_labels(["Guess", "Certain"]))

Each result row contains the original rating and a version rescaled to 0 to 1, ConfidenceUnit. It also records the scale definition in ConfidenceScale, ConfidenceLow, ConfidenceHigh, ConfidenceGranularity, ConfidenceLevels, and ConfidenceSigned. These columns identify the scale used in each session without requiring the parameters file.

A Windows shortcut#

Once a wrapper is edited, a .bat file starts the task with a double click. With the virtual environment from the installation:

call C:\Users\you\cardio\cardioception-env\Scripts\activate.bat
python C:\Users\you\cardio\hrd.py
pause

With conda, activate the cardioception environment rather than the base one:

call C:\Users\you\miniconda3\condabin\conda.bat activate cardioception
python C:\Users\you\cardio\hrd.py
pause

Next step#

Go to the page of the task you are running: Heart Rate Discrimination, Heartbeat Counting, Phase Adjustment Task or Heartbeat Synchrony Discrimination. The tasks sets them side by side.