Home > data-analysis > manip > cevent > cevent_relative_intervals.m

cevent_relative_intervals

PURPOSE ^

cevent_relative_intervals - find time relative to start or end of event

SYNOPSIS ^

function relative_intervals = cevent_relative_intervals(cevent, whence, interval)

DESCRIPTION ^

 cevent_relative_intervals - find time relative to start or end of event

 cevent_relative_intervals(cevent, 'start', [-5 0])
   Make a new cevent.  For each instance of the original event, make a new
   instance that's the 5 seconds before the event starts, up to the moment
   the event starts.  Each new event will have the same ID as the original
   event that it was based on.

 cevent_relative_intervals(cevent, 'end', [-2 3])
   Make a new cevent, with the time bounds as 2 seconds before to 3
   seconds after the end of the original event.

 cevent_relative_intervals(cevent, 'startend', [1, -1])
   Make a new cevent, which is like the original event, but "shrunken" by
   1 second on each end.  WARNING: this may lead to an event with negative
   length, if the original event is less than 2 seconds long.
   (cevent_relative_intervals will emit a warning in this case)

 If the input variable is a plain event (2 columns) rather than a cevent
 (3 columns), that's handled, and the output will also be a 2-column
 event.

 The most straightforward way to use the function is to create another
 cevent, by having the INTERVAL argument be two elements long.  However,
 if you just wanted to find out a single point in time for each event, you
 could specify an INTERVAL like [-3], just one element long.  Or you could
 specify an INTERVAL that had 3 elements.  I don't know if this would be
 useful, but it was easy to write the function this way, so I'll just go
 ahead and document it.

 Example:

 >> cevent = [0 10 1; 20 21 2; 80 85 3]
 cevent =
      0    10     1
     20    21     2
     80    85     3

 >> cevent_relative_intervals(cevent, 'start', [-1 1]) 
 ans =
     -1     1     1
     19    21     2
     79    81     3
 
 >> cevent_relative_intervals(cevent, 'end', [-1 1])
 ans =
      9    11     1
     20    22     2
     84    86     3

 >> % Add 0 to start time and 0 to end time:
 >> % Should get the cevent back with no changes
 >> isequal(cevent, cevent_relative_intervals(cevent, 'startend', [0 0]))
 ans = 1

 >> % Make an event with negative length
 >> cevent_relative_intervals(cevent, 'startend', [5 -5])
 Warning: You seem to have constructed an event that ends before it
 begins!
 ***

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function relative_intervals = cevent_relative_intervals(cevent, whence, interval)
0002 % cevent_relative_intervals - find time relative to start or end of event
0003 %
0004 % cevent_relative_intervals(cevent, 'start', [-5 0])
0005 %   Make a new cevent.  For each instance of the original event, make a new
0006 %   instance that's the 5 seconds before the event starts, up to the moment
0007 %   the event starts.  Each new event will have the same ID as the original
0008 %   event that it was based on.
0009 %
0010 % cevent_relative_intervals(cevent, 'end', [-2 3])
0011 %   Make a new cevent, with the time bounds as 2 seconds before to 3
0012 %   seconds after the end of the original event.
0013 %
0014 % cevent_relative_intervals(cevent, 'startend', [1, -1])
0015 %   Make a new cevent, which is like the original event, but "shrunken" by
0016 %   1 second on each end.  WARNING: this may lead to an event with negative
0017 %   length, if the original event is less than 2 seconds long.
0018 %   (cevent_relative_intervals will emit a warning in this case)
0019 %
0020 % If the input variable is a plain event (2 columns) rather than a cevent
0021 % (3 columns), that's handled, and the output will also be a 2-column
0022 % event.
0023 %
0024 % The most straightforward way to use the function is to create another
0025 % cevent, by having the INTERVAL argument be two elements long.  However,
0026 % if you just wanted to find out a single point in time for each event, you
0027 % could specify an INTERVAL like [-3], just one element long.  Or you could
0028 % specify an INTERVAL that had 3 elements.  I don't know if this would be
0029 % useful, but it was easy to write the function this way, so I'll just go
0030 % ahead and document it.
0031 %
0032 % Example:
0033 %
0034 % >> cevent = [0 10 1; 20 21 2; 80 85 3]
0035 % cevent =
0036 %      0    10     1
0037 %     20    21     2
0038 %     80    85     3
0039 %
0040 % >> cevent_relative_intervals(cevent, 'start', [-1 1])
0041 % ans =
0042 %     -1     1     1
0043 %     19    21     2
0044 %     79    81     3
0045 %
0046 % >> cevent_relative_intervals(cevent, 'end', [-1 1])
0047 % ans =
0048 %      9    11     1
0049 %     20    22     2
0050 %     84    86     3
0051 %
0052 % >> % Add 0 to start time and 0 to end time:
0053 % >> % Should get the cevent back with no changes
0054 % >> isequal(cevent, cevent_relative_intervals(cevent, 'startend', [0 0]))
0055 % ans = 1
0056 %
0057 % >> % Make an event with negative length
0058 % >> cevent_relative_intervals(cevent, 'startend', [5 -5])
0059 % Warning: You seem to have constructed an event that ends before it
0060 % begins!
0061 % ***
0062 %
0063 
0064 % find what thing we should use to calculate the times from
0065 switch whence
0066     case 'start'
0067         basis = cevent(:, 1);
0068     case 'end'
0069         basis = cevent(:, 2);
0070     case 'startend'
0071         % Will call this function again with a different WHENCE argument.
0072         relative_intervals = do_startend(cevent, interval);
0073         return
0074         
0075     otherwise
0076         error('The WHENCE argument must be either ''start'' or ''end''.');
0077 end
0078 
0079 % make the time columns by adding each element of the interval to each
0080 % element of the time, in the correct column
0081 [time_grid, offset_grid] = ndgrid(interval, basis);
0082 timestamps = time_grid' + offset_grid';
0083 
0084 
0085 if size(cevent, 2) > 2
0086     relative_intervals = [timestamps cevent(:, 3:end)];
0087 else
0088     relative_intervals = timestamps;
0089 end
0090 
0091 check_non_negative(relative_intervals, numel(interval));
0092 end
0093 
0094 
0095 
0096 function relative_intervals = do_startend(cevent, interval)
0097 % deal with the specialness of doing one part from the start and one from
0098 % the end
0099 
0100 if size(interval) ~= [1,2]
0101     error('For a ''startend'' interval, the INTERVAL argument must be a 1x2 matrix.');
0102 end
0103 
0104 from_start = cevent_relative_intervals(cevent, 'start', interval(1));
0105 
0106 from_end = cevent_relative_intervals(cevent, 'end', interval(2));
0107 
0108 % there's a duplicate of the category column so you have to do (:,1)
0109 relative_intervals = horzcat(from_start(:, 1), from_end);
0110 
0111 check_non_negative(relative_intervals, 2);
0112 end
0113 
0114 
0115 function check_non_negative(relative_intervals, time_columns)
0116 % Make sure that, for all the events E, the start time of E is before the
0117 % end time of E.
0118 
0119 if ~ all(diff(relative_intervals(:, 1:time_columns), 1, 2) >= 0)
0120     warning('cevent_relative_intervals:negative_event_duration', ...
0121         'You seem to have constructed an event that ends before it begins!');
0122 end
0123 end
0124

Generated on Tue 23-May-2017 20:00:55 by m2html © 2005