Notes on software installation and tips

Preparing Ubuntu for Psychopy¶

Psychopy is preferably installed in a pure Python environment

If an anaconda environment is activated, run the following command to deactivate it:

conda deactivate

Ensure your Ubuntu system has all necessary dependencies:

sudo apt install python3-dev \
                 libgtk-4-dev \
                 libgstreamer1.0-dev \
                 libgstreamer-plugins-base1.0-dev \
                 freeglut3-dev \
                 libwebkitgtk-6.0-dev \
                 libjpeg8-dev \
                 libpng-dev \
                 libtiff-dev \
                 libsdl1.2-dev \
                 libnotify-dev \
                 libsm-dev

Multiple screens

If you want to use multiple screens, install the corresponding libxcb extension:

sudo apt-get install libxcb-xinerama0

Create a Python virtual environment:
```
python3 -m venv $HOME/psychopyenv
```
Load the new virtual environment:
```
source $HOME/psychopyenv/bin/activate
```

Update Pypi and setuptools to the latest version:

python -m pip install -U pip setuptools six wheel

Update Numpy to the latest version:
```
python -m pip install -U numpy
```
Download the wxPython sources:
```
python -m pip download wxPython
```
Build wxPython (version of package may change on your settings, edit accordingly):
```
python -m pip wheel -v wxPython-4.2.1.tar.gz  2>&1 | tee build.log
```

Install the wheel you just created:

python -m pip install wxPython-4.2.1-<python-version>-linux_x86_64.whl

Test the installation (an empty window should we created without errors):

python -c "import wx; a=wx.App(); wx.Frame(None,title='hello world').Show(); a.MainLoop();"

Install our HCPh-signals package (assumes these SOPs are checked out at <path>:
```
cd <path>/code/signals
python -m pip install .
```

Psychopy installation¶

This block describes how to prepare an environment with a running Psychopy 3 installation.

Make sure to load the correct environment

Deactivate conda (if active):
```
conda deactivate
```
Load the new virtual environment:
```
source $HOME/psychopyenv/bin/activate
```

Clone the Psychopy repository:

git clone https://github.com/psychopy/psychopy.git

Navigate to the Psychopy directory and check-out tag 2023.2.3:
```
cd psychopy
git checkout 2023.2.3
```
Install Psychopy using the following command:
```
python -m pip install .[suggested]
```
Install the EyeLink plugin for Psychopy:
```
python -m pip install git+https://github.com/oesteban/psychopy-eyetracker-eyelink.git
```
On MacOSX or if you don't have access to pip directly, Psychopy's package manager

Open Psychopy as mentioned immediately below. Click Tools ⤷ Plugin/Packages manager..., then go to the Packages tab and hit the Open PIP terminal button (bottom left area). There, you can type:
```
pip install git+https://github.com/oesteban/psychopy-eyetracker-eyelink.git
```

Install the Pylink module made by SR Research, it is distributed with the installation of the eyelink-display-software done previously:

python -m pip install /usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp310-cp310-linux_x86_64.whl

Find the appropriate version for your Python distribution

The example above is for cPython 3.10, alternative installations are:

/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp27-cp27mu-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp310-cp310-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp311-cp311-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp36-cp36m-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp37-cp37m-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp38-cp38-linux_x86_64.whl
/usr/share/EyeLink/SampleExperiments/Python/wheels/sr_research_pylink-2.1.762.0-cp39-cp39-linux_x86_64.whl

Try opening Psychopy by typing:
```
psychopy --no-splash -b
```
Check that the EyeLink eye tracker is available in the dropdown under the experiment's options

If the EyeLink is not available, most likely the appropriate Pylink is missing. See the last checkbox in the installation of the eye tracker to install it. Otherwise, make sure you installed the EyeLink plugin above.
The first time it runs, Psychopy will likely request some increased permissions
- Add a new psychopy group to your system.
```
sudo groupadd --force psychopy
```
- Add your current user to the new group:
```
sudo usermod -a -G psychopy $USER
```
- Raise security thresholds for Psychopy, by inserting the following into /etc/security/limits.d/99-psychopylimits.conf:
```
@psychopy - nice -20
@psychopy - rtprio 50
@psychopy - memlock unlimited
```

Psychopy crashes when trying to run a experiment: pyglet.gl.ContextException: Could not create GL context

This is likely related to your computer having a GPU and a nonfunctional configuration:

$ glxinfo | grep PyOpenGL
X Error of failed request:  BadValue (integer parameter out of range for operation)
  Major opcode of failed request:  151 (GLX)
  Minor opcode of failed request:  24 (X_GLXCreateNewContext)
  Value in failed request:  0x0
  Serial number of failed request:  110
  Current serial number in output stream:  111

A quick attempt to solve this would be adding our user to the video group.

However, that is unlikely to work out so you'll need to take more actions (see this, and this)

Psychopy crashes when trying to run a experiment: qt.qpa.plugin: Could not load the Qt platform plugin 'xcb'

If you installed libxcb-xinerama0, or you don't have multiple screens, first try:

python -m pip uninstall opencv-python
python -m pip install opencv-python-headless

If that doesn't work, try a brute force solution by installing libxcb fully:

sudo apt-get install libxcb-*

Psychopy does not recognize the SR Research eye tracker

If the eye tracker does not appear in the corresponding dropdown menu or your experiments fail as described in this issue, you almost certainly need to check the plugin is installed and available within Psychopy's environment.

Setting up the synchronization service as a daemon in the background¶

It's fundamental to have a reliable means of communication with the BIOPAC digital inputs

The following guidelines set up a little service on a linux box that keeps listening for key presses (mainly, the s trigger from the trigger box), and RPC (remote procedure calls) from typically Psychopy or similar software.

The service is spun up automatically when you connect the MMBT-S modem interface that communicates with the BIOPAC (that is, the N-shaped pink box)

To automatically start the program when the BIOPAC is connected, create a udev rule as follows:
```
sudo nano /etc/udev/rules.d/99-forward-trigger.rules
```

Add the following rule to the file:

ACTION=="add", KERNEL=="ttyACM0", SUBSYSTEM=="tty", TAG+="systemd", ENV{SYSTEMD_WANTS}="forward-trigger.service"

Save the file and exit the editor.
Run the following command to reload the udev rules:
```
sudo udevadm control --reload-rules
```

Create a systemd service unit file:

sudo nano /etc/systemd/system/forward-trigger.service

Add the following content to the file (Adapt the path to forward-trigger-service.py to the location on your computer):

[Unit]
Description=Forward Trigger Service
After=network.target

[Service]
ExecStart=/usr/bin/python3 /path/to/forward-trigger-service.py
WorkingDirectory=/path/to/forward-trigger/directory
StandardOutput=null

[Install]
WantedBy=multi-user.target

Save the file and exit the text editor.
Run the following command to enable the service to start at boot:
```
sudo systemctl enable forward-trigger
```
Run the following command to reload the systemd daemon:
```
sudo systemctl daemon-reload
```

Conversion of ET recordings into BIDS¶

EyeLink's EDF recording files will be accessed with PyEDFRead. Please note, we will be using @oesteban's fork to include two bugfixes that, at the time of writing this document, have not been made it into the codebase of PyEDFRead.

Install PyEDFRead on the computer where the ET conversion into BIDS will be executed.
```
python -m pip install git+https://github.com/oesteban/pyedfread.git@master
```
PyEDFRead requires the EyeLink SDK be installed as described here