Home > matlabmk > compile_erpimage.m

compile_erpimage

PURPOSE ^

compile_erpimage() - Extracts relevant data from multiple data sets for

SYNOPSIS ^

function compile_erpimage(gui_infiles_or_tmplt,varargin)

DESCRIPTION ^

 compile_erpimage() - Extracts relevant data from multiple data sets for
                        creating ERPimages.  ERPimages are produced by the
                        function plot_erpimageMK.m.
              
 Usage:
  >> compile_erpimage(setfiles,varargin)

 Required Input:
  gui_infiles_or_tmplt - ['gui', a cell array of strings, or a string template]
                         If 'gui', a GUI is created that allows you to select
                         which set files to import (this is probably the
                         easiest way to import files).  If a cell array of
                         of strings, each element of the cell array should
                         contain the filename of an EEGLAB set file (e.g.,
                         {'visodbl01.set','visodbl02.set'}.  Otherwise, this
                         input should be a filename template (i.e., a string with
                         # where the subject number should be--'visodbl#.set').
                         If you provide a template, you must use the option
                         'sub_ids' (see below) to specify the ID numbers of
                         each subject. Include the files' path unless the files
                         are in the current working directory.
     

 Optional Inputs:
   'bins'           = [integer vector] Bins to extract trials from {default:
                       use all bins}
   'chans'          = [string | cell array] Name of the electrode (e.g., 
                       'MiCe') or a cell array of electrode names that you 
                       want to image. {default: use all electrodes}
   'sub_ids'        = [integer vector] A set of integers specifying the
                       subject ID numbers to include in the grand average.
                       Only necessary if a filename template is given as
                       the input to gui_infiles_or_tmplt. Leading 0's are not
                       necessary for ID numbers less than 10 (e.g., If 7 is a
                       sub_id and visodbl#.set the template, the function will 
                       look for visodbl07.set AND visodbl7.set).
   'bsln_wind'      = [pair of integers] The time window (in units of
                       milliseconds) that will be used to baseline each trial
                       of EEG.  The mean voltage in the time window will be
                       removed from the entire EEG epoch. If the data have
                       already been baselined and ICA artifact correction was NOT
                       applied, you won't need to re-baseline the data. {default:
                       no additional baselining will be done}
   'out_fname'      = [string] The name of the Matlab file in which the
                       ERPimage data will be stored.  If not specified, 
                       the data will be stored in global variables that 
                       plot_erpimageMK.m can use.  By convention, you 
                       should give the file the extension .eim and include 
                       the files' path, unless the files are in the 
                       current working directory. {default: store data as
                       global variables}
   'verblevel'      = an integer specifiying the amount of information you 
                       want functions to provide about what they are doing 
                       during runtime.
                        Options are:
                         0 - quiet, only show errors, warnings, and EEGLAB 
                             reports
                         1 - stuff anyone should probably know
                         2 - stuff you should know the first time you start 
                             working with a data set {default value if 
                             verblevel not already specified}
                         3 - stuff that might help you debug (show all 
                             reports)

 Outputs:
   If specified, function saves data for creating ERPimages in a Matlab file.
   Otherwise, function stores the data in the following global variables:
    chan_data, chans, chanlocs, ep_info, ep_times, bindesc, & srate


 Example: 
 >> setfile_tplate='/usr/local/matlab-toolboxes/matlabmk/demo_files/rtm#y.set';
 >> chans={'MiPf','MiCe','MiOc','LLOc','RLOc'};
 >> compile_erpimage(setfile_tplate,'sub_ids',1:4,'chans',chans, ...
    'bins',[127 133 142 157],'out_fname','demo.eim');
 >> plot_erpimageMK('MiCe','rtmsec','in_fname','demo.eim','avewidth',4,'fig_id',1);

 Notes: 
 -This function assumes that if two electrodes in two different setfiles
 have the same name (e.g., 'MiCe'), then they are homologous.  Congruency
 of electrode coordinates is not checked.  Some electrodes in the 26 and
 59 electrode caps have the same names but are not in homologous
 positions.

 Author: 
 David Groppe
 Kutaslab, 8/2009

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 % compile_erpimage() - Extracts relevant data from multiple data sets for
0002 %                        creating ERPimages.  ERPimages are produced by the
0003 %                        function plot_erpimageMK.m.
0004 %
0005 % Usage:
0006 %  >> compile_erpimage(setfiles,varargin)
0007 %
0008 % Required Input:
0009 %  gui_infiles_or_tmplt - ['gui', a cell array of strings, or a string template]
0010 %                         If 'gui', a GUI is created that allows you to select
0011 %                         which set files to import (this is probably the
0012 %                         easiest way to import files).  If a cell array of
0013 %                         of strings, each element of the cell array should
0014 %                         contain the filename of an EEGLAB set file (e.g.,
0015 %                         {'visodbl01.set','visodbl02.set'}.  Otherwise, this
0016 %                         input should be a filename template (i.e., a string with
0017 %                         # where the subject number should be--'visodbl#.set').
0018 %                         If you provide a template, you must use the option
0019 %                         'sub_ids' (see below) to specify the ID numbers of
0020 %                         each subject. Include the files' path unless the files
0021 %                         are in the current working directory.
0022 %
0023 %
0024 % Optional Inputs:
0025 %   'bins'           = [integer vector] Bins to extract trials from {default:
0026 %                       use all bins}
0027 %   'chans'          = [string | cell array] Name of the electrode (e.g.,
0028 %                       'MiCe') or a cell array of electrode names that you
0029 %                       want to image. {default: use all electrodes}
0030 %   'sub_ids'        = [integer vector] A set of integers specifying the
0031 %                       subject ID numbers to include in the grand average.
0032 %                       Only necessary if a filename template is given as
0033 %                       the input to gui_infiles_or_tmplt. Leading 0's are not
0034 %                       necessary for ID numbers less than 10 (e.g., If 7 is a
0035 %                       sub_id and visodbl#.set the template, the function will
0036 %                       look for visodbl07.set AND visodbl7.set).
0037 %   'bsln_wind'      = [pair of integers] The time window (in units of
0038 %                       milliseconds) that will be used to baseline each trial
0039 %                       of EEG.  The mean voltage in the time window will be
0040 %                       removed from the entire EEG epoch. If the data have
0041 %                       already been baselined and ICA artifact correction was NOT
0042 %                       applied, you won't need to re-baseline the data. {default:
0043 %                       no additional baselining will be done}
0044 %   'out_fname'      = [string] The name of the Matlab file in which the
0045 %                       ERPimage data will be stored.  If not specified,
0046 %                       the data will be stored in global variables that
0047 %                       plot_erpimageMK.m can use.  By convention, you
0048 %                       should give the file the extension .eim and include
0049 %                       the files' path, unless the files are in the
0050 %                       current working directory. {default: store data as
0051 %                       global variables}
0052 %   'verblevel'      = an integer specifiying the amount of information you
0053 %                       want functions to provide about what they are doing
0054 %                       during runtime.
0055 %                        Options are:
0056 %                         0 - quiet, only show errors, warnings, and EEGLAB
0057 %                             reports
0058 %                         1 - stuff anyone should probably know
0059 %                         2 - stuff you should know the first time you start
0060 %                             working with a data set {default value if
0061 %                             verblevel not already specified}
0062 %                         3 - stuff that might help you debug (show all
0063 %                             reports)
0064 %
0065 % Outputs:
0066 %   If specified, function saves data for creating ERPimages in a Matlab file.
0067 %   Otherwise, function stores the data in the following global variables:
0068 %    chan_data, chans, chanlocs, ep_info, ep_times, bindesc, & srate
0069 %
0070 %
0071 % Example:
0072 % >> setfile_tplate='/usr/local/matlab-toolboxes/matlabmk/demo_files/rtm#y.set';
0073 % >> chans={'MiPf','MiCe','MiOc','LLOc','RLOc'};
0074 % >> compile_erpimage(setfile_tplate,'sub_ids',1:4,'chans',chans, ...
0075 %    'bins',[127 133 142 157],'out_fname','demo.eim');
0076 % >> plot_erpimageMK('MiCe','rtmsec','in_fname','demo.eim','avewidth',4,'fig_id',1);
0077 %
0078 % Notes:
0079 % -This function assumes that if two electrodes in two different setfiles
0080 % have the same name (e.g., 'MiCe'), then they are homologous.  Congruency
0081 % of electrode coordinates is not checked.  Some electrodes in the 26 and
0082 % 59 electrode caps have the same names but are not in homologous
0083 % positions.
0084 %
0085 % Author:
0086 % David Groppe
0087 % Kutaslab, 8/2009
0088 %
0089 
0090 %%%%%%%%%%%%%%%% REVISION LOG %%%%%%%%%%%%%%%%%
0091 %
0092 % 08/21/09 Tidied up (e.g., temp_epoch information for the set currently in memory
0093 % no longer needs to be stored) -DG
0094 %
0095 % 2/1/2010-remove_art_ics.m replaced by remove_artifact_ics.m.  Help
0096 % documentation extended to cover all optional input arguments. -DG
0097 %
0098 
0099 function compile_erpimage(gui_infiles_or_tmplt,varargin)
0100 
0101 global VERBLEVEL
0102 global chan_data;
0103 global chans;
0104 global chanlocs;
0105 global ep_info;
0106 global ep_times;
0107 global bindesc;
0108 global srate;
0109 global rtbins;
0110 global rtmsec;
0111 global eim_bins
0112 
0113 %Input Parser
0114 p=inputParser;
0115 %Note: the order of the required arguments needs to match precisely their
0116 %order in the function definition (which is also the order used by p.parse
0117 %below)
0118 p.addRequired('gui_infiles_or_tmplt',@(x) ischar(x) || iscell(x));
0119 p.addParamValue('bins',[],@isnumeric);
0120 p.addParamValue('chans',[],@(x) ischar(x) | iscell(x));
0121 p.addParamValue('sub_ids',[],@isnumeric);
0122 p.addParamValue('out_fname',[],@ischar);
0123 p.addParamValue('verblevel',[],@(x) x>=0);
0124 p.addParamValue('bsln_wind',[],@(x) isvector(x) && (length(x)==2));
0125 
0126 p.parse(gui_infiles_or_tmplt,varargin{:});
0127 
0128 if isempty(VERBLEVEL) && isempty(p.Results.verblevel)
0129     VERBLEVEL=2;
0130 elseif ~isempty(p.Results.verblevel)
0131     VERBLEVEL=p.Results.verblevel;
0132 end
0133 
0134 %Do NOT store data in global variables
0135 if ~isempty(p.Results.out_fname)
0136     clear global chan_data;
0137     clear global chans;
0138     clear global chanlocs;
0139     clear global ep_info;
0140     clear global ep_times;
0141     clear global bindesc;
0142     clear global srate;
0143     clear global rtbins;
0144     clear global rtmsec;
0145     clear global eim_bins;
0146 end
0147 
0148 %Note, if chans is empty, use all of them (done in main loop below)
0149 if ischar(p.Results.chans)
0150   n_chan=1;
0151   chans{1}=p.Results.chans; %make it a cell array
0152   chan_data=cell(1,n_chan);
0153 elseif iscell(p.Results.chans) 
0154   n_chan=length(p.Results.chans);
0155   chans=p.Results.chans;
0156   chan_data=cell(1,n_chan);
0157 end
0158 
0159 
0160 %% Get *.set fileames
0161 sfiles=get_set_infiles(gui_infiles_or_tmplt,p.Results.sub_ids);
0162 
0163 
0164 if isempty(p.Results.bins),
0165     VerbReport('Grabbing data from all bins in setfiles.',2,VERBLEVEL);
0166 end
0167     
0168 
0169 %%%%%%%%%%%%%%%%%%%% File Loop %%%%%%%%%%%%%%%%%%%%%%%%%
0170 clear ep_info; %the epoch information from all sets
0171 rtmsec=[]; %the rts from all sets
0172 rtbins=[]; %the bin numbers that rtmsec correspond to (same event can have different RTs for different bins)
0173 chanlocs=[]; %the channel location info for all sets
0174 grand_ep_ct=0; 
0175 global EEG; %necessary for rm_artifact_ics (below)
0176 
0177 for a=1:length(sfiles),
0178   %Note, pop_loadset displays message about what file is being loaded
0179   EEG=pop_loadset(sfiles{a});
0180 
0181   %Check for artifact ICs and remove them if there
0182   %[EEG, ICs_removed]=remove_art_ics(EEG,p.Results.bsln_wind,VERBLEVEL); ??old code
0183   ICs_removed=remove_artifact_ics(p.Results.bsln_wind,VERBLEVEL);
0184   
0185   %Baseline EEG (unless already baselined by remove_art_ics
0186   %if ~isempty(p.Results.bsln_wind) && ~ICs_removed, ?? old code
0187   if ~isempty(p.Results.bsln_wind) && isempty(ICs_removed),
0188       EEG=baseline_EEG(EEG,p.Results.bsln_wind,VERBLEVEL);
0189   end
0190   
0191   %%%%% Make sure new set is consistent with already loaded sets %%%%%%
0192   %Get/check times (in ms) for all time points
0193   if ~exist('ep_times','var')
0194       ep_times=EEG.times;
0195   elseif isempty(ep_times)
0196       ep_times=EEG.times;
0197   else
0198       if (length(ep_times)==length(EEG.times)),
0199           if max(abs(ep_times-EEG.times))
0200               error('EEG.times in set %s does not match that of other sets.\n', ...
0201                   sfiles{a});
0202           end
0203       else
0204           error('EEG.times in set %s does not match that of other sets.\n', ...
0205               sfiles{a});
0206       end
0207   end
0208   
0209   %Get/check sampling rate
0210   if ~exist('srate','var')  
0211       srate=EEG.srate;
0212   elseif isempty(srate)
0213       srate=EEG.srate;
0214   else
0215       if (srate~=EEG.srate),
0216           error('EEG.srate in set %s does not match that of other sets.\n', ...
0217               sfiles{a});
0218       end
0219   end
0220 
0221   %See if reaction time info is attached to set
0222   fldnames=fieldnames(EEG);
0223   rtmsec_attached=0;
0224   rtbins_attached=0;
0225   for d=1:length(fldnames),
0226       if strcmpi(fldnames{d},'rtmsec')
0227           rtmsec_attached=1;
0228       elseif strcmpi(fldnames{d},'rtbins')
0229           rtbins_attached=1;
0230       end
0231   end
0232   rts_attached=rtbins_attached*rtmsec_attached;
0233   if ~isempty(rtmsec) && ~(rts_attached),
0234      error(['File %s does not have reaction time information, ' ...
0235          'but the other files you loaded do.\n'],sfiles{a});
0236   end
0237   
0238   %Get/check bin descriptors
0239   if ~exist('bindesc','var')
0240       bindesc=EEG.bindesc;
0241   elseif isempty(bindesc)
0242       bindesc=EEG.bindesc;
0243   else
0244       if length(bindesc)==length(EEG.bindesc)
0245          for b=1:length(bindesc),
0246             if ~strcmpi(bindesc{b},EEG.bindesc{b}),
0247                 error('EEG.bindesc in set %s does not match that of other sets.\n', ...
0248               sfiles{a});
0249             end
0250          end
0251       else
0252           error('EEG.bindesc in set %s does not match that of other sets.\n', ...
0253               sfiles{a});
0254       end
0255   end
0256   
0257   no_chans=0;
0258   if ~exist('chanlocs','var'),
0259      no_chans=1; 
0260   elseif isempty(chanlocs),
0261       no_chans=1;
0262   end
0263   if no_chans,
0264     chanlocs=EEG.chanlocs;
0265     %if chans not specified by user, use all of them
0266     if isempty(p.Results.chans)
0267       n_chan=length(chanlocs);
0268       chan_data=cell(1,n_chan);
0269       for c=1:n_chan,
0270          chans{c}=EEG.chanlocs(c).labels;
0271       end
0272     end
0273   end
0274   
0275   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0276   % Find epochs that fall into desired bins
0277   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0278   %Note, I'm sure you could speed this up by first converting the bin
0279   %identifiers in EEG.epoch.eventtype from strings (e.g., 'bin1') to
0280   %integers (e.g., 1)
0281   
0282   %Initialize variables tracking information about the current set
0283   use_ep_this_set=[];
0284   temp_ep_ct=0;  %this variable counts how many epochs have been grabbed from JUST THE CURRENT SET
0285 
0286   if isempty(p.Results.bins), 
0287       %use all bins
0288       for d=1:length(EEG.epoch),
0289           %Grab this epoch? loop
0290           for j=1:length(EEG.epoch(d).eventtype), %check this epoch's types
0291               if strcmpi(EEG.epoch(d).eventtype{j}(1:3),'bin') %is this type a bin?
0292                   use_ep_this_set=[use_ep_this_set d];
0293                   temp_ep_ct=temp_ep_ct+1;
0294                   
0295                   EEG.epoch(d).sourcefile=sfiles{a}; %create new field to keep
0296                   %track of what file each epoch came from
0297                   grand_ep_ct=grand_ep_ct+1;
0298                   ep_info(grand_ep_ct)=EEG.epoch(d);
0299                   if rts_attached,
0300                       rtbins{grand_ep_ct}=EEG.rtbins{d};
0301                       rtmsec{grand_ep_ct}=EEG.rtmsec{d};
0302                   end
0303                   break; %leave j loop
0304               end
0305           end
0306       end
0307   else
0308       %use specified bins
0309       for d=1:length(EEG.epoch),
0310           %Grab this epoch? loop
0311           grabbed=0;
0312           for j=1:length(EEG.epoch(d).eventtype), %check this epoch's types
0313               for k=p.Results.bins,
0314                   if strcmpi(EEG.epoch(d).eventtype{j},['bin' int2str(k)]),
0315                       use_ep_this_set=[use_ep_this_set d];
0316                       temp_ep_ct=temp_ep_ct+1;
0317 
0318                       EEG.epoch(d).sourcefile=sfiles{a}; %create new field to keep
0319                       %track of what file each epoch came from
0320                       grand_ep_ct=grand_ep_ct+1;
0321                       ep_info(grand_ep_ct)=EEG.epoch(d);
0322                       if rts_attached,
0323                           rtbins{grand_ep_ct}=EEG.rtbins{d};
0324                           rtmsec{grand_ep_ct}=EEG.rtmsec{d};
0325                       end
0326                       grabbed=1;
0327                       break; %leave k loop
0328                   end
0329               end
0330               if grabbed,
0331                   break; %leave j loop
0332               end
0333           end
0334       end
0335   end
0336   
0337   %Check to make sure no epochs have been included more than once.  This
0338   %should never happen.
0339   if length(use_ep_this_set)~=length(unique(use_ep_this_set)),
0340      error(['The same trial of data has been grabbed more than once and will distort' ...
0341          ' the ERPimage.']);
0342   end
0343   
0344   %Make sure this file is contributing some data to the pool
0345   if isempty(use_ep_this_set),
0346     watchit(sprintf('File %s has no trials for the bins you are trying to analyze.\n', ...
0347         sfiles{a}));
0348   else
0349     for c=1:n_chan,
0350       %find channel id
0351       n_loc=length(chanlocs);
0352       chan_id=[];
0353       for d=1:n_loc,
0354           if strcmpi(chanlocs(d).labels,chans{c}),
0355             chan_id=d;
0356             break; %break out of d loop;
0357           end
0358       end
0359     
0360       if ~isempty(chan_id)
0361           %concatenate data
0362           chan_data{c}=[chan_data{c} squeeze(EEG.data(chan_id,:,use_ep_this_set))];
0363       else
0364         watchit(sprintf('File: %s does not have electrode: %s\n',sfiles{a}, ...
0365               chans{c}));
0366       end
0367     end
0368   end
0369 end
0370 
0371 %record bins that were loaded
0372 if ~isempty(p.Results.bins)
0373     eim_bins=p.Results.bins;
0374 else
0375     eim_bins=zeros(1,length(bindesc));
0376     for a=1:length(bindesc)
0377         if ~isempty(bindesc{a})
0378             eim_bins(a)=1;
0379         end
0380     end
0381     eim_bins=find(eim_bins);
0382 end
0383 
0384 if ~isempty(p.Results.out_fname)
0385     VerbReport(sprintf('Saving data to %s.',p.Results.out_fname),2,VERBLEVEL);
0386     save(p.Results.out_fname,'chans','chan_data','ep_info','chanlocs', ...
0387        'ep_times','sfiles','bindesc','srate','rtbins','rtmsec','eim_bins'); 
0388 else %make variables global for other functions to use
0389     VerbReport('Putting data in global variables.',2,VERBLEVEL);
0390 end
0391

Generated on Tue 10-May-2016 16:37:45 by m2html © 2005