Documentation: Automation of Analysis over an Experimental Study
IN CONSTRUCTION
This section needs an update by Windows users for the LaTeX part.
The LaTeXing part assumes that a global variable TEX_DIR exists, which points to the bbci_tex folder of the SVN with '/' at the end, e.g.,
TEX_DIR = '/home/blanker/svn/ida/public/bbci_tex/'
The proposed automation works best, when sticking to the following convention: You should file your sequence of experiments (session) either as 'project' or as 'study'. This is just a formal distinction with the following convention:
study. Large scale study, typically with external participants, targeting at a journal publication.
projects. Experimental studies that are exploratory, and/or for training purpose (labrotations, master theses, internships).
Having explained this distinction, the term 'session' will be generally used in the sequel. In any case, your session needs to have a 'session name'. The Matlab scripts to analyse the data of the session are stored under BCI_DIR/investigation/studies/''{SESSION_NAME}'' or under BCI_DIR/investigation/projects/''{SESSION_NAME}''. The LaTeX files are stored under TEX_DIR/studies/{SESSION_NAME}, resp. TEX_DIR/projects/{SESSION_NAME}`. The (numerous) figures that are automatically generated are stored in a subdirectory 'pics_auto' thereof, and should preferably not be added to the SVN. However, summarizing figures (like grand average overview figures) or figures that should be included in papers can be stored in a subdirectory 'pics' and be added to the SVN.
Lopping an ERP-Analysis over a Sequence of Experiments
1 [subdir_list, session_name]= get_session_list('projekt_biomed2010');
2
3 results_file= [DATA_DIR 'results/' session_name '/grand_average_ERPs'];
4
5 opt_fig= strukt('folder', [TEX_DIR session_name '/pics_auto/'], ...
6 'format', 'pdf');
7
8 % For each participant, experiments with the following conditions were performed:
9 taglist= {'Intensify','Rotate','Upsize'};
10 filelist= strcat('MatrixSpeller', taglist);
11
12 colOrder= [0.83 0.67 0; 0.4 0.4 0.4];
13 clear erp erp_r
14
15 for vp= 1:length(subdir_list),
16 subdir= subdir_list{vp};
17 sbj= subdir(1:find(subdir=='_',1,'first')-1);
18 exp_id= strrep(subdir, '_', '');
19
20 % default values
21 disp_ival= [-200 1000];
22 ref_ival= [-200 0];
23 crit_maxmin= 70;
24 crit_ival= [100 900];
25 crit_clab= {'F9,z,10','AF3,4'};
26 clab= {'Cz','PO7'};
27
28 for ff = 1:length(filelist),
29 fprintf('Processing %s - %s.\n', subdir, filelist{ff});
30 opt_fig.prefix= [exp_id '_' taglist{ff} '_'];
31
32 % subject-specific settings
33 switch(sbj),
34 end
35
36 % load data
37 clear cnt epo*
38 file= [subdir '/' filelist{ff} sbj];
39 [cnt, mrk, mnt]= eegfile_loadMatlab(file);
40
41 b= procutil_firlsFilter(0.5, cnt.fs);
42 cnt= proc_filtfilt(cnt, b);
43
44 %% artifact rejection based on variance criterion
45 mrk= reject_varEventsAndChannels(cnt, mrk, disp_ival, 'verbose', 1);
46
47 % segmentation
48 epo= cntToEpo(cnt, mrk, disp_ival);
49
50 %% artifact rejection based on minmax difference criterion on frontal chans
51 epo= proc_rejectArtifactsMaxMin(epo, crit_maxmin, ...
52 'clab',crit_clab, 'ival',crit_ival, 'verbose',1);
53
54 epo= proc_baseline(epo, ref_ival);
55 epo_r= proc_r_square_signed(epo);
56 epo_r.className= {'sgn r^2 ( T , NT )'}; %% just make it shorter
57
58 fig_set(1);
59 constraint= ...
60 {{-1, [100 300], {'I#','O#','PO7,8','P9,10'}, [50 300]}, ...
61 {1, [200 350], {'P3-4','CP3-4','C3-4'}, [200 400]}, ...
62 {1, [400 500], {'P3-4','CP3-4','C3-4'}, [350 600]}};
63 [ival_scalps, nfo]= ...
64 select_time_intervals(epo_r, 'visualize', 1, 'visu_scalps', 1, ...
65 'title', [sbj ': ' taglist{ff}], ...
66 'clab',{'not','E*','Fp*','AF*'}, ...
67 'constraint', constraint);
68 printFigure('r_matrix', [18 13], opt_fig);
69 ival_scalps= visutil_correctIvalsForDisplay(ival_scalps, 'fs',epo.fs);
70
71 fig_set(3)
72 H= grid_plot(epo, mnt, defopt_erps, 'colorOrder',colOrder);
73 grid_addBars(epo_r, 'h_scale',H.scale);
74 printFigure(['erp'], [19 12], opt_fig);
75
76 fig_set(2);
77 H= scalpEvolutionPlusChannel(epo, mnt, clab, ival_scalps, ...
78 defopt_scalp_erp2, ...
79 'colorOrder',colOrder);
80 grid_addBars(epo_r);
81 printFigure(['erp_topo'], [20 4+5*size(epo.y,1)], opt_fig);
82
83 fig_set(4, 'shrink',[1 2/3]);
84 scalpEvolutionPlusChannel(epo_r, mnt, clab, ival_scalps, ...
85 defopt_scalp_r2);
86 printFigure(['erp_topo_r'], [20 9], opt_fig);
87
88 % save averages for calculating grand averages later
89 erp{vp,ff}= proc_average(epo);
90 erp_r{vp,ff}= epo_r;
91
92 end
93 end
94
95 save(results_file, 'erp','erp_r', 'clab', ...
96 'session_name', 'subdir_list','filelist', 'taglist', 'mnt', 'opt_fig');
Plotting Grand Average ERPs
1 load(results_file); % as defined in the example above
2
3 ival_scalps= [180 230; 250 350; 400 500];
4
5 % find unified scalings for all plots
6 range_grid= visutil_commonRangeForGA(erp, 'nice_range_erp',10);
7 range= visutil_commonRangeForGA(erp, 'clab_erp', clab, ...
8 'ival_scalp',ival_scalps);
9 range_r= visutil_commonRangeForGA(erp_r, 'clab_erp', clab, ...
10 'ival_scalp',ival_scalps);
11
12 for ff = 1:length(filelist),
13 opt_fig.prefix= ['grand_average_ERPs_' taglist{ff} '_'];
14 erp_ga= proc_grandAverage(erp{:,ff});
15 erp_r_ga= proc_grandAverage(erp_r{:,ff});
16
17 fig_set(1);
18 grid_plot(erp_ga, mnt, defopt_erps, 'colorOrder',colOrder, ...
19 'yLim', range_grid.erp);
20 printFigure('erp', [19 12]*1.3, opt_fig);
21
22 fig_set(2); clf;
23 H= scalpEvolutionPlusChannel(erp_ga, ...
24 mnt, clab, ival_scalps, ...
25 defopt_scalp_erp2, ...
26 'colorOrder',colOrder, ...
27 'yLim', range.erp, ...
28 'colAx', range.scalp);
29 printFigure('erp_topo', [25 16], opt_fig);
30
31 fig_set(4, 'shrink',[1 2/3]);
32 H= scalpEvolutionPlusChannel(erp_r_ga, mnt, clab, ival_scalps, ...
33 defopt_scalp_r2, ...
34 'channelAtBottom', 1, ...
35 'yLim', range_r.erp, ...
36 'colAx', range_r.scalp);
37 printFigure('erp_r_topo', [25 10.5], opt_fig);
38 end