function varargout = ltpda_arma_time(varargin)
% LTPDA_ARMA_TIME estimates the ARMA parameters of the transfer function
% relating an output to an input
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% DESCRIPTION: LTPDA_ARMA_TIME estimates the ARMA parameters of the
% transfer function relating an output to an input time series. The 
% algorithm uses the IV method to find a set of initial parameters 
% and then performs an iterative search based on the Optimization
% Toolbox.
%
% CALL:        b = ltpda_arma_time(ax,ay,pl)
%
% INPUTS:      ax  - analysis object containig the input time series
%              ay  - analysis object containig the output time series
%              pl  - parameters list
%
% OUTPUTS:     b  - cdata type analysis object containing the ARMA
%                   parameters and the residual of the fit
%
% PARAMETERS:  
%  MaxIter     -  Maximum number of iterations to be performed by the  
%                 iterative search (default 4e2)
%  MaxFunEvals -  Maximum number of function evaluations (default 1e2)
%  TolX        -  Tolerance on the estimated parameter  (default 1e-6)
%  TolFun      -  Tolerance on the evaluated function   (default 1e-6)
%  UpBound     -  Array of parameters upper bounds for the iterative search
%                 (default is 1 for each parameter)
%  LowBound    -  Array of parameters lower bounds for the iterative search
%                 (default is 1 for each parameter)
%  ARMANum     -  MA order of the ARMA filter (default 2)
%  ARMADen     -  AR order of the ARMA filter (default 1)
%
% VERSION:     $Id: ltpda_arma_time.m,v 1.1 2008/03/04 12:55:05 miquel Exp $
%
% HISTORY:     15-02-2008 M Nofrarias
%                 Creation
%
% 
% TODO: - Add parameters errors
%       - Pass from univariate to multivariate
% 
% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



%% Standard history variables 

ALGONAME = mfilename;
VERSION  = '$Id: ltpda_arma_time.m,v 1.1 2008/03/04 12:55:05 miquel Exp $';
CATEGORY = 'SIGPROC';


%% Check if this is a call for parameters
if nargin == 1 && ischar(varargin{1})
  in = char(varargin{1});
  if strcmpi(in, 'Params')
    varargout{1} = getDefaultPL();
    return
  elseif strcmpi(in, 'Version')
    varargout{1} = VERSION;
    return
  elseif strcmpi(in, 'Category')
    varargout{1} = CATEGORY;
    return
  end
end

%% Capture input variables names
invars = {};
as     = [];
ps     = [];
for j=1:nargin
   invars = [invars cellstr(inputname(j))];
   if isa(varargin{j}, 'ao')
     as = [as varargin{j}];
   end
   if isa(varargin{j}, 'plist')
     ps = [ps varargin{j}];
   end
end


%% Check plist
if isempty(ps)
  pl = getDefaultPL();
else
  pl = combine(ps, getDefaultPL);
end


%% Initialise variables
x=as(1).data.y;
y=as(2).data.y;
p = find(pl, 'ARMANum'); 
q = find(pl, 'ARMADen'); 
disp(sprintf('! ARMA orders p = %d, q = %d', p,q))

%% First estimate through Instrument Variables (IV) Method 

% Least squares 
for i=1:p
     obs1(:,i) = [zeros(i,1); x(1:length(x)-i)];
end
for i=1:q
     obs2(:,i) = [zeros(i,1); -y(1:length(y)-i)];
end

% LS estimation
obs = [obs1 obs2];
par0=(obs'*obs)\obs'*y

% filter observations with LS parameters
obs1_f = filter([par0(1:p)],[1 par0(p+1:p+q)],obs1);

% build instruments
inst = [obs1 obs1_f];

% IV estimation
par0=(inst'*obs)\inst'*y


%% Iterative search using the Optimization Toolbox


% Options for the lsqcurvefit function
opt = optimset(...
'MaxIter',find(pl, 'MaxIter'),...
'TolX',find(pl, 'TolXm'),...
'TolFun',find(pl, 'TolFun'),...
'MaxFunEvals',find(pl, 'MaxFunEvals'),...
'Display','off');

% Upper and Lower Bounds for the parameters 
ub=find(pl,'UpBound');
lb=find(pl,'LowBound');
if isempty(ub)
ub=ones(p+q,1);
pl = append(pl, param('UpBound', ub));
disp('! Parameters Upper Bound set to 1')
end
if isempty(lb)
lb=-ones(p+q,1);
pl = append(pl, param('LowBound', lb));
disp('! Parameters Lower Bound set to -1')
end    

% Call to the Optimization Toolbox function
[par,res]=lsqcurvefit(@(par,xdata)filter([par(1:p)],[1 par(p+1:p+q)],xdata),...
       par0,x,y,lb,ub,opt);
   
   
%% Build output ao
 
% New output history
h = history(ALGONAME, VERSION, pl,[as(1).hist as(2).hist]);
h = set(h,'invars', invars);

% Make output analysis object
b = ao([par; res]);
 
% Name, mfilename, description for this object
b = setnh(b,...
   'name', ['ARMA param. Input: ' sprintf('%s ', char(invars{1})) ' Output: ' char(invars{2})],...
   'mfilename', ALGONAME, ...
   'description', find(pl,'description'),...
   'hist', h);
 
varargout{1} = b;
 
 
%% --- FUNCTIONS ---


% Get default parameters
function plo = getDefaultPL();
disp('* creating default plist...');
plo = plist();
plo = append(plo, param('MaxIter',4e2));
plo = append(plo, param('MaxFunEvals',1e2));
plo = append(plo, param('TolX',1e-6));
plo = append(plo, param('TolFun',1e-6));
plo = append(plo, param('ARMANum',2));
plo = append(plo, param('ARMADen',1));
disp('* done.');