From Center for Cognitive Neuroscience
Revision as of 01:57, 7 March 2014 by Elau (talk | contribs) (Command style updated)
Jump to navigation Jump to search

Back to all things Hoffman2

Back to all things MATLAB

Back to all things EEGLAB

Normally, if you wanted to run something in EEGLAB, you start up MATLAB on Hoffman2, wait for a node to check out, wait for a license, and then start crunching numbers.

But what if your analysis in EEGLAB is going to take 10 hours, and you need to shut your computer down and leave in five hours? Or you don't want your MATLAB job to crash just because your flaky WiFi decides to die in hour nine of the analysis?

Well, if you have run this analysis before and have the "EEG.history" contents, you should be able to create a MATLAB script (*.m file) from said history and run it as a headless job on Hoffman2.

Pros and Cons of Running your EEGLAB analysis as a job
Pros Cons
Learn how to submit command line scripts and feel powerful controlling lots of computers Have to learn command line scripts and how to submit jobs correctly
Be able to have your analysis run without tying up your computer for hours or days at a time Have to run the analysis through at least once partially to create your script
Be able to run MATLAB jobs longer than 24 hours Have to be comfortable editing MATLAB code to create your *.m file
Be able to run MATLAB jobs that use way more memory than your laptop can.
Possibly be able to run multiple analyses at once if you make the extra step and compile your code (so it doesn't need a MATLAB license)

If you think the Pros outweigh the Cons, and they certainly do if you are processing more than one subject, then this is the solution for you.

Identify the processing commands

Using the EEGLAB GUI, process a data file the way your want your job to process a data file. Go from loading the file, to processing, to saving the file.

Once that is complete, keep EEGLAB open and on the MATLAB command line, look at the contents of the history area:

>> disp(EEG.history)

Those commands you see are the ones you will need to put into your script in various places.

Make your script

If you know the exact commands you need to run, or have the contents of an "EEG.history" from a previous analysis, then the general *.m file to create will be like the following example, found at

% eeglab_example_job.m
% Edward Lau
% eplau[at]ucla[dot]edu
% 2014.03.06
% Example EEGLAB script that can be submitted as a job on Hoffman2.
% This M-file will:
%     0. Set the paths for the input and output files.
%     1. Load the EEGLAB "set" file
%     2. Bandpass filter it to 1-45Hz
%     3. Average re-reference the data
%     4. Save the new data file with "preproc" appended to the old name (e.g. worked on "Subj1.set" resulting in "Subj1_preproc.set)
% This example does not necessarily reflect the best practices for how EEG should be pre-processed and
% should only be viewed as an example of how to script basic EEGLAB steps.

%% 0. Variables to set
% The directory where the data to be processed lives.
INPUT_DIR = '/u/home/FMRI/apps/eeglab/current/sample_data/';

% The EEGLAB ".set" file that should be processed
INPUT_FILE = 'eeglab_data.set';

% The directory where the processed data should be saved

% The EEGLAB ".set" filename that should be saved after processing
OUTPUT_FILE = sprintf('%s_%s.%s', INPUT_FILE(1:end-4), 'preproc', 'set');

%% Make sure EEGLAB is in your PATH, change "current" to whichever version of EEGLAB you prefer

%% Load up EEGLAB in headless mode

%% 1. Load up your data
EEG = pop_loadset('filename', INPUT_FILE, 'filepath', INPUT_DIR);

% Set EEG variables appropriately
EEG = eeg_checkset( EEG );

%% Do your analyses
% This could be built from the contents of an EEG.history array from a previous analysis

% 2. Bandpass filter 1-45Hz
EEG = pop_eegfiltnew(EEG, 1, 45, 424, 0, [], 0);
EEG = eeg_checkset( EEG );

% 3. Average re-reference the data
EEG = pop_reref( EEG, []);
EEG = eeg_checkset( EEG );

%% 4. Don't forget to save your data afterward
OUTDIR = getenv('SCRATCH');
EEG = pop_saveset( EEG, 'filename', OUTPUT_FILE, 'filepath', OUTPUT_DIR);
EEG = eeg_checkset( EEG );

Running the script

You will now need to create a BASH command script to submit as a job. This script will setup MATLAB and tell it to run your M-file.

Something like the following will do

# run_eeglab_example_job.sh
# Edward Lau
# eplau[at]ucla[dot]edu
# 2014.03.06
# Runs the example EEGLAB script in a headless job.

# Setup the environment to have modules like MATLAB
source /u/local/Modules/default/init/modules.sh

# Load the MATLAB module
module load matlab

# Run MATLAB and your script
matlab -nosplash -nojvm -nodesktop -singleCompThread -r eeglab_example_job

Submit the Job

All that remains is to submit the job based on what you've already learned about submitting jobs.

Be mindful of the time and memory that you request and then wait patiently as your job is queued and run on the cluster.

In our example case, you would SSH into Hoffman2 and execute the following commands:

 $ cd /u/home/FMRI/apps/examples/eeglab
 $ ./q.sh ./run_eeglab_example_job.sh

Look at the outputs

Make sure that was all worthwhile and look at the outputs. If you are still on Hoffman2, go ahead and launch MATLAB and run the following commands

 >> addpath(genpath('/u/home/FMRI/apps/eeglab/current/')); % Make sure EEGLAB is in the PATH
 >> eeglab; % Launch EEGLAB

And then using the GUI, load up the resulting processed file. If you followed along with our example, this output file will be in your SCRATCH directory.