├── adjph.m ├── tquant.m ├── arconf.m ├── acf.m ├── arord.m ├── arqr.m ├── CHANGES ├── LICENSE ├── README.md ├── arsim.m ├── arres.m ├── arfit.m ├── armode.m └── ardem.m /adjph.m: -------------------------------------------------------------------------------- 1 | function ox=adjph(x) 2 | %ADJPH Normalization of columns of a complex matrix. 3 | % 4 | % Given a complex matrix X, OX=ADJPH(X) returns the complex matrix OX 5 | % that is obtained from X by multiplying column vectors of X with 6 | % phase factors exp(i*phi) such that the real part and the imaginary 7 | % part of each column vector of OX are orthogonal and the norm of the 8 | % real part is greater than or equal to the norm of the imaginary 9 | % part. 10 | % 11 | % ADJPH is called by ARMODE. 12 | % 13 | % See also ARMODE. 14 | 15 | % Modified 16-Dec-99 16 | % Author: Tapio Schneider 17 | % tapio@gps.caltech.edu 18 | 19 | for j = 1:size(x,2) 20 | a = real(x(:,j)); % real part of jth column of x 21 | b = imag(x(:,j)); % imag part of jth column of x 22 | phi = .5*atan( 2*sum(a.*b)/(b'*b-a'*a) ); 23 | bnorm = norm(sin(phi).*a+cos(phi).*b); % norm of new imaginary part 24 | anorm = norm(cos(phi).*a-sin(phi).*b); % norm of new real part 25 | if bnorm > anorm 26 | if phi < 0 27 | phi = phi-pi/2; 28 | else 29 | phi = phi+pi/2; 30 | end 31 | end 32 | ox(:,j) = x(:,j).*exp(i*phi); 33 | end 34 | 35 | 36 | 37 | 38 | 39 | 40 | -------------------------------------------------------------------------------- /tquant.m: -------------------------------------------------------------------------------- 1 | function t=tquant(n, p) 2 | %TQUANT Quantiles of Student's t distribution 3 | % 4 | % TQUANT(n, p) is the p-quantile of a t distributed random variable 5 | % with n degrees of freedom; that is, TQUANT(n, p) is the value below 6 | % which 100p percent of the t distribution with n degrees of freedom 7 | % lies. 8 | 9 | % Modified 13-Jul-06 10 | % Author: Tapio Schneider 11 | % tapio@gps.caltech.edu 12 | % Nir Krakauer, 19-Mar-11: modified call to fzero to work in Octave 13 | 14 | % References: 15 | % L. Devroye, 1986: "Non-Uniform Random Variate Generation", Springer 16 | % 17 | % M. Abramowitz and I. A. Stegun, 1964: "Handbook of Mathematical 18 | % Functions" 19 | % 20 | % See also: tcdf.m in the Matlab Statistics Toolbox (evaluates 21 | % cumulative distribution function of Student's t) 22 | 23 | if (n ~= round(n) | n < 1) 24 | error('Usage: TQUANT(n,p) - Degrees of freedom n must be positive integer.') 25 | end 26 | 27 | if (p<0 | p>1) 28 | error('Usage: TQUANT(n,p) - Probability p must be in [0,1].') 29 | elseif p == 1 30 | t = Inf; 31 | return 32 | elseif p == 0 33 | t = -Inf; 34 | return 35 | end 36 | 37 | if n == 1 38 | % Cauchy distribution (cf. Devroye [1986, pp. 29 and 450]) 39 | t = tan(pi*(p-.5)); 40 | elseif p >= 0.5 41 | % positive t-values (cf. M. Abramowitz and I. A. Stegun [1964, 42 | % Chapter 26]) 43 | b0 = [0, 1]; 44 | f = @(b) 1 - betainc(b, n/2, .5)/2 - p; 45 | b = fzero(f, b0); 46 | t = sqrt(n/b-n); 47 | else 48 | % negative t-values 49 | b0 = [0, 1]; 50 | f = @(b) betainc(b, n/2, .5)/2 - p; 51 | b = fzero(f, b0); 52 | t = -sqrt(n/b-n); 53 | end 54 | -------------------------------------------------------------------------------- /arconf.m: -------------------------------------------------------------------------------- 1 | function [Aerr, werr]=arconf(A, C, w, th) 2 | %ARCONF Confidence intervals for AR coefficients. 3 | % 4 | % For an AR(p) model that has been fitted with ARFIT, 5 | % [Aerr,werr]=ARCONF(A,C,w,th) computes the margins of error Aerr and 6 | % werr such that (A +/- Aerr) and (w +/- werr) are approximate 95% 7 | % confidence intervals for the elements of the coefficient matrix A 8 | % and for the components of the intercept vector w. The input 9 | % arguments of ARCONF are output of AR. 10 | % 11 | % If no intercept vector w has been fitted with ARFIT (i.e., the flag 12 | % 'zero' was an input argument of ARFIT), then [Aerr]=ARCONF(A,C,th) 13 | % computes the margins of error only for the elements of the 14 | % coefficient matrix A. 15 | % 16 | % The confidence intervals are based on Student's t distribution, 17 | % which for small samples yields only approximate confidence 18 | % intervals. Inferences drawn from small samples must therefore be 19 | % interpreted cautiously. 20 | % 21 | % See also ARFIT. 22 | 23 | % Modified 30-Dec-99 24 | % Author: Tapio Schneider 25 | % tapio@gps.caltech.edu 26 | 27 | ccoeff = .95; % confidence coefficient 28 | m = size(C,1); % dimension of state space 29 | p = size(A,2)/m; % order of model 30 | 31 | if (nargin == 3) 32 | % no intercept vector has been fitted 33 | Aaug = A; 34 | th = w; 35 | w = []; 36 | np = m*p; % number of parameter vectors of size m 37 | else 38 | Aaug = [w A]; 39 | np = m*p+1; % number of parameter vectors of size m 40 | end 41 | % number of degrees of freedom for residual covariance matrix 42 | dof = th(1,1); 43 | % quantile of t distribution for given confidence coefficient and dof 44 | t = tquant(dof, .5+ccoeff/2); 45 | 46 | % Get matrix Uinv that appears in the covariance matrix of the least squares 47 | % estimator 48 | Uinv = th(2:size(th,1), :); 49 | 50 | % Compute approximate confidence intervals for elements of Aaug 51 | Aaug_err = zeros(m, np); 52 | for j=1:m 53 | for k=1:np 54 | Aaug_err(j,k) = t * sqrt( Uinv(k ,k)* C(j,j) ); 55 | end 56 | end 57 | 58 | if (nargin == 3) 59 | % No intercept vector has been fitted 60 | Aerr = Aaug_err; 61 | else 62 | % An intercept vector has been fitted => return margins of error 63 | % for intercept vector and for AR coefficients separately 64 | werr = Aaug_err(:, 1); 65 | Aerr = Aaug_err(:, 2:np); 66 | end 67 | -------------------------------------------------------------------------------- /acf.m: -------------------------------------------------------------------------------- 1 | function []=acf(x, k, caption) 2 | %ACF Plot of sample autocorrelation function. 3 | % 4 | % ACF(x) plots the sample autocorrelation function of the univariate 5 | % time series in vector x. By default, the sample autocorrelation 6 | % function is plotted up to lag 25. ACF(x,k) plots the sample 7 | % autocorrelation function up to lag k. ACF(X,k,'name') sets the 8 | % title of the plot to 'name'. 9 | % 10 | % The approximate 95% confidence limits of the autocorrelation 11 | % function of an IID process of the same length as X are also 12 | % displayed. Sample autocorrlations lying outside the 95% confidence 13 | % intervals of an IID process are marked by an asterisk. 14 | % 15 | % ACF requires XCORR from the Signal Processing Toolbox. 16 | % 17 | % See also XCORR. 18 | 19 | % Modified 30-Dec-99 20 | % Author: Tapio Schneider 21 | % tapio@gps.caltech.edu 22 | 23 | if ~exist('xcorr') 24 | error('ACF requires XCORR from the Signal Processing Toolbox.') 25 | end 26 | 27 | [m,n] = size(x); 28 | if (min(m,n) > 1) error('Time series must be univariate.'); end 29 | n = max(m,n); 30 | 31 | if (nargin < 3) caption='ACF'; end 32 | if (nargin < 2) k=25; end 33 | if (nargin < 1) error('Usage: ACF(vector).'); end 34 | 35 | % Compute autocorrelation sequence with XCORR from the Signal 36 | % Processing Toolbox 37 | cor = xcorr(x,'coeff'); 38 | rho = cor(n:n+k); % autocorrelation function up to lag k 39 | abscis = [0:1:k]; % abscissa for plot 40 | 41 | % Approximate 95% confidence limits for IID process of the same length 42 | bound = zeros(size(rho)); 43 | bound = bound + 1.96/sqrt(n); 44 | 45 | % Initialize abscissas and ordinates for ACF values within and outside the 46 | % approximate 95% confidence intervals of IID process 47 | inabsc = zeros(1, k+1); 48 | inl = zeros(1, k+1); 49 | outabsc = zeros(1, k+1); 50 | outl = zeros(1, k+1); 51 | 52 | % Find lags within and outside approximate 95% confidence 53 | % intervals; start with lag 0 54 | inl(1) = rho(1); % stores ACF at lags within cfd intervals 55 | inabsc(1) = 0; % lags at which ACF is within cfd intervals 56 | nin = 1; % number of points within confidence intervals 57 | nout = 0; % number of points outside confidence intervals 58 | for i=2:k+1 59 | if abs(rho(i)) > bound(1) % point outside confidence intervals 60 | nout = nout+1; 61 | outl(nout) = rho(i); 62 | outabsc(nout) = i-1; 63 | else % point within confidence intervals 64 | nin = nin+1; 65 | inl(nin) = rho(i); 66 | inabsc(nin) = i-1; 67 | end; 68 | end; 69 | 70 | % Plot ACF 71 | plot(abscis, rho, abscis, bound, '-.', abscis, -bound, '-.', ... 72 | outabsc(1:nout), outl(1:nout), '*', ... 73 | inabsc(1:nin), inl(1:nin), 'o'); 74 | axis([0 k -1 1]) 75 | title(caption) 76 | xlabel('Lag') 77 | ylabel('Autocorrelation function') 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | -------------------------------------------------------------------------------- /arord.m: -------------------------------------------------------------------------------- 1 | function [sbc, fpe, logdp, np] = arord(R, m, mcor, ne, pmin, pmax) 2 | %ARORD Evaluates criteria for selecting the order of an AR model. 3 | % 4 | % [SBC,FPE]=ARORD(R,m,mcor,ne,pmin,pmax) returns approximate values 5 | % of the order selection criteria SBC and FPE for models of order 6 | % pmin:pmax. The input matrix R is the upper triangular factor in the 7 | % QR factorization of the AR model; m is the dimension of the state 8 | % vectors; the flag mcor indicates whether or not an intercept vector 9 | % is being fitted; and ne is the number of block equations of size m 10 | % used in the estimation. The returned values of the order selection 11 | % criteria are approximate in that in evaluating a selection 12 | % criterion for an AR model of order p < pmax, pmax-p initial values 13 | % of the given time series are ignored. 14 | % 15 | % ARORD is called by ARFIT. 16 | % 17 | % See also ARFIT, ARQR. 18 | 19 | % For testing purposes, ARORD also returns the vectors logdp and np, 20 | % containing the logarithms of the determinants of the (scaled) 21 | % covariance matrix estimates and the number of parameter vectors at 22 | % each order pmin:pmax. 23 | 24 | % Modified 17-Dec-99 25 | % Author: Tapio Schneider 26 | % tapio@gps.caltech.edu 27 | 28 | imax = pmax-pmin+1; % maximum index of output vectors 29 | 30 | % initialize output vectors 31 | sbc = zeros(1, imax); % Schwarz's Bayesian Criterion 32 | fpe = zeros(1, imax); % log of Akaike's Final Prediction Error 33 | logdp = zeros(1, imax); % determinant of (scaled) covariance matrix 34 | np = zeros(1, imax); % number of parameter vectors of length m 35 | np(imax)= m*pmax+mcor; 36 | 37 | % Get lower right triangle R22 of R: 38 | % 39 | % | R11 R12 | 40 | % R=| | 41 | % | 0 R22 | 42 | % 43 | R22 = R(np(imax)+1 : np(imax)+m, np(imax)+1 : np(imax)+m); 44 | 45 | % From R22, get inverse of residual cross-product matrix for model 46 | % of order pmax 47 | invR22 = inv(R22); 48 | Mp = invR22*invR22'; 49 | 50 | % For order selection, get determinant of residual cross-product matrix 51 | % logdp = log det(residual cross-product matrix) 52 | logdp(imax) = 2.*log(abs(prod(diag(R22)))); 53 | 54 | % Compute approximate order selection criteria for models of 55 | % order pmin:pmax 56 | i = imax; 57 | for p = pmax:-1:pmin 58 | np(i) = m*p + mcor; % number of parameter vectors of length m 59 | if p < pmax 60 | % Downdate determinant of residual cross-product matrix 61 | % Rp: Part of R to be added to Cholesky factor of covariance matrix 62 | Rp = R(np(i)+1:np(i)+m, np(imax)+1:np(imax)+m); 63 | 64 | % Get Mp, the downdated inverse of the residual cross-product 65 | % matrix, using the Woodbury formula 66 | L = chol(eye(m) + Rp*Mp*Rp')'; 67 | N = L \ Rp*Mp; 68 | Mp = Mp - N'*N; 69 | 70 | % Get downdated logarithm of determinant 71 | logdp(i) = logdp(i+1) + 2.* log(abs(prod(diag(L)))); 72 | end 73 | 74 | % Schwarz's Bayesian Criterion 75 | sbc(i) = logdp(i)/m - log(ne) * (ne-np(i))/ne; 76 | 77 | % logarithm of Akaike's Final Prediction Error 78 | fpe(i) = logdp(i)/m - log(ne*(ne-np(i))/(ne+np(i))); 79 | 80 | % Modified Schwarz criterion (MSC): 81 | % msc(i) = logdp(i)/m - (log(ne) - 2.5) * (1 - 2.5*np(i)/(ne-np(i))); 82 | 83 | i = i-1; % go to next lower order 84 | end 85 | 86 | -------------------------------------------------------------------------------- /arqr.m: -------------------------------------------------------------------------------- 1 | function [R, scale]=arqr(v, p, mcor) 2 | %ARQR QR factorization for least squares estimation of AR model. 3 | % 4 | % [R, SCALE]=ARQR(v,p,mcor) computes the QR factorization needed in 5 | % the least squares estimation of parameters of an AR(p) model. If 6 | % the input flag mcor equals one, a vector of intercept terms is 7 | % being fitted. If mcor equals zero, the process v is assumed to have 8 | % mean zero. The output argument R is the upper triangular matrix 9 | % appearing in the QR factorization of the AR model, and SCALE is a 10 | % vector of scaling factors used to regularize the QR factorization. 11 | % 12 | % ARQR is called by ARFIT. 13 | % 14 | % See also ARFIT. 15 | 16 | % Modified 29-Dec-99 17 | % 24-Oct-10 Tim Mullen (added support for multiple realizatons) 18 | % 19 | % Author: Tapio Schneider 20 | % tapio@gps.caltech.edu 21 | 22 | % n: number of time steps (per realization) 23 | % m: number of variables (dimension of state vectors) 24 | % ntr: number of realizations (trials) 25 | [n,m,ntr] = size(v); 26 | 27 | ne = ntr*(n-p); % number of block equations of size m 28 | np = m*p+mcor; % number of parameter vectors of size m 29 | 30 | % If the intercept vector w is to be fitted, least squares (LS) 31 | % estimation proceeds by solving the normal equations for the linear 32 | % regression model 33 | % 34 | % v(k,:)' = Aaug*u(k,:)' + noise(C) (1) 35 | % 36 | % with Aaug=[w A] and `predictors' 37 | % 38 | % u(k,:) = [1 v(k-1,:) ... v(k-p,:)]. (2a) 39 | % 40 | % If the process mean is taken to be zero, the augmented coefficient 41 | % matrix is Aaug=A, and the regression model 42 | % 43 | % u(k,:) = [v(k-1,:) ... v(k-p,:)] (2b) 44 | % 45 | % is fitted. 46 | % The number np is the dimension of the `predictors' u(k). 47 | % 48 | % If multiple realizations are given (ntr > 1), they are appended 49 | % as additional ntr-1 blocks of rows in the normal equations (1), and 50 | % the 'predictors' (2) correspondingly acquire additional row blocks. 51 | 52 | % Initialize the data matrix K (of which a QR factorization will be computed) 53 | K = zeros(ne,np+m); % initialize K 54 | if (mcor == 1) 55 | % first column of K consists of ones for estimation of intercept vector w 56 | K(:,1) = ones(ne,1); 57 | end 58 | 59 | % Assemble `predictors' u in K 60 | for itr=1:ntr 61 | for j=1:p 62 | K((n-p)*(itr-1) + 1 : (n-p)*itr, mcor+m*(j-1)+1 : mcor+m*j) = ... 63 | squeeze(v(p-j+1:n-j, :, itr)); 64 | end 65 | % Add `observations' v (left hand side of regression model) to K 66 | K((n-p)*(itr-1) + 1 : (n-p)*itr, np+1 : np+m) = squeeze(v(p+1:n, :, itr)); 67 | end 68 | 69 | % Compute regularized QR factorization of K: The regularization 70 | % parameter delta is chosen according to Higham's (1996) Theorem 71 | % 10.7 on the stability of a Cholesky factorization. Replace the 72 | % regularization parameter delta below by a parameter that depends 73 | % on the observational error if the observational error dominates 74 | % the rounding error (cf. Neumaier, A. and T. Schneider, 2001: 75 | % "Estimation of parameters and eigenmodes of multivariate 76 | % autoregressive models", ACM Trans. Math. Softw., 27, 27--57.). 77 | q = np + m; % number of columns of K 78 | delta = (q^2 + q + 1)*eps; % Higham's choice for a Cholesky factorization 79 | scale = sqrt(delta)*sqrt(sum(K.^2)); 80 | R = triu(qr([K; diag(scale)])); -------------------------------------------------------------------------------- /CHANGES: -------------------------------------------------------------------------------- 1 | 04-May-13 * Minor changes in documentation of ARFIT 2 | 21-Mar-11 * Changed call to FZERO in TQUANT to be compatible with 3 | Octave. [Suggested by Nir Krakauer.] 4 | 5 | 01-Dec-10 * Added support for multiple realizations (with 6 | contributions by Tim Mullen) 7 | * ARRES now returns the actual residuals of the AR 8 | model, not centered residuals as before 9 | 10 | 13-Jul-06 * Updated call of FZERO in TQUANT for compatibility with 11 | newer Matlab versions (tested with Matlab 7.2) 12 | 13 | 01-Jun-02: * The ARfit homepage has moved to www.gps.caltech.edu/~tapio/arfit/ 14 | 15 | 14-Oct-00: * Minor revision of the papers describing the algorithms. 16 | * Minor changes to some modules to improve error handling and 17 | warning messages. 18 | 19 | 06-Sep-00: * The ARfit homepage has moved to www.math.nyu.edu/~tapio/arfit/ 20 | 21 | 15-Apr-00: * Changed call of Matlab function FZERO in TQUANT to old 22 | format in order to ensure compatibility with 23 | Windows/Mac versions of Matlab. [Suggested by Vico Klump.] 24 | 25 | 10-Jan-00: * The two papers describing the algorithms implemented in ARfit 26 | have been extensively revised. 27 | * Confidence intervals are now based on Student's t 28 | distribution, no longer on the chi-squared distribution. 29 | 95% margins of error are returned instead of standard 30 | errors. 31 | * The regularization in ARQR has changed. 32 | * The margin of error for the period of a purely relaxatory mode 33 | with infinite period is now zero, not NaN as before. 34 | 35 | 17-Dec-99: * Renamed the demo-module from ARFIT to ARDEM. 36 | * Renamed the least squares estimation module from AR to 37 | ARFIT (in order to avoid conflicts with ar.m in the system 38 | identification toolbox). 39 | * Rewrote some of the help entries and annotations. 40 | * Changed output of ARCONF. The approximate confidence intervals 41 | are now returned as separate variables, no longer as imaginary 42 | parts of the parameter matrices. 43 | * The modification MSC of Schwarz's Bayesian Criterion for order 44 | selection is no longer supported. 45 | * Changed definition of the excitation (change affects only 46 | higher-order models). 47 | 48 | 12-Aug-98: * Fixed bug (in AR) that affected the computation of confidence 49 | intervals for the intercept vector. (The condition-improving 50 | scaling was not undone before the matrix Uinv was returned.) 51 | 52 | 02-Aug-98: * Fixed bug in ARSIM. (ARSIM did not simulate multivariate AR(1) 53 | processes correctly.) 54 | * Replaced DOT(a,b) by SUM(a.*b) because DOT(a,b) is neither 55 | part of older Matlab distributions nor part of Octave. 56 | Only ADJPH was affected by this change, which increases the 57 | portability of ARfit. 58 | * Forced dot_lam in ARMODE to be a column vector in order to 59 | ensure compatibility with Octave. 60 | * Removed (from AR) calls of the function LOWER in order to 61 | ensure compatibility with Octave. 62 | * Readability of the code has been improved. 63 | * All modules have been tested under Matlab 5. 64 | 65 | 06-Sep-97: * Release of ARfit version 2.0 with accelerated 66 | computation of order selection criteria. 67 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright © 2001 Association for Computing Machinery, Inc. Permission to include in application software or to make digital or hard copies of part or all of this work is subject to the following licensing agreement. 2 | 3 | # ACM Software License Agreement 4 | 5 | All software, both binary and source published by the Association for Computing Machinery (hereafter, Software) is copyrighted by the Association (hereafter, ACM) and ownership of all right, title and interest in and to the Software remains with ACM. By using or copying the Software, User agrees to abide by the terms of this Agreement. 6 | 7 | # Noncommercial Use 8 | The ACM grants to you (hereafter, User) a royalty-free, nonexclusive right to execute, copy, modify and distribute both the binary and source code solely for academic, research and other similar noncommercial uses, subject to the following conditions: 9 | 10 | User acknowledges that the Software is still in the development stage and that it is being supplied "as is," without any support services from ACM. Neither ACM nor the author makes any representations or warranties, express or implied, including, without limitation, any representations or warranties of the merchantability or fitness for any particular purpose, or that the application of the software, will not infringe on any patents or other proprietary rights of others. 11 | 12 | ACM shall not be held liable for direct, indirect, incidental or consequential damages arising from any claim by User or any third party with respect to uses allowed under this Agreement, or from any use of the Software. 13 | 14 | User agrees to fully indemnify and hold harmless ACM and/or the author(s) of the original work from and against any and all claims, demands, suits, losses, damages, costs and expenses arising out of the User's use of the Software, including, without limitation, arising out of the User's modification of the Software. 15 | 16 | User may modify the Software and distribute that modified work to third parties provided that: (a) if posted separately, it clearly acknowledges that it contains material copyrighted by ACM (b) no charge is associated with such copies, (c) User agrees to notify ACM and the Author(s) of the distribution, and (d) User clearly notifies secondary users that such modified work is not the original Software. 17 | 18 | User agrees that ACM, the authors of the original work and others may enjoy a royalty-free, non-exclusive license to use, copy, modify and redistribute these modifications to the Software made by the User and distributed to third parties as a derivative work under this agreement. 19 | 20 | This agreement will terminate immediately upon User's breach of, or non-compliance with, any of its terms. User may be held liable for any copyright infringement or the infringement of any other proprietary rights in the Software that is caused or facilitated by the User's failure to abide by the terms of this agreement. 21 | 22 | This agreement will be construed and enforced in accordance with the law of the state of New York applicable to contracts performed entirely within the State. The parties irrevocably consent to the exclusive jurisdiction of the state or federal courts located in the City of New York for all disputes concerning this agreement. 23 | 24 | # Commercial Use 25 | 26 | Any User wishing to make a commercial use of the Software must contact ACM at permissions@acm.org to arrange an appropriate license. Commercial use includes (1) integrating or incorporating all or part of the source code into a product for sale or license by, or on behalf of, User to third parties, or (2) distribution of the binary or source code to third parties for use with a commercial product sold or licensed by, or on behalf of, User. 27 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ARfit: Multivariate Autoregressive Model Fitting 2 | 3 | This repository contains a collection of Matlab modules for 4 | 5 | - estimating parameters of multivariate autoregressive (AR) models, 6 | - diagnostic checking of fitted AR models, and 7 | - analyzing eigenmodes of fitted AR models. 8 | 9 | The algorithms implemented in ARfit are described in the following papers, which should be referenced if you use ARfit in publications: 10 | 11 | A. Neumaier and T. Schneider, 2001: [Estimation of parameters and eigenmodes of multivariate autoregressive models.](http://dx.doi.org/10.1145/382043.382304) ACM Trans. Math. Softw., 27, 27-57. 12 | 13 | T. Schneider and A. Neumaier, 2001: Algorithm 808: [ARfit – A Matlab package for the estimation of parameters and eigenmodes of multivariate autoregressive models.](http://dx.doi.org/10.1145/382043.382316) ACM Trans. Math. Softw., 27, 58-65. 14 | 15 | ARfit includes support for multiple realizations (trials) of time series and can estimate parameters of multivariate AR models taking all available realizations into account. 16 | 17 | 18 | # Installation 19 | 20 | The program package consists of several Matlab modules. To install the programs, download the package into a directory that is accessible by Matlab. 21 | 22 | Starting Matlab and invoking Matlab's online help function 23 | 24 | ``` 25 | help filename 26 | ``` 27 | 28 | calls up detailed information on the purpose and the calling syntax of the module filename.m. The script ardem.m demonstrates the basic features of the modules contained in ARfit. 29 | 30 | 31 | # Module Descriptions 32 | 33 | | Module | Description | 34 | |------------------------- | ----------------------------------------------------------------------------------- | 35 | | [CHANGES](CHANGES) | Recent significant changes of the programs | 36 | | [acf.m](acf.m) | Plots the sample autocorrelation function of a univariate time series (using XCORR from the Matlab Signal Processing Toolbox) | | [adjph.m](adjph.m) | Multiplies a complex vector by a phase factor such that the real part and the imaginary part of the vector are orthogonal and the norm of the real part is greater than or equal to the norm of the imaginary part. ADJPH is required by ARMODE to normalize the eigenmodes of an AR model | 37 | | [arconf.m](arconf.m) | Computes approximate confidence intervals for the AR model coefficients | 38 | | [ardem.m](ardem.m) | Demonstrates the use of modules contained in the ARfit package | 39 | | [arfit.m](arfit.m) | Stepwise selection of the order of an AR model and least squares estimation of AR model parameters | 40 | | [armode.m](armode.m) | Eigendecomposition of AR model. For a fitted AR model, ARMODE computes eigenmodes and their associated oscillation periods and damping times, as well as approximate confidence intervals for the eigenmodes, periods, and damping times | 41 | | [arord.m](arord.m) | Computes approximate order selection criteria for a sequence of AR models. ARORD is required by ARFIT | 42 | | [arqr.m](arqr.m) | QR factorization for least squares estimation of AR model parameters. ARQR is required by ARFIT | 43 | | [arres.m](arres.m) | Diagnostic checking of the residuals of a fitted model. Computes the time series of residuals. The modified multivariate portmanteau statistic of Li & McLeod (1981) is used to test the residuals for uncorrelatedness | 44 | | [arsim.m](arsim.m) | Simulation of AR processes | 45 | | [tquant.m](tquant.m) | Quantiles of Student’s t distribution. (TQUANT is required by ARCONF and ARMODE in the construction of confidence intervals.) | -------------------------------------------------------------------------------- /arsim.m: -------------------------------------------------------------------------------- 1 | function [v]=arsim(w,A,C,n_ntr,ndisc) 2 | %ARSIM Simulation of AR process. 3 | % 4 | % v=ARSIM(w,A,C,n) simulates n time steps of the AR(p) process 5 | % 6 | % v(k,:)' = w' + A1*v(k-1,:)' +...+ Ap*v(k-p,:)' + eta(k,:)', 7 | % 8 | % where A=[A1 ... Ap] is the coefficient matrix, and w is a vector of 9 | % intercept terms that is included to allow for a nonzero mean of the 10 | % process. The vectors eta(k,:) are independent Gaussian noise 11 | % vectors with mean zero and covariance matrix C. 12 | % 13 | % The p vectors of initial values for the simulation are taken to 14 | % be equal to the mean value of the process. (The process mean is 15 | % calculated from the parameters A and w.) To avoid spin-up effects, 16 | % the first 10^3 time steps are discarded. Alternatively, 17 | % ARSIM(w,A,C,n,ndisc) discards the first ndisc time steps. 18 | % 19 | % ARSIM(w,A,C,[n, ntr]) generates ntr realizations (trials) of 20 | % length n of the AR(p) process, which are output as the matrices 21 | % v(:,:,itr) with itr=1,...,ntr. 22 | 23 | % Modified 13-Oct-00 24 | % Author: Tapio Schneider 25 | % tapio@gps.caltech.edu 26 | 27 | m = size(C,1); % dimension of state vectors 28 | p = size(A,2)/m; % order of process 29 | n = n_ntr(1); % number of time steps 30 | if size(n_ntr) == 1 31 | ntr = 1; 32 | else 33 | ntr = n_ntr(2); 34 | end 35 | 36 | if (p ~= round(p)) 37 | error('Bad arguments.'); 38 | end 39 | 40 | if (length(w) ~= m | min(size(w)) ~= 1) 41 | error('Dimensions of arguments are mutually incompatible.') 42 | end 43 | w = w(:)'; % force w to be row vector 44 | 45 | % Check whether specified model is stable 46 | A1 = [A; eye((p-1)*m) zeros((p-1)*m,m)]; 47 | lambda = eig(A1); 48 | if any(abs(lambda) > 1) 49 | warning('The specified AR model is unstable.') 50 | end 51 | 52 | % Discard the first ndisc time steps; if ndisc is not given as input 53 | % argument, use default 54 | if (nargin < 5) 55 | ndisc = 10^3; 56 | end 57 | 58 | % Compute Cholesky factor of covariance matrix C 59 | [R, err]= chol(C); % R is upper triangular 60 | if err ~= 0 61 | error('Covariance matrix not positive definite.') 62 | end 63 | 64 | % Get ntr realizations of ndisc+n independent Gaussian 65 | % pseudo-random vectors with covariance matrix C=R'*R 66 | for itr=1:ntr 67 | randvec(:, :, itr) = randn([ndisc+n,m])*R; 68 | end 69 | 70 | % Add intercept vector to random vectors 71 | randvec = randvec + repmat(w, [ndisc+n, 1, ntr]); 72 | 73 | % Get transpose of system matrix A (use transpose in simulation because 74 | % we want to obtain the states as row vectors) 75 | AT = A'; 76 | 77 | % Take the p initial values of the simulation to equal the process mean, 78 | % which is calculated from the parameters A and w 79 | if any(w) 80 | % Process has nonzero mean mval = inv(B)*w' where 81 | % B = eye(m) - A1 -... - Ap; 82 | % Assemble B 83 | B = eye(m); 84 | for j=1:p 85 | B = B - A(:, (j-1)*m+1:j*m); 86 | end 87 | % Get mean value of process 88 | mval = w / B'; 89 | 90 | % The optimal forecast of the next state given the p previous 91 | % states is stored in the vector x. The vector x is initialized 92 | % with the process mean. 93 | x = repmat(mval, [p, 1]); 94 | else 95 | % Process has zero mean 96 | x = zeros(p,m); 97 | end 98 | 99 | % Initialize state vectors 100 | u = repmat([x; zeros(ndisc+n,m)], [1, 1, ntr]); 101 | 102 | % Simulate ntr realizations of n+ndisc time steps. In order to be 103 | % able to make use of Matlab's vectorization capabilities, the 104 | % cases p=1 and p>1 must be treated separately. 105 | if p==1 106 | for itr=1:ntr 107 | for k=2:ndisc+n+1; 108 | x(1,:) = u(k-1,:,itr)*AT; 109 | u(k,:,itr) = x + randvec(k-1,:,itr); 110 | end 111 | end 112 | else 113 | for itr=1:ntr 114 | for k=p+1:ndisc+n+p; 115 | for j=1:p; 116 | x(j,:) = u(k-j,:,itr)*AT((j-1)*m+1:j*m,:); 117 | end 118 | u(k,:,itr) = sum(x)+randvec(k-p,:,itr); 119 | end 120 | end 121 | end 122 | 123 | % return only the last n simulated state vectors 124 | v = u(ndisc+p+1:ndisc+n+p,:,:); 125 | 126 | 127 | 128 | 129 | 130 | -------------------------------------------------------------------------------- /arres.m: -------------------------------------------------------------------------------- 1 | function [siglev,res, lmp, dof_lmp]=arres(w,A,v,k) 2 | %ARRES Test of residuals of fitted AR model. 3 | % 4 | % [siglev,res]=ARRES(w,A,v) computes the time series of residuals 5 | % 6 | % res(k,:)' = v(k+p,:)'- w - A1*v(k+p-1,:)' - ... - Ap*v(k,:)' 7 | % 8 | % of an AR(p) model with A=[A1 ... Ap]. If v has three dimensions, 9 | % the 3rd dimension is treated as indicating multiple realizations 10 | % (trials) of the time series, that is, v(:,:,itr) is taken as the 11 | % itr-th trial. 12 | % 13 | % Also returned is the significance level siglev of the modified 14 | % Li-McLeod portmanteau (LMP) statistic, aggregated over multiple 15 | % realizations when they are present. 16 | % 17 | % Correlation matrices for the LMP statistic are computed up to lag 18 | % k=20, which can be changed to lag k by using 19 | % [siglev,res]=ARRES(w,A,v,k). 20 | 21 | % Modified 01-Dec-10 22 | % 24-Oct-10 Tim Mullen (added support for multiple realizations) 23 | % 24 | % Author: Tapio Schneider 25 | % tapio@gps.caltech.edu 26 | % 27 | % Reference: 28 | % Li, W. K., and A. I. McLeod, 1981: Distribution of the 29 | % Residual Autocorrelations in Multivariate ARMA Time Series 30 | % Models, J. Roy. Stat. Soc. B, 43, 231--239. 31 | % 32 | % The use of the LMP statistic with correlation matrices of the 33 | % residuals averaged over the realizations, as we do here, is a 34 | % heuristic. It may not work well for ntr large. An alternative 35 | % would be to calculate the LMP statistic for each realization 36 | % separately and test whether they jointly are consistent with no 37 | % autocorrelation of the residuals. 38 | 39 | n = size(v,1); % number of time steps (per realization) 40 | m = size(v,2); % dimension of state vectors 41 | ntr = size(v,3); % number of realizations (trials) 42 | p = size(A,2)/m; % order of model 43 | nres = n-p; % number of residuals (per realization) 44 | 45 | % Default value for k 46 | if (nargin < 4) 47 | k = min(20, nres-1); 48 | end 49 | if (k <= p) % check if k is in valid range 50 | error('Maximum lag of residual correlation matrices too small.'); 51 | end 52 | if (k >= nres) 53 | error('Maximum lag of residual correlation matrices too large.'); 54 | end 55 | 56 | w = w(:)'; % force w to be row vector 57 | 58 | % Get time series of residuals 59 | res = zeros(nres,m,ntr); 60 | l = 1:nres; % vectorized loop l=1,...,nres 61 | res(l,:,:) = v(l+p,:,:) - repmat(w, [nres, 1, ntr]); 62 | for itr=1:ntr 63 | for j=1:p 64 | res(l,:,itr) = res(l,:,itr) - v(l-j+p,:,itr)*A(:, (j-1)*m+1:j*m)'; 65 | end 66 | end 67 | % end of loop over l 68 | 69 | % For computation of correlation matrices, center residuals by 70 | % subtraction of the mean 71 | resc = res - repmat(mean(res), [nres, 1, 1]); 72 | 73 | % Compute correlation matrix of the residuals 74 | % compute lag zero correlation matrix 75 | c0 = zeros(m, m); 76 | for itr=1:ntr 77 | c0 = c0 + resc(:,:,itr)'*resc(:,:,itr); 78 | end 79 | d = diag(c0); 80 | dd = sqrt(d*d'); 81 | c0 = c0./dd; 82 | 83 | % compute lag l correlation matrix 84 | cl = zeros(m, m, k); 85 | for l=1:k 86 | for itr=1:ntr 87 | cl(:,:,l) = cl(:,:,l) ... 88 | + resc(1:nres-l, :, itr)'*resc(l+1:nres, :, itr); 89 | end 90 | cl(:,:,l) = cl(:,:,l)./dd; 91 | end 92 | 93 | % Get "covariance matrix" in LMP statistic 94 | c0_inv= inv(c0); % inverse of lag 0 correlation matrix 95 | rr = kron(c0_inv, c0_inv); % "covariance matrix" in LMP statistic 96 | 97 | % Compute modified Li-McLeod portmanteau statistic 98 | lmp = 0; % LMP statistic initialization 99 | x = zeros(m*m,1); % correlation matrix arranged as vector 100 | for l=1:k 101 | x = reshape(cl(:,:,l), m^2, 1); % arrange cl as vector by stacking columns 102 | lmp = lmp + x'*rr*x; % sum up LMP statistic 103 | end 104 | ntot = nres*ntr; % total number of residual vectors 105 | lmp = ntot*lmp + m^2*k*(k+1)/2/ntot;% add remaining term and scale 106 | dof_lmp = m^2*(k-p); % degrees of freedom for LMP statistic 107 | 108 | % Significance level with which hypothesis of uncorrelatedness is rejected 109 | siglev = 1 - gammainc(lmp/2, dof_lmp/2); -------------------------------------------------------------------------------- /arfit.m: -------------------------------------------------------------------------------- 1 | function [w, A, C, sbc, fpe, th]=arfit(v, pmin, pmax, selector, no_const) 2 | %ARFIT Stepwise least squares estimation of multivariate AR model. 3 | % 4 | % [w,A,C,SBC,FPE,th]=ARFIT(v,pmin,pmax) produces estimates of the 5 | % parameters of an m-variate AR model of order p, 6 | % 7 | % v(k,:)' = w' + A1*v(k-1,:)' +...+ Ap*v(k-p,:)' + noise(C), 8 | % 9 | % where w is the (m x 1) intercept vector, A1, ..., Ap are (m x m) 10 | % coefficient matrices, and C is a (m x m) noise covariance 11 | % matrix. The estimated order p lies between pmin and pmax and is 12 | % chosen as the optimizer of Schwarz's Bayesian Criterion. 13 | % 14 | % The input matrix v must contain the time series data, with 15 | % columns v(:,l) representing m variables l=1,...,m and rows 16 | % v(k,:) representing n observations at different (equally 17 | % spaced) times k=1,..,n. Optionally, v can have a third 18 | % dimension, in which case the matrices v(:,:, itr) represent 19 | % the realizations (e.g., measurement trials) itr=1,...,ntr of the 20 | % time series. ARFIT returns least squares estimates of the 21 | % intercept vector w, of the coefficient matrices A1,...,Ap (as 22 | % A=[A1 ... Ap]), and of the noise covariance matrix C. 23 | % 24 | % As order selection criteria, ARFIT computes approximations to 25 | % Schwarz's Bayesian Criterion and to the logarithm of Akaike's Final 26 | % Prediction Error. The order selection criteria for models of order 27 | % pmin:pmax are returned as the vectors SBC and FPE. 28 | % 29 | % The matrix th contains information needed for the computation of 30 | % confidence intervals. ARMODE and ARCONF require th as input 31 | % arguments. 32 | % 33 | % If the optional argument SELECTOR is included in the function call, 34 | % as in ARFIT(v,pmin,pmax,SELECTOR), SELECTOR is used as the order 35 | % selection criterion in determining the optimum model order. The 36 | % three letter string SELECTOR must have one of the two values 'sbc' 37 | % or 'fpe'. (By default, Schwarz's criterion SBC is used.) If the 38 | % bounds pmin and pmax coincide, the order of the estimated model 39 | % is p=pmin=pmax. 40 | % 41 | % If the function call contains the optional argument 'zero' as the 42 | % fourth or fifth argument, a model of the form 43 | % 44 | % v(k,:)' = A1*v(k-1,:)' +...+ Ap*v(k-p,:)' + noise(C) 45 | % 46 | % is fitted to the time series data. That is, the intercept vector w 47 | % is taken to be zero, which amounts to assuming that the AR(p) 48 | % process has zero mean. 49 | % 50 | % Modified 14-Oct-00 51 | % 24-Oct-10 Tim Mullen (added support for multiple realizatons) 52 | % 53 | % Authors: Tapio Schneider 54 | % tapio@gps.caltech.edu 55 | % 56 | % Arnold Neumaier 57 | % neum@cma.univie.ac.at 58 | 59 | % n: number of time steps (per realization) 60 | % m: number of variables (dimension of state vectors) 61 | % ntr: number of realizations (trials) 62 | [n,m,ntr] = size(v); 63 | 64 | if (pmin ~= round(pmin) | pmax ~= round(pmax)) 65 | error('Order must be integer.'); 66 | end 67 | if (pmax < pmin) 68 | error('PMAX must be greater than or equal to PMIN.') 69 | end 70 | 71 | % set defaults and check for optional arguments 72 | if (nargin == 3) % no optional arguments => set default values 73 | mcor = 1; % fit intercept vector 74 | selector = 'sbc'; % use SBC as order selection criterion 75 | elseif (nargin == 4) % one optional argument 76 | if strcmp(selector, 'zero') 77 | mcor = 0; % no intercept vector to be fitted 78 | selector = 'sbc'; % default order selection 79 | else 80 | mcor = 1; % fit intercept vector 81 | end 82 | elseif (nargin == 5) % two optional arguments 83 | if strcmp(no_const, 'zero') 84 | mcor = 0; % no intercept vector to be fitted 85 | else 86 | error(['Bad argument. Usage: ', ... 87 | '[w,A,C,SBC,FPE,th]=AR(v,pmin,pmax,SELECTOR,''zero'')']) 88 | end 89 | end 90 | 91 | ne = ntr*(n-pmax); % number of block equations of size m 92 | npmax = m*pmax+mcor; % maximum number of parameter vectors of length m 93 | 94 | if (ne <= npmax) 95 | error('Time series too short.') 96 | end 97 | 98 | % compute QR factorization for model of order pmax 99 | [R, scale] = arqr(v, pmax, mcor); 100 | 101 | % compute approximate order selection criteria for models 102 | % of order pmin:pmax 103 | [sbc, fpe] = arord(R, m, mcor, ne, pmin, pmax); 104 | 105 | % get index iopt of order that minimizes the order selection 106 | % criterion specified by the variable selector 107 | [val, iopt] = min(eval(selector)); 108 | 109 | % select order of model 110 | popt = pmin + iopt-1; % estimated optimum order 111 | np = m*popt + mcor; % number of parameter vectors of length m 112 | 113 | % decompose R for the optimal model order popt according to 114 | % 115 | % | R11 R12 | 116 | % R=| | 117 | % | 0 R22 | 118 | % 119 | R11 = R(1:np, 1:np); 120 | R12 = R(1:np, npmax+1:npmax+m); 121 | R22 = R(np+1:npmax+m, npmax+1:npmax+m); 122 | 123 | % get augmented parameter matrix Aaug=[w A] if mcor=1 and Aaug=A if mcor=0 124 | if (np > 0) 125 | if (mcor == 1) 126 | % improve condition of R11 by re-scaling first column 127 | con = max(scale(2:npmax+m)) / scale(1); 128 | R11(:,1) = R11(:,1)*con; 129 | end; 130 | Aaug = (R11\R12)'; 131 | 132 | % return coefficient matrix A and intercept vector w separately 133 | if (mcor == 1) 134 | % intercept vector w is first column of Aaug, rest of Aaug is 135 | % coefficient matrix A 136 | w = Aaug(:,1)*con; % undo condition-improving scaling 137 | A = Aaug(:,2:np); 138 | else 139 | % return an intercept vector of zeros 140 | w = zeros(m,1); 141 | A = Aaug; 142 | end 143 | else 144 | % no parameters have been estimated 145 | % => return only covariance matrix estimate and order selection 146 | % criteria for ``zeroth order model'' 147 | w = zeros(m,1); 148 | A = []; 149 | end 150 | 151 | % return covariance matrix 152 | dof = ne-np; % number of block degrees of freedom 153 | C = R22'*R22./dof; % bias-corrected estimate of covariance matrix 154 | 155 | % for later computation of confidence intervals return in th: 156 | % (i) the inverse of U=R11'*R11, which appears in the asymptotic 157 | % covariance matrix of the least squares estimator 158 | % (ii) the number of degrees of freedom of the residual covariance matrix 159 | invR11 = inv(R11); 160 | if (mcor == 1) 161 | % undo condition improving scaling 162 | invR11(1, :) = invR11(1, :) * con; 163 | end 164 | Uinv = invR11*invR11'; 165 | th = [dof zeros(1,size(Uinv,2)-1); Uinv]; 166 | 167 | 168 | 169 | -------------------------------------------------------------------------------- /armode.m: -------------------------------------------------------------------------------- 1 | function [S, Serr, per, tau, exctn, lambda] = armode(A, C, th) 2 | %ARMODE Eigendecomposition of AR model. 3 | % 4 | % [S,Serr,per,tau,exctn]=ARMODE(A,C,th) computes the 5 | % eigendecomposition of an AR(p) model that has been fitted using 6 | % ARFIT. The input arguments of ARMODE are output of ARFIT. 7 | % 8 | % The columns of the output matrix S contain the estimated eigenmodes 9 | % of the AR model. The output matrix Serr contains margins of error 10 | % for the components of the estimated eigenmodes S, such that 11 | % (S +/- Serr) are approximate 95% confidence intervals for the 12 | % individual components of the eigenmodes. 13 | % 14 | % The two-row matrices per and tau contain in their first rows the 15 | % estimated oscillation period per(1,k) and the estimated damping 16 | % time tau(1,k) of the eigenmode S(:,k). In their second rows, the 17 | % matrices per and tau contain margins of error for the periods and 18 | % damping times, such that 19 | % ( per(1,k) +/- per(2,k) ) and ( tau(1,k) +/- tau(2,k) ) 20 | % are approximate 95% confidence intervals for the period and damping 21 | % time of eigenmode S(:,k). 22 | % 23 | % For a purely relaxatory eigenmode, the period is infinite (Inf). 24 | % For an oscillatory eigenmode, the periods are finite. 25 | % 26 | % The excitation of an eigenmode measures its dynamical importance 27 | % and is returned as a fraction exctn that is normalized such that 28 | % the sum of the excitations of all eigenmodes equals one. 29 | % 30 | % See also ARFIT, ARCONF. 31 | 32 | % Modified 13-Oct-00 33 | % Author: Tapio Schneider 34 | % tapio@gps.caltech.edu 35 | 36 | ccoeff = .95; % confidence coefficient 37 | m = size(C,1); % dimension of state space 38 | p = size(A,2) / m; % order of model 39 | if p <= 0 40 | error('Order must be greater 0.'); 41 | end 42 | 43 | % Assemble coefficient matrix of equivalent AR(1) model 44 | A1 = [A; eye((p-1)*m) zeros((p-1)*m,m)]; 45 | 46 | % Eigenvalues and eigenvectors of coefficient matrix of equivalent 47 | % AR(1) model 48 | [BigS,d] = eig(A1); % columns of BigS are eigenvectors 49 | lambda = diag(d); % vector containing eigenvalues 50 | lambda = lambda(:); % force lambda to be column vector 51 | 52 | % Warning if the estimated model is unstable 53 | if any(abs(lambda) > 1) 54 | warning(sprintf(['The estimated AR model is unstable.\n',... 55 | '\t Some excitations may be negative.'])) 56 | end 57 | 58 | % Fix phase of eigenvectors such that the real part and the 59 | % imaginary part of each vector are orthogonal 60 | BigS = adjph(BigS); 61 | 62 | % Return only last m components of each eigenvector 63 | S = BigS((p-1)*m+1:p*m, :); 64 | 65 | % Compute inverse of BigS for later use 66 | BigS_inv = inv(BigS); 67 | 68 | % Recover the matrix Uinv that appears in the asymptotic covariance 69 | % matrix of the least squares estimator (Uinv is output of AR) 70 | if (size(th,2) == m*p+1) 71 | % The intercept vector has been fitted by AR; in computing 72 | % confidence intervals for the eigenmodes, this vector is 73 | % irrelevant. The first row and first column in Uinv, 74 | % corresponding to elements of the intercept vector, are not 75 | % needed. 76 | Uinv = th(3:size(th,1), 2:size(th,2)); 77 | 78 | elseif (size(th,2) == m*p) 79 | % No intercept vector has been fitted 80 | Uinv = th(2:size(th,1), :); 81 | else 82 | error('Input arguments of ARMODE must be output of ARFIT.') 83 | end 84 | % Number of degrees of freedom 85 | dof = th(1,1); 86 | % Quantile of t distribution for given confidence coefficient and dof 87 | t = tquant(dof, .5+ccoeff/2); 88 | 89 | % Asymptotic covariance matrix of estimator of coefficient matrix A 90 | Sigma_A = kron(Uinv, C); 91 | 92 | % Noise covariance matrix of system of relaxators and oscillators 93 | CovDcpld = BigS_inv(:, 1:m) * C * BigS_inv(:, 1:m)'; 94 | 95 | % For each eigenmode j: compute the period per, the damping time 96 | % tau, and the excitation exctn; also get the margins of error for 97 | % per and tau 98 | for j=1:m*p % eigenmode number 99 | a = real(lambda(j)); % real part of eigenvalue j 100 | b = imag(lambda(j)); % imaginary part of eigenvalue j 101 | abs_lambda_sq= abs(lambda(j))^2; % squared absolute value of eigenvalue j 102 | tau(1,j) = -2/log(abs_lambda_sq);% damping time of eigenmode j 103 | 104 | % Excitation of eigenmode j 105 | exctn(j) = real(CovDcpld(j,j) / (1-abs_lambda_sq)); 106 | 107 | % Assemble derivative of eigenvalue with respect to parameters in 108 | % the coefficient matrix A 109 | dot_lam = zeros(m^2*p, 1); 110 | for k=1:m 111 | dot_lam(k:m:k+(m*p-1)*m) = BigS_inv(j,k) .* BigS(1:m*p,j); 112 | end 113 | dot_a = real(dot_lam); % derivative of real part of lambda(j) 114 | dot_b = imag(dot_lam); % derivative of imag part of lambda(j) 115 | 116 | % Derivative of the damping time tau w.r.t. parameters in A 117 | phi = tau(1,j)^2 / abs_lambda_sq * (a*dot_a + b*dot_b); 118 | % Margin of error for damping time tau 119 | tau(2,j) = t * sqrt(phi'*Sigma_A*phi); 120 | 121 | % Period of eigenmode j and margin of error for period. (The 122 | % if-statements avoid warning messages that may otherwise result 123 | % from a division by zero) 124 | if (b == 0 & a >= 0) % purely real, nonnegative eigenvalue 125 | per(1,j) = Inf; 126 | per(2,j) = 0; 127 | elseif (b == 0 & a < 0) % purely real, negative eigenvalue 128 | per(1,j) = 2; 129 | per(2,j) = 0; 130 | else % complex eigenvalue 131 | per(1,j) = 2*pi/abs(atan2(b,a)); 132 | 133 | % Derivative of period with respect to parameters in A 134 | phi = per(1,j)^2 / (2*pi*abs_lambda_sq)*(b*dot_a-a*dot_b); 135 | % Margin of error for period 136 | per(2,j) = t * sqrt(phi'*Sigma_A*phi); 137 | end 138 | end 139 | 140 | % Give the excitation as `relative importance' that sums to one 141 | exctn = exctn/sum(exctn); 142 | 143 | % Compute confidence intervals for eigenmodes 144 | % ------------------------------------------- 145 | % Shorthands for matrix products 146 | XX = real(BigS)'*real(BigS); 147 | YY = imag(BigS)'*imag(BigS); 148 | XY = real(BigS)'*imag(BigS); 149 | 150 | % Need confidence intervals only for last m rows of BigS 151 | row1 = (p-1)*m+1; % first row for which confidence interval is needed 152 | 153 | mp = m*p; % dimension of equivalent AR(1) model 154 | for k=1:mp % loop over columns of S 155 | for l=row1:mp % loop over rows of S 156 | 157 | % evaluate gradient of S_{lk} 158 | for ii=1:m 159 | for jj=1:mp 160 | % compute derivative with respect to A(ii,jj) 161 | zsum = 0; 162 | zkkr = 0; % real part of Z_{kk} 163 | zkki = 0; % imaginary part of Z_{kk} 164 | for j=1:mp 165 | if (j ~= k) % sum up elements that appear in Z_{kk} 166 | zjk = BigS_inv(j,ii)*BigS(jj,k)/(lambda(k)-lambda(j)); 167 | zjkr = real(zjk); 168 | zjki = imag(zjk); 169 | zkkr = zkkr+zjki*(XY(k,j)-XY(j,k))-zjkr*(XX(k,j)+YY(k,j)); 170 | zkki = zkki+zjki*(YY(k,j)-XX(k,j))-zjkr*(XY(k,j)+XY(j,k)); 171 | zsum = zsum+BigS(l,j)*zjk; 172 | end 173 | end 174 | % now add Z_{kk} 175 | zkki = zkki / (XX(k,k)-YY(k,k)); 176 | grad_S((jj-1)*m+ii) = zsum+BigS(l,k)*(zkkr+i*zkki); 177 | end 178 | end 179 | Serr(l,k) = t * ( sqrt( real(grad_S)*Sigma_A*real(grad_S)') ... 180 | + i*sqrt( imag(grad_S)*Sigma_A*imag(grad_S)') ); 181 | end 182 | end 183 | 184 | % Only return last m*p rows of Serr 185 | Serr = Serr(row1:m*p, :); 186 | 187 | 188 | 189 | 190 | 191 | 192 | -------------------------------------------------------------------------------- /ardem.m: -------------------------------------------------------------------------------- 1 | %ARDEM Demonstrates modules of the ARfit package. 2 | 3 | % Revised: 30-Dec-99 Tapio Schneider 4 | % 01-Dec-10 (added example with multiple realizations) 5 | 6 | format short 7 | format compact 8 | 9 | echo on 10 | clc 11 | 12 | % ARfit is a collection of Matlab modules for the modeling of 13 | % multivariate time series with autoregressive (AR) models. ARfit 14 | % contains modules for estimating parameters of AR models from given 15 | % time series data; for checking the adequacy of an estimated 16 | % AR model; for analyzing eigenmodes of an estimated AR model; and 17 | % for simulating AR processes. 18 | % 19 | % This demo illustrates the use of ARfit with a bivariate AR(2) 20 | % process 21 | % 22 | % v(k,:)' = w' + A1*v(k-1,:)' + A2*v(k-2,:)' + eta(k,:)', 23 | % 24 | % where the row vectors eta(k,:) are independent and identically 25 | % distributed Gaussian noise vectors with zero mean and covariance 26 | % matrix C. The kth row v(k,:) of the 2-column matrix v represents an 27 | % observation of the process at instant k. The intercept vector w is 28 | % included to allow for a nonzero mean of the AR(p) process. 29 | % 30 | pause % Press any key to continue. 31 | 32 | clc 33 | 34 | % Let us simulate observations from a bivariate AR(2) process, 35 | % choosing the parameters 36 | 37 | w = [ 0.25 ; 0.1 ]; 38 | 39 | % for the intercept vector, 40 | 41 | A1 = [ 0.4 1.2; 0.3 0.7 ]; 42 | 43 | % and 44 | 45 | A2 = [ 0.35 -0.3; -0.4 -0.5 ]; 46 | 47 | % for the AR coefficient matrices, and 48 | 49 | C = [ 1.00 0.50; 0.50 1.50 ]; 50 | 51 | % for the noise covariance matrix. The two 2x2 matrices A1 and A2 are 52 | % assembled into a single 2x4 coefficient matrix: 53 | 54 | A = [ A1 A2 ]; 55 | 56 | % We use the module ARSIM to simulate observations (time steps) of 57 | % this AR process. ARSIM and other modules in the ARfit collection 58 | % allow multiple realizations (trials) of the time series to be 59 | % simulated and used in estimation procedures. Let us simulate 60 | % ntr realizations with n observations each: 61 | % 62 | n = 200; 63 | ntr = 5; 64 | v = arsim(w, A, C, [n, ntr]); 65 | 66 | % The matrix v now contains the simulated time series. Each 2D 67 | % submatrix v(:,:,itr) contains a realization of the time series, 68 | % with the row index labeling observations (time steps) and the 69 | % column index labeling variables. The third index itr=1,...,ntr 70 | % labels the realizations. 71 | % 72 | pause % Press any key to continue. 73 | 74 | clc 75 | 76 | % Suppose that we have no information about how the time series 77 | % data v are generated, but we want to try to fit an AR model to the 78 | % time series. That is, we must estimate the AR model parameters, 79 | % including the model order. Assuming that the correct model order 80 | % lies between 1 and 5, we use the module ARFIT to determine the 81 | % optimum model order using Schwarz's Bayesian Criterion (SBC): 82 | % 83 | pmin = 1; 84 | pmax = 5; 85 | [west, Aest, Cest, SBC, FPE, th] = arfit(v, pmin, pmax); 86 | 87 | % The output arguments west, Aest, and Cest of ARFIT are the 88 | % estimates of the intercept vector w, of the coefficient matrix A, 89 | % and of the noise covariance matrix C. (The matrix th will be needed 90 | % later in the computation of confidence intervals.) These parameters 91 | % are estimated for a model of order popt, where the optimum model 92 | % order popt is chosen as the minimizer of an approximation to 93 | % Schwarz's Bayesian Criterion. The selected order popt in our 94 | % example is: 95 | 96 | m = 2; % dimension of the state space 97 | popt = size(Aest, 2) / m; 98 | 99 | disp(['popt = ', num2str(popt)]) 100 | 101 | pause % Press any key to continue. 102 | 103 | clc 104 | 105 | % Besides the parameter estimates for the selected model, ARFIT has 106 | % also returned approximations to Schwarz's Bayesian Criterion SBC 107 | % and to Akaike's Final Prediction Error FPE, each for models of 108 | % order pmin:pmax. In this demo, the model order was chosen as the 109 | % minimizer of SBC. Here are the SBCs for the fitted models of order 110 | % 1,...,5: 111 | 112 | disp(SBC) 113 | 114 | % To see if using Akaike's Final Prediction Error as a criterion to 115 | % select the model order would have resulted in the same optimum 116 | % model order, compare the FPEs: 117 | 118 | disp(FPE) 119 | 120 | % Employing FPE as the order selection criterion, the optimum model 121 | % order would have been chosen as the minimizer of FPE. The values of 122 | % the order selection criteria are approximations in that in 123 | % evaluating an order selection criterion for a model of order p < 124 | % pmax, the first pmax-p observations of the time series are ignored. 125 | % 126 | pause % Press any key to continue. 127 | 128 | clc 129 | 130 | % Next it is necessary to check whether the fitted model is adequate 131 | % to represent the time series v. A necessary condition for model 132 | % adequacy is the uncorrelatedness of the residuals. The module ARRES 133 | 134 | [siglev,res] = arres(west,Aest,v); 135 | 136 | % returns the time series of residuals res(:,:,itr) for each 137 | % realization itr=1,...,ntr of the original time series and the 138 | % significance level siglev with which a modified Li-McLeod 139 | % portmanteau test rejects the null hypothesis that the residuals 140 | % (using all available realizations) are uncorrelated. A model 141 | % passes this test if, say, siglev > 0.05. In our example, the 142 | % significance level of the modified Li-McLeod portmanteau 143 | % statistic is 144 | 145 | disp(siglev); 146 | 147 | % (If siglev is persistently smaller than about 0.05, even over 148 | % several runs of this demo, and if the number of realizations ntr 149 | % is not very large, then there is most likely a problem with the 150 | % random number generator that ARSIM used in the simulation of v.) 151 | % 152 | pause % Press any key to continue. 153 | 154 | clc 155 | 156 | if exist('xcorr') % If the Signal Processing Toolbox is installed, plot 157 | % autocorrelation function of residuals ... 158 | 159 | % Using ACF, one can also plot the autocorrelation function of, say, 160 | % the first component of the first realization of the time series 161 | % of residuals: 162 | 163 | acf(res(:,1,1)); 164 | 165 | % 95% of the autocorrelations for lag > 0 should lie between the 166 | % dashdotted confidence limits for the autocorrelations of an IID 167 | % process of the same length as the time series of residuals res. 168 | 169 | % Since uncorrelatedness of the residuals is only a necessary 170 | % condition for model adequacy, further diagnostic tests should, in 171 | % practice, be performed. However, we shall go on to the estimation 172 | % of confidence intervals. 173 | % 174 | pause % Press any key to continue. 175 | end 176 | 177 | clc 178 | 179 | % Being reasonably confident that the model adequately represents the 180 | % data, we compute confidence intervals for the AR parameters with 181 | % the module ARCONF: 182 | 183 | [Aerr, werr] = arconf(Aest, Cest, west, th); 184 | 185 | % The output arguments Aerr and werr contain margins of error such 186 | % that (Aest +/- Aerr) and (west +/- werr) are approximate 95% 187 | % confidence intervals for the individual AR coefficients and for the 188 | % components of the intercept vector w. Here is the estimated 189 | % intercept vector with margins of error for the individual 190 | % components in the second column: 191 | 192 | disp([west werr]) 193 | 194 | % For comparison, the `true' vector as used in the simulation: 195 | 196 | disp(w) 197 | 198 | pause % Press any key to display the other parameter estimates. 199 | 200 | clc 201 | 202 | % The estimated coefficient matrix: 203 | 204 | disp(Aest) 205 | 206 | % with margins of error for its elements: 207 | 208 | disp(Aerr) 209 | 210 | % For comparison, the `true' AR coefficients: 211 | 212 | disp(A) 213 | 214 | pause % Press any key to continue. 215 | 216 | echo off 217 | % Compute `true' eigenmodes from model parameters: 218 | % Eigenvectors and eigenvalues of corresponding AR(1) coefficient 219 | % matrix: 220 | [Strue,EvTrue] = eig([A; eye(2) zeros(2)]); 221 | EvTrue = diag(EvTrue)'; % `true' eigenvalues 222 | Strue = adjph(Strue); % adjust phase of eigenmodes 223 | 224 | clc 225 | echo on 226 | 227 | % Finally, ARMODE computes the eigendecomposition of the fitted AR 228 | % model: 229 | 230 | [S, Serr, per, tau, exctn] = armode(Aest, Cest, th); 231 | 232 | % The columns of S are the estimated eigenmodes: 233 | 234 | disp(S) 235 | 236 | % with margins of error Serr: 237 | 238 | disp(Serr) 239 | 240 | % The intervals (S +/- Serr) are approximate 95% confidence intervals 241 | % for the individual components of the eigenmodes. Compare the 242 | % estimated eigenmodes above with the eigenmodes obtained from the 243 | % `true' model parameters: 244 | 245 | disp(Strue(3:4,:)) 246 | 247 | % (Note that the estimated modes can be a permutation of the `true' 248 | % modes. The sign of the modes is also ambiguous.) 249 | % 250 | pause % Press any key to continue. 251 | 252 | echo off 253 | pertrue = 2*pi./abs(angle(EvTrue)); % `true' periods 254 | 255 | clc 256 | 257 | echo on 258 | % Associated with the eigenmodes are the following oscillation periods: 259 | 260 | disp(per) 261 | 262 | % The second row contains margins of error for the periods such that 263 | % (per(1,k) +/- per(2,k)) is an approximate 95% confidence interval 264 | % for the period of eigenmode S(:,k). [Note that for a purely 265 | % relaxatory eigenmode, the period is infinite (Inf).] Compare the 266 | % above estimated periods with the `true' periods: 267 | 268 | disp(pertrue) 269 | 270 | pause % Press any key to get the damping time scales. 271 | 272 | echo off 273 | tautrue = -1./log(abs(EvTrue)); % `true' damping time scales 274 | 275 | clc 276 | 277 | echo on 278 | 279 | % The damping times associated with each eigenmode are: 280 | 281 | disp(tau) 282 | 283 | % with margins of error again in the second row. For comparison, the 284 | % `true' damping times: 285 | 286 | disp(tautrue) 287 | 288 | pause % Press any key to get the excitation of each eigenmode. 289 | echo off 290 | % Compute `true' excitation of eigenmodes from the designed parameters: 291 | p = 2; % true model order 292 | 293 | invStr = inv(Strue); % inverse of matrix with eigenvectors as columns 294 | 295 | % covariance matrix of corresponding decoupled AR(1) system 296 | CovDcpld = invStr*[C zeros(2,(p-1)*2); zeros((p-1)*2, p*2)]*invStr'; 297 | 298 | % diagonal of that covariance matrix 299 | DgCovDcpld = real(diag(CovDcpld))'; 300 | 301 | % excitation 302 | TrueExctn = DgCovDcpld(1:2*p)./(1-abs(EvTrue).^2); 303 | 304 | % normalize excitation 305 | TrueExctn = TrueExctn./sum(TrueExctn); 306 | 307 | clc 308 | 309 | echo on 310 | % ARMODE has also returned the excitations, measures of the relative 311 | % dynamical importance of the eigenmodes: 312 | 313 | disp(exctn) 314 | 315 | % Compare the estimated excitations with the `true' excitations 316 | % computed from the parameters used in the simulation: 317 | 318 | disp(TrueExctn) 319 | 320 | echo off 321 | disp('End') 322 | 323 | --------------------------------------------------------------------------------