- Overview
- Configuration and GUI
- Mandatory Variables
- Loading Variables
- Warping Variables
- Event and Marks Variables
Overview
This script takes in raw data files and preforms all of the necessary steps to prepare the raw files for the eeg_pipe_asr_amica pipeline (this pipeline). This script was designed to be very versatile for any level of automation and knowledge base of configuration scripts.
Raw files can vary greatly depending on the modality used to collect the data, while init files going into the pipeline need to to prepared just right for smooth processing. This script current can prepare data from two different styles:
1. ESS Capsule
To load a capsule make sure it it is at the level 1 stage, and load the study_description.xml file into the batch config file upload. The metadata stored in the capsule will be automatically accessed in the script. Using the file structure for this pipeline is best as the saved files will be directed into the analysis/data/1_init folder when they are complete.
2. Raw Files
You can also load raw files into the batch config file upload. Using the file structure for this pipeline is best as the saved files will be directed into the analysis/data/1_init folder when they are complete. This means uploading your raw files from the analysis/data/0_raw folder.
This script takes the raw data file through 3 process:
- Loading the File
- Warping Channel locations to MNI head
- Creating events and marks to indicate In/Out Task Time
The picture below shows how each section develops the file.
Configuration and GUI
This script will only produce GUI's if it is missing a necessary piece of information. This means that if you carefully fill out the configuration file then you can run the complete pipeline autonomously. On the other hand if you are not comfortable with the configuration files this file can be run with no configuration and will use GUI's to prompt you for the information as needed. This process is more time consuming but will help you understand what is needed in the configuration, and you can always run a smaller batch first to sort out these details. Refer to the table below to plan your script usage.
Method | Varibles | Run Style |
---|---|---|
ESS | ||
1 | ESS and Config | Auto |
2 | ESS and Manual | Interactive |
3 | ESS and Config and Manual | Interactive |
OTHER | ||
1 | Config | Auto |
2 | Manual | Interactive |
3 | Config and Manual | Interactive |
Mandatory Variables
If you want to run this script fully automatic or on a remote cluster you need to ensure that each of the mandatory variables described below are denoted in either the batch config or the ESS capsule metadata.
ESS LoadType
- Mandatory variables are split between the ESS capsule metadata and the config file. Do not worry about the XML variables in this case as they are automatically found by reading the ESS study_description.xml file that you loaded when batching.
OTHER LoadType
- All of the mandatory variables need to be in the config file.
The table below indicates with an x the methods in which you can describe each variables depending on your load type. You will see that all variables can be described in the Config or the ESS metadata. If those are not filled out, then some variable allow you to enter the values later, while others will revert to defaults.
LOADTYPE | ESS | ESS | ESS | OTHER | OTHER | |
---|---|---|---|---|---|---|
Variable | XML | Config | Manual | Config | Manual | Description |
loadType | x | x | x | x | ESS or OTHER type of study you are loading | |
modality | x | x | x | System used for recording | ||
oneloc | x | x | x | 1 if you are using a single montage location file, 0 for subject specific files | ||
locs_file_name | x | x | x | Path to montage or naming convention for subject specific files | ||
srate | x | x | x | Number of data points collected per second | ||
NotEEG_chans | x | x | Channel numbers that do not contain EEG data | |||
Fid_chans | x | x | x | Channel numbers of the Fiducials for warping reference | ||
ref_loc_file | x | x | Warp reference surface, default is the MNI head if no config is given | |||
tMatrix | x | x | x | x | Matrix used to warp your location files to MNI head | |
Onevents | x | x | x | x | Events that represent HED tag 'Custom/Marks/RecStart' | |
Offevents | x | x | x | x | Events that represent HED tag 'Custom/Marks/RecStop' | |
Inevents | x | x | x | x | Events that represent HED tag 'Custom/Marks/InEvent' |
Loading Variables
loadType
The load type refers to whether you are starting from an ESS capsule or from a list of raw files. Use
[loadType],ESS
or [loadType],OTHER
in the config replace_string. If you leave config empty the following GUI will be displayed. Simply checkbox your answer.
modality
The modality refers to which system you did you data recording on. The script needs to know this in order to select the right plugin and function to load your data. If you are using ESS then this information is not needed in the config. Use [modality],BIOSEMI
or [modality],BRAINVISION
in the config replace_string. If you leave config empty the following GUI will be displayed. Simply checkbox your answer. If you check other it will attempt a multitude of loading functions based on the file extension but there is no guarantee that any of these will work for you unique file type.
oneloc
This variable is either a 0 or a 1, based on your location file. ESS capsules are always set to 0.
- 0 means that the file has a unique location file for each subject. The file is located in the same folder as the data file.
- 1 means that the files use a common location montage or generic location file.
Use [oneloc],0
or [oneloc],1
in the config replace_string. If you leave config empty the following GUI will be displayed. Simply checkbox your answer.
locs_file_name
This variable is a continuation of your oneloc answer above. ESS capsules use the built in metadata and the location file names will be found automatically.
-
If you chose oneloc 0 , use a naming convention in the config such as
[batch_dfn,.,-1]_locs.elc
see swap strings for more information. -
If you chose oneloc 1 , write the path and file name of the montage file such as
analysis/support/misc/BioSemi_BUCANL_7Eyes.sfp
.
If you leave config empty the following GUI will be displayed. Simply write the same thing as above.
srate
State the sampling rate of the system that you used. ESS capsules will find this data automatically. Common rates are 280, 500, and 512 point per second. An example would be [srate],512
in the config replace_string. If you leave config empty the following GUI will be displayed. Simply type in a number.
NotEEG_chans
These are the channel indices that do not contain EEG information this includes unplugged channels not including fiducials. ESS will by default not load any channels that do not contain EEG, but if you are using config you will have to specify these. For example our lab never uses the EXG8 channel of our BioSemi, this corresponds to using [NotEEG_chans],[140]
to remove the very last channel. This item is one of the few that does not contain a backup GUI as an empty config is a acceptable answer. The default will remove no channels.
Note that the channels that are purged are: NotEEG_chans + Fid_chans(see below), so channels should only be included in one or the other.
Warping Variables
Fid_chans
This item is very similar to NotEEG_chans but the indices you are listing in this case are the fiducials. ESS capsules denote this information by specifying the channel Type as FID. ESS will automatically use these when warping , but if you are using config you will have to specify these. For example our lab never uses the LPA,NZ and RPA fiducials recorded as the first three, using[Fid_chans],[1 2 3]
to set these as the landmarks for warping and then removing them from EEG.data afterwards. If you leave config empty the following GUI will be displayed. Simply type in a indices of the channels, you do not have to do [ ] brackets.
ref_loc_file
The reference Location file is the montage that you want to warp your channel locations to. For this pipeline you will be warping to the MNI head. The config should point to the location file. The config should be[ref_loc_file],analysis/support/misc/standard_1020.elc
. If the config is empty it will default back to this file as well. In the future this may want to be changed and thus was made a string_swap variable.
tMatrix
Warping or transforming, ensures that the location file that you loaded aligns with the standard MNI head model that is used later on in the pipeline for referencing. Both ESS capsules and Other sets need to provide this information through the config or through the interactive GUI. Essentially the pipeline needs a transformation matrix of 9 values to expand,translate and rotate in each dimension to get your locations to our positions. If you are using a standard transformation matrix for all of your subjects you can place the matrix in the config, for example [tMatrix],[ 0 , -23 , -50 , 0 , 0 , -240.3 , 1100 , 1100 , 1100 ]
. If you you would like to do exact transformations for each file you will have to go through the GUIs. The first GUI allows you to input a file specific transformation matrix for that subject if you know it. If you do not know what it is yet, then click the manual checkbox to open the EEGLAB co-register GUI.
Adjust the matrix that is displayed at the bottom until you find the right fit and press
[ OK ]
.
Event and Marks Variables
The pipeline proceeding this script needs to be contain specific events that indicate in-task time and out of task time. This is because ICA analysis is sensitive to messy task time that could contain movement artifacts or non-stationary so we only want to submit the essential data to ICA. To do this the out of task time is flagged using our Out/On/In events to create removal marks. This system uses the Vised Marks plugin to do the data flagging.
- Custom/Marks/RecStart
- Custom/Marks/RecStop
- Custom/Marks/In
These tags will be identified and used as your On/Off/In events respectively.
Onevents/Offevents/Inevents
To tell the script where to flag, you need to give it Onevents and Offevents OR Inevents.
-
In events are events that need to be surrounded in In task time. Any time that is not within 3 sec of an Inevent is considered out of task. This is ideal for studies with many repeated tasks that are within a few seconds of each other.
-
Config Example: A Go/NoGo task with 1 as Go and 2 as NoGo with one or the other every 2 seconds. This task has many short breaks between the sessions. Inevents would be ideal as you could specify
[Inevent], 1 2
and that would ensure that all of the Go and NoGo tasks are included for ICA, while the breaks and lead up times would be removed. -
On/Off events can also be thought of as Record On and Record Off. They are specified in pairs to act as boundaries for in task time. Any time on the outside of these events will be marked black and out of task.
-
Config Example: A study where participants are asked to clear their mind for 5 min. The start of this task is event 11 and the end is 22. In this case Inevents would not work, as they would only gather 6sec of the task. Instead if you specify
[Onevent], 11
and[Offevent], 22
that would ensure that the whole 5min is set as in task recording. Notice how 11 and 22 are a paired set. If 11 was always on but off alternated between 22 and 33, then you would specify the following in the config:[Onevent], 11 11
and[Offevent], 22 33
. 11 is recorded twice but each time it has a different stop indicator. You also have to be weary about the number of events of each type you have in the file. For every On there must be an Off, since the marking function uses intervals.
If you do not have the prebuilt ESS and you don not fill out the config file you will prompted with the following GUI that asks for the same information. Depending on which method you are using simply type in the event numbers separated by spaces. If your study does not contain events that suit either of these methods you can manually add Recording Start and Recording Stop marks. To do this select the Manual Mode checkbox.
If you selected Manual Mode then this little GUI will pop up. This GUI simply warns you that you are entering the Vised-Marks editor and that any annotations you add here will be added to the marks structure permanently. The two commands you will be using are:
-
a
to drop a RecStart event at your cursor -
b
to drop a RecStop event at your cursor
See the example below where we placed events before and after each block of tasks.
After you click Update Marks Structure the events that you dropped into the data will be saved into the events information structure. Vised Marks will then proceed to place Out of task Marks everywhere outside your boundaries. Below is a example of what the final result will look like if you were to plot the data afterwards, note that below we plotted the whole file at once so you could get a birds eye view.
These methods may seem like a lot of work but they can easily be simplified by using the events that already exist in the experiment. For the example above if we used Inevents we could have listed all of the event types in the experiment in the config file. We would get the same result as there were no events during the break times. That method would have run automatically and would have saved bunch of time. Consider your experiment when choosing a marking method.