Threshold

Threshold - Find periods above/below threshold.

  Find periods where samples lay above or below a given threshold. Optionally,
  keep only periods of sufficient duration and ignore brief interruptions.

  USAGE

    [periods,in] = Threshold(x,criterion,threshold,<options>)

    x              <a href="matlab:help samples">samples</a> to process
    criterion      one of '>', '>=', '<' or '<='
    threshold      threshold
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'min'         minimum duration for inclusion (default = 0)
     'max'         maximum duration of ignored interruptions (default = 0)
    =========================================================================

  OUTPUT

    periods        list of [start stop] pairs
    in             list of [t s] pairs, where s is 1 if the the values
                   match the inclusion criterion (and 0 otherwise)

  SEE

    See also QuietPeriods.

0001 function [periods,in] = Threshold(x,criterion,threshold,varargin)
0002 
0003 %Threshold - Find periods above/below threshold.
0004 %
0005 %  Find periods where samples lay above or below a given threshold. Optionally,
0006 %  keep only periods of sufficient duration and ignore brief interruptions.
0007 %
0008 %  USAGE
0009 %
0010 %    [periods,in] = Threshold(x,criterion,threshold,<options>)
0011 %
0012 %    x              <a href="matlab:help samples">samples</a> to process
0013 %    criterion      one of '>', '>=', '<' or '<='
0014 %    threshold      threshold
0015 %    <options>      optional list of property-value pairs (see table below)
0016 %
0017 %    =========================================================================
0018 %     Properties    Values
0019 %    -------------------------------------------------------------------------
0020 %     'min'         minimum duration for inclusion (default = 0)
0021 %     'max'         maximum duration of ignored interruptions (default = 0)
0022 %    =========================================================================
0023 %
0024 %  OUTPUT
0025 %
0026 %    periods        list of [start stop] pairs
0027 %    in             list of [t s] pairs, where s is 1 if the the values
0028 %                   match the inclusion criterion (and 0 otherwise)
0029 %
0030 %  SEE
0031 %
0032 %    See also QuietPeriods.
0033 
0034 % Copyright (C) 2008-2011 by Michaël Zugaro
0035 %
0036 % This program is free software; you can redistribute it and/or modify
0037 % it under the terms of the GNU General Public License as published by
0038 % the Free Software Foundation; either version 3 of the License, or
0039 % (at your option) any later version.
0040 
0041 % Default values
0042 m = 0;
0043 M = 0;
0044 
0045 if nargin < 3,
0046     error('Incorrect number of parameters (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).');
0047 end
0048 if ~isastring(criterion,'>','>=','<','<='),
0049     error('Incorrect criterion (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).');
0050 end
0051 
0052 if mod(length(varargin),2) ~= 0,
0053     error('Incorrect number of parameters (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).');
0054 end
0055 
0056 % Parse options
0057 for i = 1:2:length(varargin),
0058     if ~ischar(varargin{i}),
0059         error(['Parameter ' num2str(i+1) ' is not a property (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).']);
0060     end
0061     switch(lower(varargin{i})),
0062         case 'min',
0063             m = varargin{i+1};
0064             if ~isdscalar(m,'>=0'),
0065                 error('Incorrect value for property ''min'' (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).');
0066             end
0067         case 'max',
0068             M = varargin{i+1};
0069             if ~isdscalar(m,'>=0'),
0070                 error('Incorrect value for property ''min'' (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).');
0071             end
0072         otherwise,
0073             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help Threshold">Threshold</a>'' for details).']);
0074     end
0075 end
0076 
0077 % Determine beginning/end of included periods
0078 ok = eval(['x(:,2)' criterion 'threshold']);
0079 crossings = diff(ok); % yields -1 for in->out crossings, and 1 for out->in crossings
0080 start = find(crossings == 1);
0081 stop = find(crossings == -1);
0082 
0083 % The previous code would ignore periods beginning at the first sample, or ending at the last sample; correct for this
0084 if ok(1),
0085     start = [1;start];
0086 end
0087 if ok(end),
0088     stop = [stop;length(ok)];
0089 end
0090 
0091 % Determine durations of excluded periods, and include brief ones
0092 durations = x(start(2:end),1) - x(stop(1:end-1),1);
0093 ignore = find(durations <= M);
0094 start(ignore+1) = [];
0095 stop(ignore) = [];
0096 
0097 % Keep only long enough periods
0098 durations = x(stop,1)-x(start,1);
0099 discard = durations < m;
0100 start(discard) = [];
0101 stop(discard) = [];
0102 
0103 % Outputs
0104 periods = [x(start,1) x(stop,1)];
0105 in = logical(zeros(size(x,1),1));
0106 for i = 1:length(start),
0107     in(start(i):stop(i)) = 1;
0108 end