Added SOPs for EMG, eye tracker & light source

documentation/src/SUMMARY.md

@@ -26,10 +26,15 @@
     - [Acttrust](./sops/actimetry/acttrust/acttrust.md)
   - [Mobile EEG](./sops/mobile-EEG/mobile-EEG.md)
   - [Pupillometry](./sops/pupillometry/main.md)
+    - [NVBL](./sops/pupillometry/nvbl/nvbl.md)
+    - [Pupil Core](./sops/pupillometry/pupil-core/pupil-core.md)
+  - [EMG](./sops/EMG/EMG-USB2+.md)
   - [Metropsis](./metropsis/metropsis.md)
   - [Saliva data collection: Dietary considerations](./sops/saliva-data-collection/dietary-considerations.md)
   - [Ocular physiology measurements](./sops/ocular-physiology/main.md)
     - [OCT](./sops/ocular-physiology/oct/oct.md)
+  - [Light sources](./sops/light-sources/main.md)
+    - [Spectra Tune Lab](./sops/light-sources/stlab/stlab.md)
   - [Light measurements](./sops/light_measurement_devices/main.md)
     - [Go Pro Hero10](./sops/light_measurement_devices/GoProHero10.md)
     - [Circadiometer WP 690](./sops/light_measurement_devices/CircadiometerWP690.md)

documentation/src/sops/EMG/EMG-USB2+.md

