eeg_context.m

含有多种ICA算法的eeglab工具箱

% eeg_context() - returns a matrix giving, for each event of specified ("target") type(s), 
%                 the latency (in ms) to the Nth preceding and/or following urevents (if any) 
%                 of specified ("neighbor") type(s). Can return the target event and urevent
%                 numbers, the neighbor urevent numbers, and the values of a specified urevent
%                 field for each of the neighbor urevents. Uses the EEG.urevent structure, plus
%                 EEG.event().urevent pointers to it.  For use in event handling scripts.
% Usage:
%             >>  [targs,unbrs,unbrtypes,delays,tfields,unfields] = ...
%                          eeg_context(EEG,{target},{neighbor},[positions],'field',alltargs);
% Inputs:
%
% EEG         - EEGLAB dataset structure containing EEG.event and EEG.urevent sub-structures
%
% Optional inputs:
%
% {target}   - cell array of strings naming event type(s) of the specified target events 
%               {default | []: all events}
% {neighbor} - cell array of strings naming event type(s) of the specified neighboring 
%               urevents {default | []: all neighboring events}.
% [positions] - int vector giving the relative positions of 'neighbor' type urevents to return. 
%               Ex: [-3 -2 -1 0 1 2 3] -> return the previous 3, current, and succeeding 3 
%               urevents of the specified {neighbor} types. [positions] values are arranged 
%               in ascending order before processing.  {default | []: 1 = first succeeding}
% 'field'     - string naming an (ur)event field to return values for neighbor urevents 
%               {default: no field info returned}
% alltargs    - string ('all'|[]) if 'all', return information about all target urevents,
%               even those on which no epoch in the current dataset is centered. 
%               {default: [] -> only return information on epoch-centered target events} 
% Outputs:
%
%  targs      - size (ntargets,3) matrix giving the indices of "target" events in the event 
%               structure in column 1 and in the urevent structure in column 2. Column 3 gives 
%               the epoch number in which the target has latency 0 (else NaN if no such epoch).
%  unbrs      - matrix of indices of "neighbor" events in the urevent structure (NaN if none).
%  unbrtypes  - if more than one type of {neighbor}, an int array giving the unbrs event type 
%               indices, else NaN if no such neighbor.  Ex: If nbr types = {'square','rt'}, 
%               (see below) then unbrtypes outputs are [1|2]; if nbr type = {'rt'}, returns [1]s.
%  delays     - matrix giving, for each {target} type event, delays (in ms) from the target 
%               events to the neighbor urevents . Else, returns NaN when no such event. 
%               Output matrix size: (ntargets,length(positions)). 
% tfields     - real or cell array of values of the (ur)event 'field' for the target events.
%               Values are the same type as the field values, else NaN if no such event.
% unfields    - real or cell array of values of the urevent 'field' for the neighbor urevents.
%               Values are the same type as the field values, else NaN if no such event.
% Example:
% 
% >> target   = {'square'};         % for all target events of type 'square'
% >> nbr      = {'square','rt'};    % counting neighbor events as either 'square' or 'rt'
% >>                                  
% >> [trgs,unbrs,unbrtypes,delays,tfld,nfld] = eeg_context(EEG,target,nbr,[-4 1],'position');
%    %
%    % Matrix 'delays' now contains latencies (in ms) from each 'square' target event to the 4th
%    % preceding and 1st succeeding 'rt' OR 'square' urevents (else NaN when none such). Outputs 
%    % 'tfld' and 'nfld' give the 'position' field values for target events and neighbor urevents,
%    % output 'unbrtypes', the type ('square' or 'rt') of the ('unbrs') neighbor urevents.
%
% Scott Makeig, SCCN, Institute for Neural Computation, UCSD, March 27, 2004

