function [q, qsig] = qstat (series, m)
%QSTAT Box-Pierce (1970) Q test using Ljung & Box's (1978) finite-sample correction
%
% [Q, QSIG] = QSTAT (SERIES, M) returns (row vector) Q, the Ljung & Box corrected Q
%    statistics of serial correlation in (vector) SERIES for each lag order specified by
%    (vector) M, and (row vector) QSIG, the levels of significance at which the associated
%    null hypotheses of no correlation are rejected.
%
%    SERIES should be a vector, or else it is transformed into a vector column by column.
%
%    M can be a scalar (default is 1) or a vector of integers in any order. For example,
%    if M = 5, results are only returned for the null hypothesis of no 5th order serial
%    correlation, but if M = [3 1 5], Q and QSIG will be three-point vectors carrying the
%    results for the test at lag orders 3, 1 and 5 (in this order).
%
%    QSIG assumes NaN values if the MATLAB Statistics Toolbox is not installed.
%
%    The cost of computation depends on the LARGEST lag order alone as specified in M.
%    See the source code comments for an explanation of how the test is conducted and the
%    bottom of the script for a list of references.
%
% The author assumes no responsibility for errors or damage resulting from usage. All
% rights reserved. Usage of the programme in applications and alterations of the code
% should be referenced. This script may be redistributed if nothing has been added or
% removed and nothing is charged. Positive or negative feedback would be appreciated.

%                     Copyright (c) 6 April 1998  by Ludwig Kanzler
%                     Department of Economics, University of Oxford
%                     Postal: Christ Church,  Oxford OX1 1DP,  U.K.
%                     E-mail: ludwig.kanzler@economics.oxford.ac.uk
%                     Homepage:      http://users.ox.ac.uk/~econlrk
%                     $ Revision: 1.21 $$ Date: 15 September 1998 $

% Some preparations:
if nargin < 2, m = 1; end
m         = m(:)';
maxm      = max(m);
P(1:maxm) = 0;
series    = series(:);
n         = length(series);

% First, compute the parts of the Q statistic which differ for each j:
for j = 1 : maxm
   P(j) = (series(1:end-j)'*series(j+1:end))^2 / (n-j)^3;
end

% Then compute the cumulative sum and multiply by the part of the Q statistic which does
% not depend on j, thus obtaining vector Q which comprises the Q statistic for each j up
% to the highest (last) value of M:
Q = cumsum(P) * n^3*(n+2)/(series'*series)^2;

% But the Q statistic does not need to be returned for every j, only for all M:
q = Q(m);

% Lastly, evaluate the null hypothesis of no serial correlation at lag order m by
% computing the level of significance at which H0 is to be rejected:
if exist('chi2cdf.m','file') & nargout == 2
   qsig = 1 - chi2cdf(q, m);
elseif nargout == 2
   qsig = NaN*m;
end

% End of function.

% This script builds on the theoretical foundations described, for example, in Campbell
% et al., 1997, p. 47, Harvey, 1990, pp. 212-213, and Intriligator et al., 1996, p. 204.
%
% However, in order to save CPU time by computing Q and QSIG for many m in one integrated
% algorithm, this implementation of the Q test is structured quite differently from any of
% the explicit equations contained in the above references. Specifically, all constant
% multiplicative terms have been pulled out of the summation (loop) and are applied only
% at the end; moreover, the summation is done only once.
%
% One criticism levelled against the Q test is that it is not clear which lag order to
% choose for the computation. This implementation addresses the problem by allowing
% computation of the test for ANY lag order without compromising speed, thus enabling the
% researcher to investigate the results for all possible m.

% REFERENCES:
%
% Box, G.E.P & David Pierce (1970), "Distribution of Residual Autocorrelations in
%    Autoregressive-Integrated Moving Average Times Series Models”, Journal of the
%    American Statistical Association, vol. 65, no. 332 (December), pp. 1509-1526
%
% Campbell, John, Andrew Lo & Craig MacKinlay (1997), "The Econometrics of Financial
%    Markets", Princeton University Press, Princeton, New Jersey
%
% Harvey, Andrew (1990), "The Econometric Analysis of Time Series", 2nd edition, MIT
%    Press, Cambridge, Massachusetts
%
% Intriligator, Michael, Ronald Bodkin & Cheng Hsiao (1996), "Econometric Models,
%    Techniques, and Applications", 2nd edition, Prentice Hall, Upper Saddle River, New
%    Jersey
%
% Ljung, G.M. & G.E.P. Box (1978), "On a Measure of Lack of Fit in Time Series Models”,
%    Biometrika, vol. 65, no. 2, pp. 297-303

% End of file.