--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/classes/+utils/@math/stopfit.m	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,212 @@
+% STOPFIT verify fit accuracy checking for specified condition.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% DESCRIPTION:
+% 
+%     Verify fit accuracy checking for a specified condition. Available
+%     conditions are:
+% 
+%     Log Residuals difference
+%     Check if the minimum of the logarithmic difference between data and
+%     residuals is larger than a specified value. ie. if the conditioning
+%     value is 2, the function ensures that the difference between data and
+%     residuals is at lest 2 order of magnitude lower than data itsleves.
+%     Checking algorithm is:
+%     lsr = log10(abs(y))-log10(abs(rdl));
+%     min(lsr) > lrscond;
+% 
+%     Log Residuals difference and Root Mean Squared Error
+%     Check if the log difference between data and residuals is in
+%     larger than the value indicated in lsrcond and that the variation of
+%     the root mean squared error is lower than 10^(-1*msevar).
+%     Checking algorithm is:
+%     lsr = log10(abs(y))-log10(abs(rdl));
+%     (lsr > lrscond) && (mse < 10^(-1*lrsvarcond));
+% 
+% CALL:
+% 
+%      [ext,msg] = stopfit(y,rdl,mse,ctp,lrscond,msevar)
+% 
+% INPUTS:
+% 
+%     - y are the fitting data (in case of 'lrs' and 'lrsmse') or the
+%     fitted model (in case of 'rft' and 'rftmse')
+%     - rdl are the fit residuals
+%     - mse is a vector storing the values of root mean squared errors
+%     difference for the present and previuos iterations
+%     - order is the model order
+%     - ctp defines the conditioning type. Admitted values are:
+%       1) 'chival' check if the value of the Mean Squared Error is lower
+%       than 10^(-1*lsrcond).
+%       2) 'chivar' check if the value of the Mean Squared Error is lower
+%       than 10^(-1*lsrcond) and if the relative variation of mean squared error is
+%       lower than 10^(-1*msevar).
+%       3) 'lrs' check if the log difference between data and residuals is
+%       point by point larger than the value indicated in lsrcond. This
+%       mean that residuals are lsrcond order of magnitudes lower than
+%       data.
+%       4) 'lrsmse' check if the log difference between data and
+%       residuals is larger than the value indicated in lsrcond and if the
+%       relative variation of root mean squared error is lower than
+%       10^(-1*msevar).
+%       5) 'rft' check if the spectral flatness coefficient for the
+%       rersiduals is larger than the value passed in lrscond. In this case
+%       only values 0 < lrscond < 1 are allowed.
+%       6) 'rftmse' check if the spectral flatness coefficient for the
+%       rersiduals is larger than the value passed in lrscond and if the
+%       relative variation of root mean squared error is lower than 10^(-1*msevar).
+%       In this case only values 0 < lrscond < 1 are allowed.
+% 
+% OUTPUT:
+% 
+%     - ext is 1 if the specified condition is satisfied or 0 if not
+%     - msg is a string containing a messagge
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% VERSION: $Id: stopfit.m,v 1.8 2009/04/20 14:25:50 luigi Exp $
+%
+% HISTORY:     09-10-2008 L Ferraioli
+%                 Creation
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+function [ext,msg] = stopfit(y,rdl,mse,ctp,lrscond,msevar)
+
+  % switching between conditions
+  switch ctp
+    case 'chival'
+      if isempty(lrscond)
+        lrscond = 2; % Default value
+      end
+
+      hh = length(mse);
+      lsr = -1*log10(mse(hh));
+      if lsr > lrscond
+        msg = 'Reached tolerance for Mean Squared Error Value';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+
+    case 'chivar'
+
+      if isempty(lrscond)
+        a = 2; % Default value
+      else
+        a = lrscond;
+      end
+      if isempty(msevar)
+        b = 2; % Default value
+      else
+        b = msevar;
+      end
+
+      hh = length(mse);
+      tlsr = -1*log10(mse(hh));
+      if hh == 1
+        stc = 1;
+      else
+        stc = diff(mse(hh-1:hh))/mse(hh-1);
+      end
+      if all(tlsr > a) && (abs(stc) < 10^(-1*b))
+        msg = 'Reached tolerance for Mean Squared Error Value and Variation';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+    
+    case 'lrs'
+      if isempty(lrscond)
+        lrscond = 2; % Default value
+      end
+
+      lsr = log10(abs(y))-log10(abs(rdl));
+      if min(lsr) > lrscond
+        msg = 'Reached tolerance for Log residuals';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+
+    case 'lrsmse'
+
+      if isempty(lrscond)
+        a = 2; % Default value
+      else
+        a = lrscond;
+      end
+      if isempty(msevar)
+        b = 2; % Default value
+      else
+        b = msevar;
+      end
+
+      tlsr = log10(abs(y))-log10(abs(rdl));
+      hh = length(mse);
+      if hh == 1
+        stc = 1;
+      else
+        stc = diff(mse(hh-1:hh))/mse(hh-1);
+      end
+      if all(tlsr > a) && (abs(stc) < 10^(-1*b))
+        msg = 'Reached tolerance for Log Residuals and Mean Squared Error variation';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+      
+    case 'rft' % Check that residuals flatness is larger than a certain value
+      % Calculate residual flatness
+      rf = utils.math.spflat(abs(rdl));
+      
+      % Checking that lrscond has the correct value
+      a = lrscond;
+      if (a >= 1) || (a < 0)
+        a = 0.5;
+      end
+      if rf > a
+        msg = 'Reached tolerance for residuals spectral flatness';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+      
+    case 'rftmse'
+      
+      % Calculate residual flatness
+      rf = utils.math.spflat(abs(rdl));
+      
+      % Checking that lrscond has the correct value
+      a = lrscond;
+      if (a >= 1) || (a < 0)
+        a = 0.5;
+      end
+      
+      if isempty(msevar)
+        b = 2; % Default value
+      else
+        b = msevar;
+      end
+
+      hh = length(mse);
+      if hh == 1
+        stc = 1;
+      else
+        stc = diff(mse(hh-1:hh))/mse(hh-1);
+      end
+      if (rf > a) && (abs(stc) < 10^(-1*b))
+        msg = 'Reached tolerance for residuals spectral flatness and Mean Squared Error variation';
+        ext = true;
+      else
+        ext = false;
+        msg = '';
+      end
+      
+        
+
+  end
+