% Edit History:
% 5/25/04 test for isnan(urevent.duration) to detect real break events -sm
% 3/27/04 made no-such-event return NaNs; added {target} and {neighbor} defaults -sm
% 3/28/04 added test for boundary urevents; renamed relidx as positions, lats as delays  -sm
% 3/29/04 reorganized output order, adding unbrtypes -sm
% 3/29/04 changed unbrtypes to int array -sm
% 3/31/04 ruled out searching 'boundary' events -sm
% 5/06/04 completed the function -sm

function [targs,ur_nbrs,ur_nbrtypes,delays,tfields,nfields] = eeg_context(EEG,targets,neighbors,positions,field,alltargs)

verbose     = 1;    % flag useful info printout (1=on|0=off)
debug_print = 0;    % flag overly verbose printout
breakwarning = 0;   % flag no pre-4.4 warning given

if nargin < 1
   help eeg_context
   return
end

if nargin< 6 || isempty(alltargs)
  alltargs = 0;
elseif strcmpi(alltargs,'all')
  alltargs = 1;
else
  error('alltargs argument must be ''all'' or [].')
end

if ~isstruct(EEG)
   error('1st argument must be an EEG dataset structure');
end
if ~isfield(EEG,'event')
   error('no EEG.event structure found');
end
if ~isfield(EEG,'urevent')
   error('no EEG.urevent structure found');
end
if ~isfield(EEG.event,'urevent')
   error('no EEG.event().urevent field found');
end
      

if EEG.trials == 1 || ~isfield(EEG.event(1),'epoch')
  fprintf('Continuous data: returning info on all targets; no epoch info returned.\n')
  alltargs = 1;
  epochinfo = 0;
else
  epochinfo = 1;
end

nevents   = length(EEG.event);
nurevents = length(EEG.urevent);
%if length(EEG.urevent) < nevents
%  error('WARNING: In this dataset, number of urevents < number of events!?');
%end
%
%%%%%%%%%%%%%%%%%% Substitute input defaults %%%%%%%%%%%%%%%%%%%%
%
if nargin < 5 || isempty(field)
  NO_FIELD = 1;        % flag no field variable output
end
if nargin  < 4 || isempty(positions)
  positions = 1;    % default: find next
end
if nargin < 3 || isempty(neighbors)
  neighbors = {'_ALL'};  % flag neighbors are all neighboring events
end
if nargin < 2 || isempty(targets)
  targets = {'_ALL'};  % flag targets are all events
end

%
%%%%%%%%%%%%% Test and adjust input arguments %%%%%%%%%%%%%%%%%%%%
%
if ~iscell(targets)
  error('2nd argument "targets" must be a {cell array} of event types.');
end
if ~iscell(neighbors)
  error('3rd argument "neighbors" must be a {cell array} of event types.');
end

for k=1:length(targets) % make all target types strings
  if ~ischar(targets{k})
    targets{k} = num2str(targets{k});
  end
end
for k=1:length(neighbors) % make all neighbor types strings
  if ~ischar(neighbors{k})
    neighbors{k} = num2str(neighbors{k});
  end
end

tmp = sort(positions);  % reorder positions in ascending order
if sum(tmp==positions) ~= length(positions)
    fprintf('eeg_context(): returning neighbors in ascending order: ');
    for k=1:length(tmp)
         fprintf('%d ',tmp(k));
    end
    fprintf('\n');
end
positions = tmp;

%
%%%%%%%%%%%%%% Prepare to find "neighbor" events %%%%%%%%%%%%%%%%%%
%
zeroidx = find(positions == 0);            % find 0's in positions vector
negidx = find(positions < 0);
negpos = positions(negidx);
if ~isempty(negpos)
  negpos = abs(negpos(end:-1:1));          % work backwards, make negpos positive
  negidx = negidx(end:-1:1);               % index into output ur_nbrs
end
nnegpos   = length(negpos);                % number of negative positions to search for

posidx = find(positions>0);                % work forwards
pospos = positions(posidx);
npospos = length(pospos);                  % number of positive positions to search for

