Cardio-Audio-Sleep study

Project to study sound/omission stimulus synchronous, asynchronous and isochronous with the heartbeat.

Install

Operating System

Recommended OS: Ubuntu 22.04 LTS or 24.04 LTS, generic kernel.

Tip

On Ubuntu 24.04 LTS, Wayland is the default display server and replaces X11. In theory, it should be more performant and have lower latencies than X11. In practice, the stimulation software (PsychoPy, psychtoolbox, ...) and the rendering software (pyvistaqt, ...) don't support Wayland well yet which can lead to crash or unexpected behaviors / latencies.

Python installation

• Add the deadsnake PPA and install python 3.10 (current version supported by PsychoPy).

  $ sudo add-apt-repository ppa:deadsnakes/ppa
  $ sudo apt update
  $ sudo apt install python3.10 python3.10-venv

• Prevent installations without virtual environment (optional, good practice).

  $ sudo apt install nano  # if absent from the system
  $ nano ~/.profile

  Add the lines:

  PYTHONNOUSERSITE=1
  PIP_REQUIRE_VIRTUALENV=1
  

• Clone the project and create an environment.

  $ cd ~
  $ mkdir git
  $ git clone https://github.com/fcbg-platforms/eeg-cardio-audio-sleep

Tip

I recommend to install VSCode and use it to spawn the terminal with an activated environment. In VSCode, File -> OpenFolder then open the ~/git/eeg-cardio-audio-sleep folder just cloned, Ctrl+Shift+P -> Create New Terminal.

• Create a virtual environment.

  $ cd ~/git/eeg-cardio-audio-sleep  # if not in VSCode
  $ python3.10 -m venv .venv --copies

Tip

If you are using VSCode, a pop-up on the bottom right detects the new environment and ask if it should be the default environment for this folder. Select Yes, you will now always have this environment activated in VSCode when you open the folder ~/git/eeg-cardio-audio-sleep.

PsychoPy preparation

• Retrieve the wxPython wheel for your platform here (ubuntu only, wheels are available for the other OS).

Tip

If you run Ubuntu 24.04 LTS, or if you want, you can build the wheel from source. Run pip install wxPython, and resolve successively the displayed errors by installing the missing libraries/compilers. The build takes a couple of minutes.

• Install dependencies

  $ sudo apt install libusb-1.0-0-dev portaudio19-dev libasound2-dev libsdl2-2.0-0

• Edit ulimits

  $ sudo groupadd --force psychopy
  $ sudo usermod -aG psychopy $USER  # replace with your username
  $ sudo nano /etc/security/limits.d/99-psychopylimits.conf

  Set the content to:

  @psychopy   -  nice       -20
  @psychopy   -  rtprio     50
  @psychopy   -  memlock    unlimited
  

Install the project

Tip

Install uv first as it's faster than pip. You could also create the environment and/or download python through uv. You could use the standalone installation of uv instead of relying on pip.

From within the created virtual environment:

$ pip install uv
$ pip install stimuli --ignore-requires-python
$ cd ~/git/eeg-cardio-audio-sleep  # not in this directory already
$ uv pip install -e .[all]

Important

Note that we install stimuli first with the flag --ignore-requires-python because stimuli requires python 3.11 and above while PsychoPy requires python 3.10 maximum. The version pin on stimuli is due to limitation on Windows and does not impact performance on Linux, thus it is safe to ignore the version pin.

Important

Note the -e flag used for an editable install. As the configuration files are within the package, this flag must be used for changes to take effect. It's also handy to use this flag in-case you need to update the package from source, im which case a simple git pull will suffice.

Important

Note that mne-lsl version 1.7 and above include a pre-compiled version of liblsl. On Linux, it is compatible with the manylinux2 and manylinux2014 standards since it was compiled on an 'old' version. If you can compile the library yourself, you might see performance improvements due to the use of newer compilers and standard libraries. To install mne-lsl from source you can use the pip flag --no-binary or you can set the environment variables MNE_LSL_LIB with a path to your manually compiled or fetched liblsl.

Install also the additional ipython and ipykernel packages if you are in VSCode, as they are useful especially for interactive windows.

$ uv pip install ipython ipykernel

Usage

Command-line interface

The paradigm is controlled by command-line from the activated environment.

Tip

If you use VSCode, the environment will always be activated provided that your workspace is set to eeg-cardio-audio-sleep, i.e. that you opened the folder ~/git/eeg-cardio-audio-sleep.

In the terminal, enter:

$ cas

It will display all the available commands, for instance test-sequence, with an associated description. To get help on a specific command and on its argument, enter the pattern:

$ cas COMMAND --help

For instance:

$ cas test-sequence --help

Tip

Every time a command is invoked, the current configuration is displayed, including the type of trigger, the sound settings, the detection settings, ...

The arguments of a command can be entered following this pattern:

$ cas COMMAND ARG1 VALUE1 ARG2 VALUE2

For instance:

$  cas test-sequence --verbose DEBUG

Tip

Some argument might accept more than 1 value, in which case the pattern becomes cas COMMAND ARG1 VALUE1_1 VALUE1_2 ARG2 VALUE2 and some argument might only control a boolean flag, in this case the pattern becomes cas COMMAND ARG.

Note that every mandatory argument will be requested in the terminal if it was absent from the command. Note that some arguments can only be provided as part of the initial command.

Configuration

The configuration of the triggers, sound, sequence, ... is done in the file ~/git/eeg-cardio-audio-sleep/cardio_audio_sleep/tasks/_config.py.

Important variables:

• The variable TARGET_DELAY controls how long after a peak the sound should be delivered.
• The variable N_SOUND and N_OMISSION control how many sound and omission are present in the sequence.
• The variable TRIGGERS controls both which trigger is delivered for a sound and for an omission.

The configuration of the detector settings is done in the file ~/git/eeg-cardio-audio-sleep/cardio_audio_sleep/tasks/_config_detector.py.

Note about the detector testing

The cardiac detector can be tested with the commands test-detector. It creates a real-time visualization of the internal buffer and of the peak detection. In the terminal, a log of the time it took to detect the last peak is displayed. This time might seem excessive. This is due to the visualization slowing down the online loop tremendously. If you want to estimate the time it takes to detect a peak, you can run those commands with the --no-viewer flag which disables visualization. The timings in the console should now be reasonable.

$ cas test-detector --stream STREAM --ch-name-ecg AUX7 --n-peaks 20 --no-viewer