What is the purpose of the input argument 'Tolerance' in the risetime function?

The function 'risetime' has an optional input argument 'Tolerance' that as far as I can tell has no affect on the functionality.

In the code below I load some step data and then call the function with and without the 'Tolerance' argument. This gives me the same answer. I also call the function with the 'Tolerance' argument but without the 'PercentReferenceLevels' argument. Since the functions defaults to the values [10, 90] this also gives me the same answer.

load('Step_data.mat')

tol = 1;        % User defined tolerance

ipt = findchangepts(Step_data(:,2));        % Find step change index

% Find statelevels
Q1 = Step_data(ipt-1,2);
Q2 = Step_data(ipt,2);
Statelvls = sort([Q1,Q2]);

% Call the function with and without the 'Tolerance' input argument
[Reac_t_1, Reac_l_t_1, Reac_u_t_1, Reac_ll_1, Reac_ul_1] = risetime(Step_data(:,3),'StateLevels',Statelvls,'PercentReferenceLevels', [10,90],'Tolerance',tol);
[Reac_t_2, Reac_l_t_2, Reac_u_t_2, Reac_ll_2, Reac_ul_2] = risetime(Step_data(:,3),'StateLevels',Statelvls,'PercentReferenceLevels', [10,90]);
[Reac_t_3, Reac_l_t_3, Reac_u_t_3, Reac_ll_3, Reac_ul_3] = risetime(Step_data(:,3),'StateLevels',Statelvls,'Tolerance',tol);

My understanding of this function is that it is picking the points marked with crosses in the attached graph. These two points are defined by the input argument 'PercentReferenceLevels', so why the need for a 'Tolerance' input argument? What extra info could this provide to the function that would affect its output?

Answer 1

[William Rose]

@Samuel Foster,

Here's an example of tolerance making a difference:

t=0:999;
x=(mod(t/100,2)>=1 & mod(t/100,6)<5)+0.8*(mod(t/100,6)>=5);
x=x+0.2*(rand(size(x))-0.5); % add noise
%plot(t,x,'-r.')
risetime(x,PercentReferenceLevels=[20 80])

ans = 1×4

0.5805 0.5344 0.5408 0.5337

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

risetime(x,PercentReferenceLevels=[20 80],Tolerance=19)

ans = 1×5

0.5805 0.5344 1.4645 0.5408 0.5337

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

In the first case, with default value for tolerance, there were four risetimes. The third "high" state was not high enough to get recognized as a transition to the high state. When the tolerence is larger (second call to risetime), there were five risetimes, because the third high state WAS recognized as high. Tolerance defines the levels that must be reached in order to qualify as "making it into the state". And if the signal does make it into that state, then the Reference Levels are used, along with interpolation, to determine when the transitions happened.

[William Rose]

@Samuel Foster

Here's an example which is simpler thatn my example above, because this example does not use the PercentReferenceLevels option in either call to risetime().

t=0:999;
x=(mod(t/100,2)>=1 & mod(t/100,6)<5)+0.9*(mod(t/100,6)>=5);
x=x+0.1*(rand(size(x))-0.5); % add noise
risetime(x)

ans = 1×4

0.7605 0.7614 0.8747 0.8111

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

risetime(x,Tolerance=9)

●

ans = 1×5

0.7605 0.7614 0.8568 0.8747 0.8111

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

The difference that Tolerance makes is evident frmo the plots and console output above. With default Tolerance (Tolerance=2 (%)), only four transitions are found. With Tolerance=9, five transitions are found. The four risetimes that are found in both calls are the same in both calls.

[Samuel Foster]

Thank you, very clear explanation

[William Rose]

@Samuel Foster, you're welcome.