% 
%%%%%%%%%%%%%%%%%%%% Initialize output arrays %%%%%%%%%%%%%%%%%%%%%%
%
npos      = length(positions);
delays    = NaN*zeros(nevents,npos); % holds inter-event intervals in ms 
                                     % else NaN when no neighboring event
targs     = NaN*zeros(nevents,1);    % holds indices of targets
targepochs= NaN*zeros(nevents,1);    % holds numbers of the epoch centered
                                     % on each target (or NaN if none such)
ur_trgs   = NaN*zeros(nevents,1);    % holds indices of targets
ur_nbrs   = NaN*zeros(nevents,npos); % holds indices of neighbors
ur_nbrtypes  = NaN*zeros(nevents,npos);  % holds {neighbors} type indices

cellfld = -1;  % flag no field output specified

if ~exist('NO_FIELD','var') % if field values asked for
  if ~isfield(EEG.urevent,field)
     error('Specified field not found in urevent struct');
  end
  if ischar(EEG.urevent(1).(field)) ...
       || iscell(EEG.urevent(1).(field)) ...
          || isstruct(EEG.urevent(1).(field)),
     tfields = cell(nevents,1);
     nfields = cell(nevents,npos);
     cellfld = 1;  % flag that field outputs are cell arrays
  else % is number
     tfields = NaN*zeros(nevents,1);
     nfields = NaN*zeros(nevents,npos);
     cellfld = 0;  % flag that field outputs are numeric arrays
  end 
end

targetcount = 0; % index of current target

% Below:
% evidx   = current event index
% uridx   = current urevent index
%  uidx   = neighbor urevent index
%  tidx   = target type index
%  nidx   = neighbor type index
%  pidx   = position index
%
%%%%%%%%%%%for each event in the dataset %%%%%%%%%%%%%%%%%%%%
%
wb=waitbar(0,'Computing event contexts...','createcancelbtn','delete(gcf)');
noepochs = 0;                                      % counter of targets that are not epoch-centered
for evidx = 1:nevents                              % for each event in the dataset
waitbar(evidx/nevents);                            % update the waitbar fraction
 %
 %%%%%%%%%%%%%%%%%%%%%%%% find target events %%%%%%%%%%%%%%%%%
 %
 uridx = EEG.event(evidx).urevent;                 % find its urevent index
 istarget = 0;                                     % initialize target flag
 tidx = 1;                                         % initialize target type index
 %
 %%%%%%%%%%%%%%% cycle through target types %%%%%%%%%%%%%%%%%%
 %
 while ~istarget && tidx<=length(targets)           % for each potential target type
    if (strcmpi(num2str(EEG.urevent(uridx).type),targets(tidx)) ...
               || strcmp(targets{1},'_ALL'))        % if is a target type
      istarget=1;                                  % flag event as target
      targetcount = targetcount+1;                 % increment target count
      %
      %%%%%%%%%%%%% find 0th neighbors (=targets themselves)
      %
      if ~isempty(zeroidx)  % if the target event is asked for in the nbrs array
        delays(targetcount,zeroidx) = 0;
        if ~exist('NO_FIELD','var')
            if cellfld ==0
              nfields(targetcount,zeroidx) = EEG.urevent(uridx).(field);
            elseif cellfld == 1
              nfields{targetcount,zeroidx} = EEG.urevent(uridx).(field);
            end
        end
      end
      if epochinfo
            is0epoch = 0;
            for z = 1:length(EEG.event(evidx).epoch) % for each epoch the event is in
              ep = EEG.event(evidx).epoch(z);
              for e = 1:length(EEG.epoch(ep).event) % for each event in the epoch
                if EEG.epoch(ep).event(e) == evidx
                  if EEG.epoch(ep).eventlatency{e} == 0
                      targepochs(targetcount) = ep;
                      is0epoch = 1;
                      break;