@@ -0,0 +1,180 @@
+# Standard Operating Procedure for OTBioelettronica EMG-USB2+ device
+
+| Device       | OTBioelettronica, EMG-USB2+ bioelectrical signal amplifier                                              |
+| ------------ | --------------------------------------------------------- |
+| Objective    | Measuring muscle activity on the skin (sEMG)                    |
+| Owner        | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) |
+| Reviewer     |  |
+| Approver     |  |
+| Contributors | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) & [Veronica Canziani](mailto:canzianiveronica@gmail.com) |
+| Version      | 1.0.0                                        |
+| Last edit    | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) |
+| Date         | 20250205                                                  |
+
+## Manuals
+
+All devices and software manuals for the device and software used can be accessed at https://otbioelettronica.it/en/download/.
+
+## Start up
+
+- Checklist for materials
+  1. EMG-USB2+ amplifier 
+
+      <img src="img/emg_0.png" alt="EMG-USB2+ amplifier" width="300">
+  2. ECG/EMG electrodes (currently using 30x24 mm) 
+
+      <img src="img/emg_1.png" alt="ECG/EMG electrodes" width="200">
+  3. EMG bipolar sensors
+
+      <img src="img/emg_2.png" alt="EMG bipolar sensors" width="200">
+  4. EMG adaptor
+
+      <img src="img/emg_3.png" alt="EMG adaptor" width="300">
+  5. Software: [OTBiolab+](https://otbioelettronica.it/en/software/)
+  6.  Software: OTBiolab Light (installed with OTBiolab+)
+  7.  Optional: 
+     - Skin prep (Nuprep or equivalent) and gauze / paper towels
+     - Tape
+
+- Start up system
+  1. Turn on device: small button at the back, on the left-hand side 
+
+      <img src="img/emg_5.png" alt="Power switch" width="300">
+  2. Connect USB cable
+
+      <img src="img/emg_6.png" alt="USB cable" width="300">
+  3. Start software:
+     - OTBiolab+ for normal, standalone measurements
+     - OTBiolab Light for measurements using 3rd party software (e.g., Python scripts)
+  4. Connect the electrodes to the amplifier:
+     1.  Connect the extension cable with the bipolar sensors
+     2.  Connect the sensor unit to the adaptor
+       - Careful to plug the sensor unit into the right channels: numbers are labelled on the adaptor
+     3.  Connect it into the amplifier(you would typically want to use _IN1_)
+     4.  Connect the ground electrode in the _PATIENT REF_ input
+
+      <img src="img/emg_4.png" alt="USB cable" width="200">
+
+## Preparation
+
+- OTBiolab+:
+  1. Go to: _Acquisition/Setup_
+  2. In the _Channels_ panel on the left-hand side:
+     1. Select and unfold _INx_
+     2. Select the channel you want to set up
+  3. In the _New channel configuration_ panel on the right hand-side:
+     1. Set _Adapter_ to “16 channels bipolar adapter – AD8x2JD”
+     2. Set _Sensor_ to “sEMG - Sendor CDE - CDE”
+  4. Press _Set configuration as current settings_. You should then see your settings in the _Configuration of INx (Channel x)_ panel
+  5. Repeat steps 2.2, 3.1 and 3.2 for each channel that you want to measure
+  6. Press _Setup Complete_ to save your setup settings 
+
+<img src="img/emg_10.png" alt="Software setup" width="600">
+
+_NOTE: This configuration can be saved in OTBiolab+, so it does not need to be set up before each trial. So, as long as the number of channels in use remains the same, you only need to do this once. Or you can open the saved setup file and then edit it. You can also copy the current configuration and paste it to add new channels faster._
+
+- OTBiolab Light:
+  1. Make sure OTBiolab+ is closed! Both software cannot run simultaneously
+  2. Set the correct settings: 
+     - _Device_: "EMG-USB2+"
+     - _Channels_: "256+16"
+     - Rest is up to you
+  3. Click _Start_ to initiate connection with device
+     - There should be a prompt: _Acquisition started – don't close OTBiolab Light_ 
+  4. The rest should be handled by your own software
+
+## General Procedure
+
+Placing electrodes:
+  1. If needed, gently apply skin prep gel to skin surface with the gauze (careful not to rub too much – gel is abrasive!)
+     - In theory, the measured area must be shaved beforehand – even if there are no visible hair 
+  2. Place electrodes 
+     - Don't forget ground electrode! Can placed on the forehead near the hairline, on the elbow, behind the neck… Basically wherever no muscle / electrical activity occurs
+  3. Plug the cables to the electrodes
+     - Careful to make sure to match (or take note of) the channel numbers and the right muscle you want to measure
+  4. Tuck cables away, to make sure no cables obstruct participant therefore ensuring good data. 
+     - For this you can use the tape - make sure there is no snagging or tension on the cables and the participant is comfortable
+  5. If you want, you can secure the electrodes even more with a small amount of tape over each one.
+
+_NOTE: if the signal does not look to be changing as the participant performs different movements, check that all electrodes, especially the black “ground” electrode, are on correctly and still pasted onto the skin._
+
+Recording from OTBiolab+:
+  1. Click on the green play button in the top panel to start visualisation. Use the double arrow symbol in each channel panel to scale the signal.
+  2. Check that the channels are properly connected
+     - Ask participant to move the measured muscle(s), you should be able to visualise changes in each channel throughout the different movements
+  3. Click on _Start recording_ (red button)
+  4. Click on _Stop recording_
+
+## Experiment Procedure
+
+### Measurement A: facial sEMG
+
+| Description | Link to variation                                      |
+| ----------- | ------------------------------------------------------ |
+| PSR Project   | [PSR project measurement A](#measurement-a-in-psr-project) |
+
+A list of all facial muscles theoretically measurable is visible below (from: Kovalchuk, Y.; Budini, E.; Cook, R.M.; Walsh, A. Investigating the Relationship between Facial Mimicry and Empathy. Behav. Sci. 2022, 12, 250. https://doi.org/10.3390/bs12080250)
+
+<img src="img/emg_9.png" alt="Software setup" width="600">
+
+Placing electrodes:
+1. Place electrodes on the desired muscles
+2. Carry out some skin prep – depending on amount of sweat, skin oils, etc.
+3. Electrodes might be in sensitive areas – if too hard, let participants plug the electrodes themselves by helping them find the location of the electrode and letting them do the rest
+4. Make sure electrodes stick well, especially for individuals with beards – muscles such a the orbicularis oris may be hard to capture then
+   - Use tape if needed
+5. Tuck the cables around the ears – you can also twist the plugs on the electrodes so the cables come out in a convenient way
+6. Use tape on the shoulder to keep the cables in place – no pulling, but no loose cables also!
+
+### Measurement B
+
+_No other variations recorded yet_
+
+## Data Saving
+
+- After recording
+  1. _File/Save_ to record your data as a .otb file 
+     - Visualise and process data within the software if needed
+
+- Access saved data 
+  1. _File/Open_ to open recorded .otb files
+
+| Description | Link to variation                                              |
+| ----------- | -------------------------------------------------------------- |
+| PST Project   | [PSR Project storage transfer](#storage-transfer-in-psr-project)   |
+
+## Shut down
+
+OTBiolab+:
+  1. Close the window to stop the software:
+   - If the system isn't recording and data has been saved!
+
+OTBiolab Light:
+  1. Click on _Stop_
+     - There should be a prompt: _Acquisition stopped_
+  2. Close the window to stop the software:
+   - If the system is recording, acquisition will stop as if you clicked on the stop button – there should be the same prompt: _Acquisition stopped_!
+
+Hardware:
+  1. Press on the button at the back of the amplifier to turn it off
+
+---
+
+## Project specific measurements
+
+### Measurement A in PSR Project
+
+In the PSR project, the following muscles are of interest to measure light sensitivity:
+- Orbicularis oculi
+- Corrugator supercilii
+- Zygomaticus major
+- Orbicularis oris
+
+The layout of the muscles is as follows:
+
+<img src="img/emg_7.png" alt="layout_diagram" width="200">
+<img src="img/emg_8.png" alt="layout_picture" width="195">
+
+## Storage transfer in PSR Project
+
+In the PSR project, the data is recorded and saved as a .csv file using a custom Python module (link to code yet to be added – ask [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) if interested)

documentation/src/sops/light-sources/main.md

@@ -0,0 +1,3 @@
+This chapter contains information about the standard operating procedures for our light sources:
+
+1. Spectra Tune Lab, a 10-primary, spectrally tuneable light engine

documentation/src/sops/light-sources/stlab/stlab.md

@@ -0,0 +1,142 @@
+# Standard Operating Procedure for Spectra Tune Lab light source
+
+| Device       | Ledmotive, Spectra Tune Lab 10-primary LED light engine                                              |
+| ------------ | --------------------------------------------------------- |
+| Objective    | Producing spectrally tuneable light                    |
+| Owner        | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) |
+| Reviewer     |  |
+| Approver     |  |
+| Contributors | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) |
+| Version      | 1.0.0                                        |
+| Last edit    | [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de) |
+| Date         | 20250207                                                  |
+
+## Manuals
+
+The manual for the device used can be accessed on this repository [here](./manual/DS_450003_rev06_SPECTRA-TUNE-LAB.pdf).
+
+## Start up
+
+- Checklist for materials
+  - Hardware:
+    1. Light source:
+
+        <img src="img/stlab-2.png" alt="Light source" width="200">
+
+    2. Light Hub:
+
+        <img src="img/stlab-4.png" alt="Light hub" width="200">
+
+  - Software:
+    1. µWave software (can be installed on Windows machine from the provided USB stick:
+
+        <img src="img/stlab-5.png" alt="USB stick" width="200">
+
+    2. PyPlr package, if communication through Python necessary. It has a ```pyplr.stlab``` module for handling many STLab features.
+
+         Access the documentation at https://pyplr.github.io/cvd_pupillometry/07_api.html#pyplr-stlab.
+
+         Martin, Joel, T., & Spitschan, M. (2021). PyPlr (1.0.0). Zenodo. https://doi.org/10.5281/zenodo.6724918
+
+- Start up system
+  1. Connect the device: make sure the light source is connected as follows (from the manual):
+
+      <img src="img/stlab-1.png" alt="Connection diagram" width="400">
+
+  2. Turn on device: power button at the back of the device
+  3. Start software, either:
+     - µWave – user-friendly, GUI based 
+     - Python for more control through PyPlr
+
+_NOTE: The workshop built a nice little holder for placing ND filters at the front of the device. Make sure that the ND filter is not under pressure from overtightening the screws. When you change the filter, unplug the light source. Nothing will hold the filter from falling when you unscrew the holder – be extra careful to hold the light source upright._
+
+  <img src="img/stlab-3.png" alt="Filter holder" width="200">
+
+## Preparation
+
+µWave software:
+1. Click on _Connections_ in the top panel
+2. Click on _Re-scan_ to look for light sources
+   - You should see the two addresses – 1 and 1023. Both should work
+3. Then you can start playing with the light source.
+
+PyPlr:
+1. Establish the connection to the light source. Make note of the device password accessible from the provided USB stick.
+
+   ```light_source = SpectraTuneLab(username='admin', default_address=1023, password='*')```
+
+   _TIP: Send all commands to address 1023, not 1 – this has caused issues with playing the command properly – some weird priority thing. Basically, 1 is the device address and 1023 is the broadcast address. When you connect one of the devices it gets assigned an address between 0 - 1022. The broadcast address is a special address that will target all devices in the network._
+
+2. The rest is up to you, depending to what you want to do – refer to the PyPlr documentation.
+
+## General Procedure
+
+- PyPlr: how to play a simple light stimulus?
+
+   The light source has 10 LEDs, each taking an intensity value ranging from 0 (dark) to 4095 (maximum intensity).
+   You have to pass a list of 10 intensity values to the light source.
+
+   ```
+   spectrum = [300]*10 # Create the list of settings – 1 value for each LED
+   light_source.set_spectrum_a(spectrum) # Pass it to the light source
+   sleep(2.) # Wait for two seconds
+   light_source.turn_off() # Swtich the lights off
+   ```
+
+   This is just one of the many ways to control the light source! Refer to the PyPlr documentation for more in-depth info.
+
+## Experiment Procedure
+
+### Measurement A: using video files
+
+| Description | Link to variation                                      |
+| ----------- | ------------------------------------------------------ |
+| PSR Project   | [PSR project measurement A](#measurement-a-in-psr-project) |
+
+In the PSR project, the light source is controlled with PyPlr.
+Sequences of 30-second light stimulation are played using so called .dsf video files (essentially .json files).
+This allows to program the different commands to send to the light source beforehand.
+
+For more info, ask [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de).
+
+### Measurement B
+
+_No other variations recorded yet_
+
+## Data Saving
+
+_No data saving_
+
+| Description | Link to variation                                              |
+| ----------- | -------------------------------------------------------------- |
+| PST Project   | [PSR Project storage transfer](#storage-transfer-in-psr-project)   |
+
+## Shut down
+
+1. Software:
+
+   µWave:
+   - Simply close the window.
+
+   PyPlr:
+   - You can pass a command to stop light emission. To my knowledge there is no way to properly disconnect from the light source.
+
+      ```light_source.turn_off()```
+
+2. Hardware:
+   - Press on the button at the back of the light source to turn it off.
+
+---
+
+## Project specific measurements
+
+### Measurement A in PSR Project
+
+In the PSR project, a need for a gradual ramp-up and ramp-down in the sequences led to creating a variation of the ```pulse_protocol``` function to handle this specific need.
+The video files are created and then stored in a _resources/video_files_ folder, for later access for light sequence playback.
+
+For more info, ask [Lucien Bickerstaff](mailto:lucien.bickerstaff@tuebingen.mpg.de).
+
+## Storage transfer in PSR Project
+
+_No data saving_

documentation/src/sops/pupillometry/main.md

@@ -1 +1,4 @@
-This chapter contains information about the standard operating procedure for our pupillometry device: NVBL, created to measure pupil size.
+This chapter contains information about the standard operating procedure for our pupillometry devices:
+
+1. NVBL, created to measure pupil size.
+2. Pupil Core, a wearable eye tracker.