octave_packages/m/signal/arch_test.m

   1 ## Copyright (C) 1995-2012 Kurt Hornik
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn {Function File} {[@var{pval}, @var{lm}] =} arch_test (@var{y}, @var{x}, @var{p})
  21 ## For a linear regression model
  22 ##
  23 ## @example
  24 ## y = x * b + e
  25 ## @end example
  26 ##
  27 ## @noindent
  28 ## perform a Lagrange Multiplier (LM) test of the null hypothesis of no
  29 ## conditional heteroscedascity against the alternative of CH(@var{p}).
  30 ##
  31 ## I.e., the model is
  32 ##
  33 ## @example
  34 ## y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
  35 ## @end example
  36 ##
  37 ## @noindent
  38 ## given @var{y} up to @math{t-1} and @var{x} up to @math{t},
  39 ## @math{e}(t) is @math{N(0, h(t))} with
  40 ##
  41 ## @example
  42 ## h(t) = v + a(1) * e(t-1)^2 + @dots{} + a(p) * e(t-p)^2,
  43 ## @end example
  44 ##
  45 ## @noindent
  46 ## and the null is @math{a(1)} == @dots{} == @math{a(p)} == 0.
  47 ##
  48 ## If the second argument is a scalar integer, @math{k}, perform the same
  49 ## test in a linear autoregression model of order @math{k}, i.e., with
  50 ##
  51 ## @example
  52 ## [1, y(t-1), @dots{}, y(t-@var{k})]
  53 ## @end example
  54 ##
  55 ## @noindent
  56 ## as the @math{t}-th row of @var{x}.
  57 ##
  58 ## Under the null, LM approximately has a chisquare distribution with
  59 ## @var{p} degrees of freedom and @var{pval} is the @math{p}-value (1
  60 ## minus the CDF of this distribution at LM) of the test.
  61 ##
  62 ## If no output argument is given, the @math{p}-value is displayed.
  63 ## @end deftypefn
  64
  65 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
  66 ## Description: Test for conditional heteroscedascity
  67
  68 function [pval, lm] = arch_test (y, x, p)
  69
  70   if (nargin != 3)
  71     error ("arch_test: 3 input arguments required");
  72   endif
  73
  74   if (! (isvector (y)))
  75     error ("arch_test: Y must be a vector");
  76   endif
  77   T   = length (y);
  78   y   = reshape (y, T, 1);
  79   [rx, cx] = size (x);
  80   if ((rx == 1) && (cx == 1))
  81     x = autoreg_matrix (y, x);
  82   elseif (! (rx == T))
  83     error ("arch_test: either rows(X) == length(Y), or X is a scalar");
  84   endif
  85   if (! (isscalar(p) && (rem(p, 1) == 0) && (p > 0)))
  86     error ("arch_test: P must be a positive integer");
  87   endif
  88
  89   [b, v_b, e] = ols (y, x);
  90   Z    = autoreg_matrix (e.^2, p);
  91   f    = e.^2 / v_b - ones (T, 1);
  92   f    = Z' * f;
  93   lm   = f' * inv (Z'*Z) * f / 2;
  94   pval = 1 - chi2cdf (lm, p);
  95
  96 endfunction