Home > chronux_2_00 > spikesort > utility > datatools > triggerevents.m

triggerevents

PURPOSE ^

TRIGGEREVENTS Extracts data samples before/after a trigger signal.

SYNOPSIS ^

function [events,trigger] = triggerevents(trace, trigger, pre, post, gap)

DESCRIPTION ^

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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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(false, 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

Generated on Fri 15-Aug-2008 11:35:42 by m2html © 2003