GetEvents

GetEvents - Get events.

  USAGE

    events = GetEvents(selection,<options>)

    selection      optional list of event descriptions; see examples below
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'output'      'times' returns the event times, 'indices' returns a
                   list of matching row indices, 'logical' returns a
                   list of matching row logical indices, and 'descriptions'
                   returns a list of descriptions (default = 'times')
    =========================================================================

  EXAMPLES

    % Get all event descriptions
    evt = GetEvents('output','descriptions');

    % Get all event times
    evt = GetEvents;

    % Get timestamps of events with description 'Ripple' or 'Sharp Wave'
    evt = GetEvents({'Ripple','Sharp Wave'});

    % Get indices of events with description 'Ripple'
    idx = GetEvents({'Ripple'},'output','indices');
    % When there is only one regexp, the {} can be omitted:
    idx = GetEvents('Ripple','output','indices');

    % Get logical indices of events with description starting with any letter
    % but 'R' and ending with ' beginning'
    m = GetEvents({'[^R].* beginning'},'output','logical');

  NOTE

    Type 'help regexp' for details on pattern matching using regular expressions.

0001 function events = GetEvents(selection,varargin)
0002 
0003 %GetEvents - Get events.
0004 %
0005 %  USAGE
0006 %
0007 %    events = GetEvents(selection,<options>)
0008 %
0009 %    selection      optional list of event descriptions; see examples below
0010 %    <options>      optional list of property-value pairs (see table below)
0011 %
0012 %    =========================================================================
0013 %     Properties    Values
0014 %    -------------------------------------------------------------------------
0015 %     'output'      'times' returns the event times, 'indices' returns a
0016 %                   list of matching row indices, 'logical' returns a
0017 %                   list of matching row logical indices, and 'descriptions'
0018 %                   returns a list of descriptions (default = 'times')
0019 %    =========================================================================
0020 %
0021 %  EXAMPLES
0022 %
0023 %    % Get all event descriptions
0024 %    evt = GetEvents('output','descriptions');
0025 %
0026 %    % Get all event times
0027 %    evt = GetEvents;
0028 %
0029 %    % Get timestamps of events with description 'Ripple' or 'Sharp Wave'
0030 %    evt = GetEvents({'Ripple','Sharp Wave'});
0031 %
0032 %    % Get indices of events with description 'Ripple'
0033 %    idx = GetEvents({'Ripple'},'output','indices');
0034 %    % When there is only one regexp, the {} can be omitted:
0035 %    idx = GetEvents('Ripple','output','indices');
0036 %
0037 %    % Get logical indices of events with description starting with any letter
0038 %    % but 'R' and ending with ' beginning'
0039 %    m = GetEvents({'[^R].* beginning'},'output','logical');
0040 %
0041 %  NOTE
0042 %
0043 %    Type 'help regexp' for details on pattern matching using regular expressions.
0044 
0045 % Copyright (C) 2004-2012 by Michaël Zugaro
0046 %
0047 % This program is free software; you can redistribute it and/or modify
0048 % it under the terms of the GNU General Public License as published by
0049 % the Free Software Foundation; either version 3 of the License, or
0050 % (at your option) any later version.
0051 
0052 global DATA;
0053 if isempty(DATA),
0054     error('No session defined (did you forget to call SetCurrentSession? Type ''help <a href="matlab:help Data">Data</a>'' for details).');
0055 end
0056 
0057 % Default values
0058 output = 'times';
0059 
0060 if nargin == 0,
0061     selection = '.*';
0062 end
0063 
0064 if mod(length(varargin),2) ~= 0,
0065     varargin = {selection varargin{:}};
0066     selection = [];
0067 else
0068     if isa(selection,'char'), selection = {selection}; end
0069 end
0070 
0071 % Parse options
0072 for i = 1:2:length(varargin),
0073     if ~ischar(varargin{i}),
0074         error(['Parameter ' num2str(i+firstIndex) ' is not a property (type ''help <a href="matlab:help GetEvents">GetEvents</a>'' for details).']);
0075     end
0076     switch(lower(varargin{i})),
0077         case 'output',
0078             output = lower(varargin{i+1});
0079             if ~isastring(output,'times','indices','logical','descriptions'),
0080                 error('Incorrect value for property ''output'' (type ''help <a href="matlab:help GetEvents">GetEvents</a>'' for details).');
0081             end
0082         otherwise,
0083             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help GetEvents">GetEvents</a>'' for details).']);
0084     end
0085 end
0086 
0087 events = DATA.events;
0088 if isempty(events.time), return; end
0089 
0090 % Selected events only
0091 nPatterns = length(selection);
0092 if nPatterns == 0,
0093     selected = logical(ones(size(events.time)));
0094 else
0095     selected = logical(zeros(size(events.time)));
0096     for i = 1:nPatterns,
0097         pattern = ['^' selection{i} '$'];
0098         matches = GetMatches(regexp(events.description,pattern));
0099         selected = selected | matches;
0100     end
0101 end
0102 if strcmp(output,'times'),
0103     events = events.time(selected,:);
0104 elseif strcmp(output,'indices'),
0105     events = find(selected);
0106 elseif strcmp(output,'logical'),
0107     events = selected;
0108 elseif strcmp(output,'descriptions'),
0109     events = {events.description{selected}}';
0110 end
0111 
0112 function m = GetMatches(c)
0113 
0114 m = zeros(length(c),1);
0115 for i = 1:length(c),
0116     m(i) = ~isempty(c{i});
0117 end