How to run SIFT simulation
This page shows an unofficial introduction for using SIFT simulator.
Linear Dynamical System-Vector Autoregressive process
Example 1: Schelter 2009 Eq 3.1 (08/30/2022 Added)
The following demonstration was confirmed to be performed under the following environment: Fedora 28, Matlab R2021a, EEGLAB 2022.0, SIFT 1.52.
1. Select 'SIFT'->'Simulation'->'Linear Dynamical System'->'Vector Autoregressive Process'
2. Set parameters
Set 'Semulation', 'Schelter 2009 Eq 3.1'; 'TrialLength', 30.1 (s); 'NumTrials', 1. These numbers follow Schelter et al. (2009). The sampling rate does not matter, use the default 100 (Hz). Under 'NoiseDistribution', set 'ScaleParams' 0 to set the amount of noise zero.
3. Run the process
4. Confirm the simulated signals
5. Preprocess the simulated data
6. Set parameters
Change the 'Signal Type' to 'Channels', 'ConvertChanlocs2Dipfit' to 'False'.
7. Select 'SIFT'->'Model fitting and validation'->'Model Order Selection'
8. Set parameters
Change 'Algorithm' to 'ARfit'. This is not critical, but 'ARfit' gives slightly more exaggerated minimum dip than the default 'Vieira-Morf'. Confirm all the four methods suggests the model order 3. Set the 'WindowLength' 30, 'WindowStepSize', 1. With this setting, the window length == data length. This changes the behavior of SIFT and the result shows frequency domain result (very nice work, Tim...) The original Schelter et al. (2009) used the maximum model order 50. We can use this number if we want, but it does not affect the result at all.
9. Neglect the warning
About the warning of datapoint-to-parameter ratio, see this article.
10. Confirm that the suggested model order is the same as the ground truth
11. Select 'SIFT'->'Model fitting and validation'->'Fit AMVAR model'
12. Set parameters
Set 'Algorithm' 'ARfit' for the sake of consistency; 'Model Order', 3; 'WindowLength', 30; 'WindowStepSize', 1.
13. Confirm the results from the status check
14. Select 'SIFT'->'Connectivity'
15. Set parameters
Select 'ConnectivityMeasures', 'dDTF08' and 'RPDC'; 'ConvertSpectrumToDecibels', 'True' (though it is not used).
16. Select 'SIFT'->'Visualization'->'Time-Frequency Grid'
17. Set parameters
Change 'PlotConditionDifference', 'False'; 'MatrixLayout', 'Partial'; 'UpperTriangle', 'RPDC'; 'UT_ColorLimits', 99 (which is not used, probably); 'LowerTriangle', 'RPDC'; 'LT_ColorLimits', 99.
18. Compare the SIFT results with those reported by the reference paper
Left, Schelter et al. (2009) Figure 1; Middle, the RPDC results; Right, the dDTF08 results. Note the frequency scaled used in the left panel refers to the normalized frequency (probably) i.e. 0.5 means the half of the Nyquist Frequency of the current sampling rate 100Hz.
Example 2: Epileptic Seizure
The following demonstration was confirmed to be performed under the following environment: Fedora 28, Matlab R2017b, EEGLAB 14.1.2, SIFT 1.52.
Obsolete info for EEGLAB 14 (08/30/2022 updated)
First of all, you have to have EEGLAB and SIFT downloaded, installed, and launched successfully. Now, SIFT may contain several functions that have the same name as other functions. For example, several versions of 'PropertyGrid' could be found in your paths. To find them out, try the following code on the command line.
which -all PropertyGrid
You may have only one included by SIFT, or you may have more than one. In any case, we need to make sure (i.e. otherwise it won't work) that all the functions called from SIFT should refer to those contained by SIFT itself. From Matlab GUI, 'Home'-'Set Path', select all SIFT-related paths by pressing shift button while selecting all of them, press 'Move to Top', then 'Save' and 'Close'.
This is easy, just click the rightmost menu item. This corresponds to generate simulated sources. If you want to obtain their scalp projection, see below for 'EEG simulator'.
Launch PropertyGrid GUI to accept user inputs
This is the famous PropertyGrid used everywhere in EEGLAB plugins. The menu items are self descriptive. The most important parameter here would be the top one labeled 'Simulation'. When you click it, you'll find 8 items in a list. Choose the first model labeled 'Epileptic Seizure'. Press 'OK' to start the process.
Wait until the progress bar reaches the end
You'll see the 5 rainbow-colored bars that shows progress of the processes. It won't take more than 10 s if you choose the default parameters on the previous window. When calculation is done, the EEGLAB function pops up. This is unrelated to the current simulation, so press 'OK' to continue.
Confirm the results
When calculation is done, you'll see these three windows pop up. The index numbers in the time-series data plot correspond to the index numbers used on the right schematic model. Press 'OK' to continue.
Confirm the updated EEGLAB GUI
Now you see the updated EEGLAB main GUI. Confirm the number of channels (13), the number of epochs (100), sampling rate (this is 100Hz, not 1000Hz!), epoch length (5 s).
If you continue to analyze this data using SIFT, then you should be able to replicate the relations shown in the schematic illustration.
Access to the generated data
The generated 13-channel data are stored in EEG.data which has the size of 13 x 500 x 100 for channel, time points, and trials (epochs), respectively. To process this data using SIFT functions, follow the Example 1 above.
EEG Simulator
This GUI menu generates 1) the simulated sources as shown above, then 2) project them to scalp EEG channels. To perform source-to-scalp projection, it uses pre-computed 90-anatomical region atlas and international 10-10 system 64-ch scalp recording sensor labels and locations. This template information is included by the downloaded SIFT package and no need to take any action to set it up.
Launch PropertyGrid GUI to accept user inputs
This window is important because just pressing 'OK' does not work. You have to first choose a model from the top GUI menu. As described, we select 'Epileptic Seizure'. This means that there will be 13 sources in the model. We need to specify the corresponding number of source locations by either entering their equivalent current dipole locations by xyz coordiantes (but in Talairach or MMN coordinate system? This needs to be clarified) or specifying their anatomical labels (looks like those used in AAL atlas by Tzourio-Mazoyer et al., 2002, but better to be confirmed also). For the test purpose, we choose the latter and click 13 check boxes for selecting anatomical labels from the dropdown menu under 'Scalp Data Generation'-'ForwardModel'-'SourceShape'-'RoiAtlasLabels'. You may choose any 13 regions for now to see if it works. When done, press 'OK'.
Wait until the progress bar reaches the end
If everything goes well, you do not need to do anything. Just watch the progress bar extending to the end. It took longer than just simulating the sources in my case.
What if I encounter this error?
I got this error message.
Fortunately, I knew what it is through my experience with updating clean_rawdata. And I know that this may not cause the problem for most of non-Linux users (unless you set a model with a crazily large number of network nodes.) This JAVA-based RAM check function returns very small amount for my environment (Fedora 28). I guess it depends on the definition of 'available RAM amount' by each OS. Even if the returned answer is 0.71 GB as in the example, there is much more RAM space available and HDD swap never occurs. You can always check how much RAM can be used via OS resource monitor. Based on this, I implemented the following change on sim_fwdProj.m. There are more than one place that has the same error function, but the first one appears in line 241. I suggest you replace the function error() to warning() to let the calculation continue.
%error('This operation will require %0.5g GiB of memory. You do not have sufficient memory.',bytesReq/1024^3); warning('This operation will require %0.5g GiB of memory. You do not have sufficient memory.',bytesReq/1024^3); % 12/02/2019 Makoto. Modified.
Confirm the results
When calculation is done, you will see the same set of figures. Note the two warning messages shown in the command line, which were generated by my mod suggested above. Note also that the 13 time-series data shown here refers to source activation, not the 64-channel projection yet.
Confirm the updated EEGLAB GUI
Now you see the updated EEGLAB main GUI. Confirm the number of channels (64, not 13!), the number of epochs (100), sampling rate (this is 100Hz, not 1000Hz!), epoch length (5 s).
Confirm the scalp projection
To visually inspect the generated scalp projection 'recorded' at the scalp sensors, you have to manually open the scroll plot using EEGLAB function. 'Plot'-'Channel Data (Scroll)' opens the interactive GUI to browse the 64-ch time-series data.
Access to the generated data
The generated 64-channel data are stored in EEG.data which has the size of 64 x 500 x 100 for channel, time points, and trials (epochs), respectively.
Author: Makoto Miyakoshi, Swartz Center for Computational Neuroscience (SCCN), Institute for Neural Computation (INC), UC San Diego
