Merge pull request #814 from contsili/cuttingeegx-workshop

OPM tutorial for CuttingEEG X (2)

workshop/cuttingeegx.md

@@ -9,7 +9,7 @@ CuttingEEG is turning 10 years old! This milestone calls for a special edition,
 
 Alongside the [CuttingEEG X](https://cuttingeegx.org) conference we will be organizing some local workshops in the morning.
 
-- Who: Konstantinos Tsilimparis, Robert Oostenveld. Jan-Mathijs Schoffelen
+- Who: Konstantinos Tsilimparis, Robert Oostenveld, Jan-Mathijs Schoffelen
 - When: 31 October 2024
 - Where: Nijmegen
 - See <https://cuttingeegx.org/registration/#Nijmegen> for more details
@@ -86,9 +86,9 @@ To have a smooth experience - and to avoid having to spend precious debugging ti
 
 ## The data used in this tutorial
 
-Next, we proceed with downloading the relevant data. The data that are used in the hands-on sessions, are stored on the FieldTrip [download-server](https://download.fieldtriptoolbox.org/workshop/cuttingeegx). You can either ‘click around’ using web browsers and/or explorer windows to grab the data that are needed, or instead (less work, at least if it works) execute the MATLAB code below.
+Next, we proceed with downloading the relevant data. The data that are used in the hands-on sessions are stored on the FieldTrip [download-server](https://download.fieldtriptoolbox.org/workshop/cuttingeegx). The data are approximately 1.3 Gb. You can either ‘click around’ using web browsers and/or explorer windows to grab the data that are needed, or instead (less work) execute the MATLAB code below.
 
-Please ensure that your present working directory is the ``'cuttingeegx'`` folder, which you created in the previous step. Open a new .m file in the text editor and run the following (Note: do not use the command line window):
+Please ensure that your present working directory is the ``'cuttingeegx'``, which you created in the previous step. Open a new .m file in the editor, copy the following code and run the whole script (Note: To properly run the function ``'recursive_download'``, do not use the command line window and do not run the code line-by-line):
 
 ```
 % create a folder (within cuttingeegx) that will contain the data

workshop/cuttingeegx/squids_vs_opms.md

@@ -2,7 +2,7 @@
 title: SQUIDs versus OPMs
 tags: [cuttingeegx]
 ---
-
+_This page is still under construction_
 # SQUIDs versus OPMs
 
 ## Introduction
@@ -15,24 +15,24 @@ OPMs are flexible in their placement allowing for new recording strategies. Thes
 
 OPMs are magnetometers, as their name suggests. Magnetometers are more sensitive to environmental noise than gradiometers, which most SQUID systems have. Several data analysis algorithms to remove environmental noise have been proposed (see [Seymour et al (2022)](https://www.sciencedirect.com/science/article/pii/S1053811921011058?via%3Dihub) for more details). In this tutorial, we apply homogeneous field correction (HFC). HFC works better with a large number of sensors (more than 32).
 
-Unlike SQUID systems, which have standard coregistration procedures, OPMs don't have a single standard. In this tutorial, we coregister the OPMs with the MRI using an optical 3D scanner which captures the participant’s facial features along with the OPM helmet (Zetter et al., 2019).
+Unlike SQUID systems, which have standard coregistration procedures, OPMs don't have a single standard. In this tutorial, we coregister the OPMs with the MRI using an optical 3D scanner which captures the participant’s facial features along with the OPM helmet ([Zetter et al., 2019](https://www.nature.com/articles/s41598-019-41763-4)).
 
 
-This tutorial does not cover follow-up analyses (like source reconstruction) which in principle should not differ from the SQUID follow-up analyses, or alternative coregistration methods which are covered in the tutorial on [coregistration of Optically Pumped Magnetometer (OPM) data](tutorial/coregistration_opm/).
+This tutorial combines the FieldTrip tutorials on [preprocessing of Optically Pumped Magnetometer (OPM) data](tutorial/preprocessing_opm/) and [coregistration of Optically Pumped Magnetometer (OPM) data](tutorial/coregistration_opm/). It does not cover follow-up analyses (like source reconstruction) which in principle should not differ from the SQUID follow-up analyses, or alternative coregistration methods which are covered in the tutorial on [coregistration of Optically Pumped Magnetometer (OPM) data](tutorial/coregistration_opm/).
 
 ## Background
 
 
-In this tutorial we will use recordings made with 32 OPM sensors  placed in an adult-sized “smart” helmet with a total of 144 slots. Each slot allows the sensor to move along a single axial direction. That way, the sensor can slide in its slot until it touches the head surface, regardless of the head size and shape. To limit head movements we mounted the helmet on a wooden plate.
+In this tutorial we will use recordings made with 32 OPM sensors placed in an adult-sized “smart” helmet with a total of 144 slots. This helmet is called “smart” as each slot allows the sensor to slide in until it touches the head surface, regardless of the head size and shape. To limit head movements we mounted the helmet on a wooden plate.
 
-To acquire a measurement for each of the 144 helmet slots, we divided the experiment into six sequential recordings while maintaining the participant's head in a fixed position. We kept 9 sensors around the participant’s head fixed for each recordings. Since the OPM sensors touched the participant’s head and the helmet was mounted, these 9 sensors were able to keep the participant's head fixed throughout the experiment. In each recording we moved the remaining 23 sensors to fill every helmet slot.
+To acquire a measurement for each of the 144 helmet slots, we divided the experiment into six runs while maintaining the participant's head in a fixed position. We kept 9 sensors around the participant’s head fixed for all the recordings. The remaining 23 sensors were moved to different helmet slots in each run to cover the whole scalp as homogeneously as possible.
 
 ### The dataset used in this tutorial
 The data for this tutorial was recorded with a 32-sensor FieldLine HEDscan v3 system with a so-called smart helmet. Each OPM sensor has one channel that measures the normal component of the magnetic field. 
 
-We perform an experiment with left median nerve stimulation on a single participant using both the SQUID and the OPM system. We expect the activity to be modelled 20 ms post-stimulation with a dipole located at the right Primary Somatosensory (S1) area (Andersen & Dalal, 2021; Boto et al., 2017; Buchner et al., 1994)). 
+We perform a left median nerve stimulation experiment on a single participant in both the SQUID and the OPM system. We expect to find a dipole 20 ms post-stimulation in the right primary somatosensory (S1) area ([Andersen & Dalal, 2021](https://pubmed.ncbi.nlm.nih.gov/34089874/); [Buchner et al., 1994](https://link.springer.com/article/10.1007/BF01211175)). 
 
-The dataset can be downloaded from our download server.
+The dataset can be downloaded from our [download-server](https://download.fieldtriptoolbox.org/workshop/cuttingeegx).
 
 ## Procedure 
 In this tutorial for the SQUIDs we will take the following steps:

workshop/cuttingeegx/test_installation.md

@@ -1,16 +1,19 @@
 ---
 title: Test your MATLAB and FieldTrip installation in advance
-tags: [toolkit2024]
+tags: [cuttingeegx]
 ---
 
 # Test your MATLAB and FieldTrip installation in advance
 
-Prior to the hands-on sessions, you need to check the functionality of the computational setup you have on your end. This is needed to hit the ground running, and to avoid to spend time on debugging the MATLAB environment during the hands on session. We recommend to use a clean install of a [recent version](https://github.com/fieldtrip/fieldtrip/releases/tag/20240916) of the toolbox. Once you have set this up, you may want to execute the below code, and check the output.
+Prior to the hands-on sessions, you need to check the functionality of the computational setup you have on your end. This is needed to hit the ground running, and to avoid to spend time on debugging the MATLAB environment during the hands on session. We recommend to use a clean install of a [recent version](https://github.com/fieldtrip/fieldtrip/releases/tag/20240916) of the toolbox. Once you have set this up, please execute the code below, and check the output.
 
     fprintf('################################################################\n');
     fprintf('computer: %s\n', computer);
     ver('MATLAB');
 
+    cd('fieldtrip-20240916')
+    ft_defaults; % sets the required paths to use fieldtrip
+
     [ftver, ftpath] = ft_version;
     fprintf('FieldTrip path is at: %s\n', ftpath);
     fprintf('FieldTrip version is: %s\n', ftver);
@@ -19,8 +22,8 @@ Prior to the hands-on sessions, you need to check the functionality of the compu
     fprintf('dpss is:         %s\n', which('dpss'));
     fprintf('fminunc is:      %s\n', which('fminunc'));
     fprintf('ft_read_data is: %s\n', which('ft_read_data'));
-    fprintf('runica is:       %s\n', which('runica'));  % should not be found yet, or the fieldtrip version
-    fprintf('spm is:          %s\n', which('spm'));     % should not be found yet, or the fieldtrip version
+    fprintf('runica is:       %s\n', which('runica'));  % don't worry if this path is not be found yet
+    fprintf('spm is:          %s\n', which('spm'));     % don't worry if this path is not be found yet
     fprintf('################################################################\n');
 
-If you get an error that says `Undefined function or variable 'ft_version'.` please add FieldTrip to the MATLAB path and try again. See [here](/faq/installation) for more information about adding FieldTrip to the MATLAB search path (Hint: You should use `'ft_defaults'` to add the necessary FieldTrip paths).
+    cd .. % go back to the 'cuttingeegx' directory