


TRIGGEREVENTS Extracts data samples before/after a trigger signal.
E = TRIGGEREVENTS(X, TRIGGER, PRE, POST), where X is an M x 1 vector
and TRIGGER is a length M vector with P 0->~0 transitions, returns a
P x (PRE+1+POST) matrix E. The j-th row of E contains values of X
before and after the index of the j-th 0->~0 transition in TRIGGER;
PRE and POST specify the number pre- and post-transition samples,
respectively. While X and TRIGGER can be of any numeric type, E will
always be of type double.
E = TRIGGEREVENTS(X, TRIGGER, PRE, POST, GAP) ignores 0->~0
transitions in TRIGGER which occur <= GAP samples after a previous
unignored transition.
[E,TRIGLIST] = TRIGGEREVENTS(X, TRIGGER, ...) also returns indices
of TRIGGER at which 0->~0 transitions occur.
E = TRIGGEREVENTS(X, TRIGLIST, PRE, POST) directly specifies trigger
crossing indices rather than inferring them from 0->~0 transitions.
Here, TRIGLIST is a length P vector (P ~= M) containing only values
between 1 and M that are interpreted as row indices into X. The j-th
row of the resulting E matrix contains values of X indexed relative to
the j-th index in TRIGLIST. The GAP syntax described above is not
allowed in this case.
In all of the above cases, if X is an M x N matrix, E will be of size
P x (PRE+1+POST) x N and E(:,:,k) will be equal to the result of
TRIGGEREVENTS(X(:,k), ...).
When a trigger is fewer than PRE samples after the start of the X or
fewer than POST samples before the end, NaN values are returned for
the invalid X samples.
Examples:
triggerevents([1 2 3 4 5 6 7 8 9]', [1 1 0 0 1 1 1 1 1]', 2, 3)
and triggerevents([1 2 3 4 5 6 7 8 9]', [1 5], 2, 3)
both return [NaN NaN 1 2 3 4; 3 4 5 6 7 8].
triggerevents([1 2 3 4 5 6 7 8 9]', [1 1 0 0 1 0 1 1 1]', 2, 3, 4)
returns [NaN NaN 1 2 3 4; 5 6 7 8 9 NaN].
triggerevents([1 2 3 4 ; 5 6 7 8]', [2], 1, 1)
returns cat(3, [1 2 3], [5 6 7]).
See also LEADINGEDGES.

0001 function [events,trigger] = triggerevents(trace, trigger, pre, post, gap); 0002 %TRIGGEREVENTS Extracts data samples before/after a trigger signal. 0003 % E = TRIGGEREVENTS(X, TRIGGER, PRE, POST), where X is an M x 1 vector 0004 % and TRIGGER is a length M vector with P 0->~0 transitions, returns a 0005 % P x (PRE+1+POST) matrix E. The j-th row of E contains values of X 0006 % before and after the index of the j-th 0->~0 transition in TRIGGER; 0007 % PRE and POST specify the number pre- and post-transition samples, 0008 % respectively. While X and TRIGGER can be of any numeric type, E will 0009 % always be of type double. 0010 % 0011 % E = TRIGGEREVENTS(X, TRIGGER, PRE, POST, GAP) ignores 0->~0 0012 % transitions in TRIGGER which occur <= GAP samples after a previous 0013 % unignored transition. 0014 % 0015 % [E,TRIGLIST] = TRIGGEREVENTS(X, TRIGGER, ...) also returns indices 0016 % of TRIGGER at which 0->~0 transitions occur. 0017 % 0018 % E = TRIGGEREVENTS(X, TRIGLIST, PRE, POST) directly specifies trigger 0019 % crossing indices rather than inferring them from 0->~0 transitions. 0020 % Here, TRIGLIST is a length P vector (P ~= M) containing only values 0021 % between 1 and M that are interpreted as row indices into X. The j-th 0022 % row of the resulting E matrix contains values of X indexed relative to 0023 % the j-th index in TRIGLIST. The GAP syntax described above is not 0024 % allowed in this case. 0025 % 0026 % In all of the above cases, if X is an M x N matrix, E will be of size 0027 % P x (PRE+1+POST) x N and E(:,:,k) will be equal to the result of 0028 % TRIGGEREVENTS(X(:,k), ...). 0029 % 0030 % When a trigger is fewer than PRE samples after the start of the X or 0031 % fewer than POST samples before the end, NaN values are returned for 0032 % the invalid X samples. 0033 % 0034 % Examples: 0035 % triggerevents([1 2 3 4 5 6 7 8 9]', [1 1 0 0 1 1 1 1 1]', 2, 3) 0036 % and triggerevents([1 2 3 4 5 6 7 8 9]', [1 5], 2, 3) 0037 % both return [NaN NaN 1 2 3 4; 3 4 5 6 7 8]. 0038 % 0039 % triggerevents([1 2 3 4 5 6 7 8 9]', [1 1 0 0 1 0 1 1 1]', 2, 3, 4) 0040 % returns [NaN NaN 1 2 3 4; 5 6 7 8 9 NaN]. 0041 % 0042 % triggerevents([1 2 3 4 ; 5 6 7 8]', [2], 1, 1) 0043 % returns cat(3, [1 2 3], [5 6 7]). 0044 % 0045 % See also LEADINGEDGES. 0046 0047 %%%%%%%%%%%%%%%%%%%%%%%%%%%% Parse Inputs %%%%%%%%%%%%%%%%%%%%%%%%%%%% 0048 if (ndims(trace) > 2), error('TRACE can not have more than 2 dimensions.'); end; 0049 if ((length(trigger) > 1) & ~isvectord(trigger)), error('TRIGGER can not be a matrix.'); end; 0050 if (pre < 0 || post < 0), error('PRE and POST must be non-negative.'); end; 0051 0052 [M,N] = size(trace); 0053 trigger = trigger(:); % force column vector 0054 0055 if (length(trigger) == M) % if we haven't been given a trigger list ... 0056 trigger = find(leadingedges(trigger)); % ... find them 0057 else 0058 if (~all((trigger >= 1) & (trigger <= M))) 0059 error('All entries in a TRIGLIST must be between 1 and the # of rows in TRACE.'); 0060 end 0061 if (nargin > 4), error('GAP can not be used with a TRIGLIST.'); end; 0062 end 0063 P = length(trigger); 0064 Q = pre + post + 1; 0065 0066 if ((nargin > 4) && (gap < 0)), error('GAP must be non-negative.'); end; 0067 0068 %%%%%%%%%%%%%%%%%%%%%% Filter out events too close %%%%%%%%%%%%%%%%%%% 0069 if (nargin > 4) 0070 A = 1; B = 2; skip = repmat(logical(0), size(trigger)); 0071 while (B <= P) % skip trigs too close to last unskipped trig 0072 if ((trigger(B)-trigger(A)) <= gap), skip(B) = 1; 0073 else, A = B; 0074 end 0075 B = B + 1; 0076 end 0077 trigger(skip) = []; 0078 P = length(trigger); % this might have changed 0079 end 0080 0081 0082 %%%%%%%%%%%%%%%%%%%%%%%%%%%% Extract Events %%%%%%%%%%%%%%%%%%%%%%%%%% 0083 events = repmat(0, [P, Q, N]); % Force events to be type double 0084 0085 % Do each of these cases separately for efficiency; wasteful to 0086 % check for overruns when we don't need to. 0087 left = trigger <= pre; right = trigger > M-post; 0088 leftevents = find(left)'; rightevents = find(right)'; 0089 safeevents = find(~(left | right))'; 0090 0091 window = [-pre:post]; 0092 for k = leftevents 0093 inds = window + trigger(k); mask = (inds < 1); inds(mask) = 1; 0094 events(k,:,:) = trace(inds,:); 0095 events(k,mask,:) = NaN; 0096 end 0097 for k = safeevents 0098 inds = window + trigger(k); 0099 events(k,:,:) = trace(inds,:); 0100 end 0101 for k = rightevents 0102 inds = window + trigger(k); mask = (inds > M); inds(mask) = M; 0103 events(k,:,:) = trace(inds,:); 0104 events(k,mask,:) = NaN; 0105 end 0106 0107 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Clean Up %%%%%%%%%%%%%%%%%%%%%%%%%%%% 0108 % Screwy Matlab indexing: if inds is N x M, trace(inds) will be N x M ... 0109 % ... unless inds is 1 x M, in which case the dimensions of trace(inds) 0110 % are M x 1 if trace is a column vector. So ... 0111 if (size(events,2) == 1), events = events'; end