-
Notifications
You must be signed in to change notification settings - Fork 32
Use Automagic within the command line
In some cases it is not straightforward to run Automagic with a GUI, for example if you would like to run the preprocessing on a remote server. In this case you could create a Project, run both preprocessing and interpolation from the command line by writing few lines of Matlab script. Of course the quality assessment is not then possible without any GUI and you will have to open the GUI for this. You can always use the command line and GUI alongside each other by using the project_state.mat file that exists in the results folder of each project.
Below is an example of a short script which creates a project, starts preprocessing, and finally interpolates the channels that are selected to be interpolated during the preprocessing steps.
addAutomagicPaths();
name = 'commandline_project';
dataFolder = '/path/to/RAWformat/';
resultsFolder = '/path/to/RAWformat_results_commandline/';
ext = '.RAW';
Params = struct();
VisualisationParams = struct();
project = Project(name, dataFolder, resultsFolder, ext, Params, VisualisationParams, samplingrate);
project.preprocessAll();
project.interpolateSelected();In order to create a new Project, 6 arguments are required. You need to specify the name of the project, dataFolder the path where the data is located, resultsFolder the path to the folder in which you would like to save the results, ext the extension of the EEG data and finally both parameters for preprocessing and visualisation which are Params and VisualisationParams in the example above.
In the example above, both Params and VisualisationParams are structures with no fields: struct(). This will use the default parameters of the Automagic specified in the DefaultParameters.m. For more information on how to modify each parameters please see the next section.
Once the Project is created, you can simply use public methods to manipulate data. As an example you can start the preprocessing with project.preprocessAll() and then interpolate channels with project.interpolateSelected(). For an overview of all public methods available please refer to the corresponding code in Project.m.
% Template for all the parameters
params = struct('FilterParams', struct('notch', struct('freq', 50), ...
'high', struct('freq', 0.5, 'order', []),... % Default order for filtering
'low', struct('freq', 30, 'order', []),...
'zapline', struct('freq', 50, 'ncomps', 3)),...
'CRDParams', struct('ChannelCriterion', 0.85,...
'LineNoiseCriterion', 4,...
'BurstCriterion', 5,...
'WindowCriterion', 0.25, ...
'Highpass', [0.25 0.75]), ...
'PrepParams', struct(), ...
'HighvarParams', struct('sd', 25), ...
'InterpolationParams', struct('method', 'spherical'), ...
'RPCAParams', struct('lambda', [], ... % Default lambda by alm_rpca
'tol', 1e-7, ...
'maxIter', 1000), ...
'MARAParams', struct('chanlocMap', containers.Map, ...
'largeMap', 0, ...
'high', struct('freq', 1.0, 'order', [])), ...
'ICLabelParams', struct('brainTher', [], ...
'muscleTher', [0.8 1], ...
'eyeTher', [0.8 1], ...
'heartTher', [0.8 1], ...
'lineNoiseTher', [0.8 1], ...
'channelNoiseTher', [0.8 1], ...
'otherTher', [], ...
'includeSelected', 0, ...
'high', struct('freq', 2.0, 'order', [])),...
'EOGRegressionParams', struct(), ...
'ChannelReductionParams', struct('tobeExcludedChans', []), ...
'EEGSystem', struct('name', 'EGI',...
'sys10_20', 0, ...
'locFile', '', ...
'refChan', struct('idx', []), ...
'fileLocType', '',...
'eogChans', [], ...
'powerLineFreq', []), ...
'Settings', struct('trackAllSteps', 0, ...
'pathToSteps', '/allSteps.mat',...
'colormap','Default',...
'sortChans', 0)...
);The general convention used by preprocessing parameters are as follows:
The main function performing the preprocessing is called preprocess.m. This function subsequently calls other preprocessing functions, each of which carrying out a different step of the preprocessing.
The main parameter given as an argument to preprocess.m is a struct which has other structs as its fields. Each of this structures then correspond to different parts of the preprocessing. An example of this is as shown below:
% This is an example of a parameters to preprocessing
params = struct('FilterParams', struct('notch', struct('freq', 50), ...
'high', struct('freq', 0.5, 'order', []),... % Default order for filtering
'low', struct('freq', 30, 'order', [])),...
'CRDParams', struct('ChannelCriterion', 0.85,...
'LineNoiseCriterion', 4,...
'BurstCriterion', 5,...
'WindowCriterion', 0.25, ...
'Highpass', [0.25 0.75]) ...
);The example above specifies only the parameters given to filtering and clean_rawdata(). Any other parameters that are omitted, for example MARA ICA or RPCA, will be replaced by default values defined in DefaultParameters.m.
Example for setting up the EEG system structure:
'EEGSystem', struct('name', 'Others',...
'sys10_20', 1, ...
'locFile', 'neuroscan64_chanloc.ced', ...
'refChan', struct([]), ...
'fileLocType', 'ced',...
'eogChans', [], ...
'powerLineFreq', []), ...Following convention are used for parameter structures:
- If a structure is not given at all, then the default values defined in
DefaultParameters.mwill be used. - If a parameter is defined as
my_param = strcut(), then again the default values for that structure are used. - If a parameter is defined as
my_param = strcut([]), then the corresponding preprocessing step is skipped and not executed. Note that this is the only way to avoid a specific preprocessing step. It is important to know that the main parameter (in the example above calledparams) must not beparams = struct([])(Otherwise simply do not use Automagic!). An example where you can disable MARA ICA is as follows:
params = struct('FilterParams', struct('notch', struct('freq', 50), ...
'high', struct('freq', 0.5,...
'order', []),...
'low', struct('freq', 30,...
'order',
[]))),...
'MARAParams', struct([]) ...
);In the example above Filtering parameters is specified, MARA ICA is skipped, and all other parameters are omitted (default values will be used).
A comprehensive description of all parameters is given in the comment section of preprocess.m. An example of how to construct all the possible parameters is also given in RecommendedParameters.m (please do not modify this file though) or the first example above (the template).
Default parameters used for preprocessing are specified in DefaultParameters.m.
The steps below are used by default:
- PREP
- MARA ICA
-
EOG regression (do not forget to specify EOG channels in EEGSystem structure, e.g.
'eogChans', [1 8 14], ...)
If you have a similar project and would like to start a preprocessing with exactly the same parameters, you need to first load the project_state.mat of your previous project from which you would like to import the parameters. Each created project has a corresponding file in the results folder called project_state.mat. This file has all the relevant information of a project. After loading this file into Matlab, you can use its field .params for your new project:
addAutomagicPaths();
load('path/to/project/project_state.mat'); % This loads object self of class
% Project.mat into the working space
Params = self.params;
% Nexts steps are as explained in the previous steps where you create the
% new project, but this time with the imported parameters
name = 'commandline_project';
dataFolder = '/path/to/RAWformat/';
resultsFolder = '/path/to/RAWformat_results_commandline/';
ext = '.RAW';
VisualisationParams = struct();
samplingrate = sampling rate of the data
project = Project(name, dataFolder, resultsFolder, ext, Params, VisualisationParams, samplingrate);
project.preprocessAll();
project.interpolateSelected();If you have already created a project, using either the GUI or command line, you can still open the project in the command line and manipulate it. Each created project has a corresponding file in the results folder called project_state.mat. This file has all the relevant information of a project. To load this file, Automagic needs to be in your path. Then you simply load the file with load('project_state.mat'). This file loads a class called Project which is named self. You can manipulate this self variable exactly as previously explained:
addAutomagicPaths();
load('path/to/project/project_state.mat');
self.preprocessAll();
self.interpolateSelected();The above lines will start preprocessing and interpolating the data.