IsLastBefore

IsLastBefore - Identify last item before each of a list of timestamps.

 For each element i of a list of test timestamps, find in a list of reference timestamps
 the last element j smaller than i. Returns a list of logical indices (the elements of the
 test list which are smaller than all the elements of the reference timestamps are ignored).

  USAGE

    logical = IsLastBefore(timestamps,list,<options>)

    timestamps     a list of reference timestamps
    list           a list of test timestamps
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'strict'      'on' for strict (<) comparisons, 'off' otherwise (<=)
                   (default = 'off')
    =========================================================================

  SEE

    See also IsFirstAfter.

0001 function l = IsLastBefore(timestamps,list,varargin)
0002 
0003 %IsLastBefore - Identify last item before each of a list of timestamps.
0004 %
0005 % For each element i of a list of test timestamps, find in a list of reference timestamps
0006 % the last element j smaller than i. Returns a list of logical indices (the elements of the
0007 % test list which are smaller than all the elements of the reference timestamps are ignored).
0008 %
0009 %  USAGE
0010 %
0011 %    logical = IsLastBefore(timestamps,list,<options>)
0012 %
0013 %    timestamps     a list of reference timestamps
0014 %    list           a list of test timestamps
0015 %    <options>      optional list of property-value pairs (see table below)
0016 %
0017 %    =========================================================================
0018 %     Properties    Values
0019 %    -------------------------------------------------------------------------
0020 %     'strict'      'on' for strict (<) comparisons, 'off' otherwise (<=)
0021 %                   (default = 'off')
0022 %    =========================================================================
0023 %
0024 %  SEE
0025 %
0026 %    See also IsFirstAfter.
0027 
0028 % Copyright (C) 2004-2011 by Michaël Zugaro
0029 %
0030 % This program is free software; you can redistribute it and/or modify
0031 % it under the terms of the GNU General Public License as published by
0032 % the Free Software Foundation; either version 3 of the License, or
0033 % (at your option) any later version.
0034 
0035 strict = 'off';
0036 
0037 if nargin < 2 | mod(length(varargin),2) ~= 0,
0038   error('Incorrect number of parameters (type ''help <a href="matlab:help IsLastBefore">IsLastBefore</a>'' for details).');
0039 end
0040 
0041 % Parse parameter list
0042 for i = 1:2:length(varargin),
0043   if ~ischar(varargin{i}),
0044     error(['Parameter ' num2str(i+1) ' is not a property (type ''help <a href="matlab:help IsLastBefore">IsLastBefore</a>'' for details).']);
0045   end
0046   switch(lower(varargin{i})),
0047     case 'strict',
0048         strict = lower(varargin{i+1});
0049         if ~isastring(strict,'on','off'),
0050             error('Incorrect value for property ''strict'' (type ''help <a href="matlab:help IsLastBefore">IsLastBefore</a>'' for details).');
0051         end
0052     otherwise,
0053       error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help IsLastBefore">IsLastBefore</a>'' for details).']);
0054   end
0055 end
0056 
0057 % Make sure 'timestamps' looks like [t1;t2;...;tn] and 'list' like [l1 l2 ... lm]
0058 if min(size(timestamps)) ~= 1 | min(size(list)) ~= 1,
0059     error('Incorrect sizes (must be vectors)');
0060 end
0061 if size(timestamps,1) == 1,
0062     timestamps = timestamps';
0063 end
0064 if size(list,2) == 1,
0065     list = list';
0066 end
0067 
0068 % Now compare [t1 t1 ... t1;t2 t2 ... t2;...;tn tn ... tn] with [l1 l2 ... lm;l1 l2 ... lm;...;l1 l2 ... lm]
0069 if strcmp(strict,'on'),
0070     where = repmat(timestamps,1,length(list)) < repmat(list,length(timestamps),1);
0071 else
0072     where = repmat(timestamps,1,length(list)) <= repmat(list,length(timestamps),1);
0073 end
0074 % This yielded something like [1 1 1;1 1 1;...;0 1 1;...;0 0 1;...;0 0 0;...;0 0 0]
0075 % where the transition from 1 to 0 in each column indicates the index of the last element
0076 % in 'timestamps' inferior to the corresponding element in 'list'. Now, find these transitions.
0077 % (we append ones before and zeros after 'where' to handle the special cases where the first
0078 % element in 'timestamps' inferior to the element of 'list' is the last element of 'timestamps'
0079 % or does not exist).
0080 where = diff([ones(1,size(where,2));where;zeros(1,size(where,2))]);
0081 % Convert the resulting logical matrix into a list of logical indices
0082 l = sum(where,2) == -1;
0083 l = l(2:length(timestamps)+1);
0084 l = logical(l);