% FITFS estimates the sample rate of the input data.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
% DESCRIPTION: Estimates the sample rate of the input data and detects if the
% data is evenly sampled or not.  Data where any of the fluctuations in the
% time difference between subsequent samples is greater than the one due to
% finite numerical precision is detected as unevenly sampled.
%
% CALL:     fs = fitfs(x)
%           [fs, t0] = fitfs(x)
%           [fs, t0, unevenly] = fitfs(x)
%
% INPUTS:   x   - sampling times vector
%
% OUTPUTS:  fs  - estimated samplig frequency
%           t0  - estimates start time
%           unevenly  - signals whether the data is regularly sampled or not
%
% VERSION:  $Id: fitfs.m,v 1.12 2010/05/04 11:23:59 nicolodi Exp $ 
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

function [fs, t0, unevenly] = fitfs(varargin)

  import utils.const.*

  % Get input vertices
  xi  = varargin{1};
  % Reshape x to match with linspace output
  ss = size(xi);
  if ss(1) > ss(2)
    xi = xi.';
  end
  d = diff(xi);
  
  % Special case of just a single number time-series
  if isempty(d)
    fs = 1;
    t0 = 0;
    unevenly = false;
    return
  end

  % Initial estimate
  dt = mean(d);
  fs = 1.0 / dt;
  t0 = xi(1);
  unevenly = false;
  
  % Strict check for unevenly sampled data. This detects as unevenly
  % sampled all data where any of the fluctuations in the time
  % difference between subsequent samples is greater than the one due
  % to finite numerical precision
  if any(abs(d - dt) > 2*eps(xi(2:end)))
    utils.helper.msg(msg.PROC1, 'unevenly sampled data detected');
    unevenly = true;

    % The median is much less sensible to outliers than the mean. It is
    % therefore a better estimate of the sampling frequency in case of
    % unevenly sampled data
    dt = median(d);
    fs = 1.0 / dt;
    t0 = 0;
  end

end