libs/math/doc/html/math_toolkit/ljung_box.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>The Ljung-Box Test</title>
   5 <link rel="stylesheet" href="../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
   8 <link rel="up" href="../statistics.html" title="Chapter&#160;6.&#160;Statistics">
   9 <link rel="prev" href="runs_test.html" title="Runs tests">
  10 <link rel="next" href="../vector_functionals.html" title="Chapter&#160;7.&#160;Vector Functionals - Norms">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="runs_test.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../statistics.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../vector_functionals.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="math_toolkit.ljung_box"></a><a class="link" href="ljung_box.html" title="The Ljung-Box Test">The Ljung-Box Test</a>
  28 </h2></div></div></div>
  29 <h4>
  30 <a name="math_toolkit.ljung_box.h0"></a>
  31       <span class="phrase"><a name="math_toolkit.ljung_box.synopsis"></a></span><a class="link" href="ljung_box.html#math_toolkit.ljung_box.synopsis">Synopsis</a>
  32     </h4>
  33 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">statistics</span><span class="special">/</span><span class="identifier">ljung_box</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  34
  35 <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">statistics</span> <span class="special">{</span>
  36
  37 <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
  38 <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">&gt;</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">RandomAccessIterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">RandomAccessIterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">int64_t</span> <span class="identifier">lags</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">,</span> <span class="identifier">int64_t</span> <span class="identifier">fit_dof</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
  39
  40
  41 <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RandomAccessContainer</span><span class="special">&gt;</span>
  42 <span class="keyword">auto</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">RandomAccessContainer</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">int64_t</span> <span class="identifier">lags</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">,</span> <span class="identifier">int64_t</span> <span class="identifier">fit_dof</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
  43
  44 <span class="special">}</span>
  45 </pre>
  46 <h4>
  47 <a name="math_toolkit.ljung_box.h1"></a>
  48       <span class="phrase"><a name="math_toolkit.ljung_box.background"></a></span><a class="link" href="ljung_box.html#math_toolkit.ljung_box.background">Background</a>
  49     </h4>
  50 <p>
  51       The Ljung-Box test is used to test if residuals from a fitted model have unwanted
  52       autocorrelation. If autocorrelation exists in the residuals, then presumably
  53       a model with more parameters can be fitted to the original data and explain
  54       more of the structure it contains.
  55     </p>
  56 <p>
  57       The test statistic is
  58     </p>
  59 <p>
  60       <span class="inlinemediaobject"><object type="image/svg+xml" data="../../graphs/ljung_box_definition.svg" width="479" height="55"></object></span>
  61     </p>
  62 <p>
  63       where <span class="emphasis"><em>n</em></span> is the length of <span class="emphasis"><em>v</em></span> and &#8467;
  64       is the number of lags.
  65     </p>
  66 <p>
  67       The variance of the statistic slightly exceeds the variance of the chi squared
  68       distribution, but nonetheless it still is a fairly good test with reasonable
  69       computational cost.
  70     </p>
  71 <p>
  72       An example use is given below:
  73     </p>
  74 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
  75 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">random</span><span class="special">&gt;</span>
  76 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
  77 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">statistics</span><span class="special">/</span><span class="identifier">ljung_box</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  78 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">statistics</span><span class="special">::</span><span class="identifier">ljung_box</span><span class="special">;</span>
  79 <span class="identifier">std</span><span class="special">::</span><span class="identifier">random_device</span> <span class="identifier">rd</span><span class="special">;</span>
  80 <span class="identifier">std</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">dis</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span>
  81 <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">(</span><span class="number">8192</span><span class="special">);</span>
  82 <span class="keyword">for</span> <span class="special">(</span><span class="keyword">auto</span> <span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">:</span> <span class="identifier">v</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">dis</span><span class="special">(</span><span class="identifier">rd</span><span class="special">);</span> <span class="special">}</span>
  83 <span class="keyword">auto</span> <span class="special">[</span><span class="identifier">Q</span><span class="special">,</span> <span class="identifier">p</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
  84 <span class="comment">// Possible output: Q = 5.94734, p = 0.819668</span>
  85 </pre>
  86 <p>
  87       Now if the result is clearly autocorrelated:
  88     </p>
  89 <pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span>
  90 <span class="keyword">auto</span> <span class="special">[</span><span class="identifier">Q</span><span class="special">,</span> <span class="identifier">p</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
  91 <span class="comment">// Possible output: Q = 81665.1, p = 0</span>
  92 </pre>
  93 <p>
  94       By default, the number of lags is taken to be the logarithm of the number of
  95       samples, so that the default complexity is [bigO](<span class="emphasis"><em>n</em></span> ln
  96       <span class="emphasis"><em>n</em></span>). If you want to calculate a given number of lags, use
  97       the second argument:
  98     </p>
  99 <pre class="programlisting"><span class="identifier">int64_t</span> <span class="identifier">lags</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
 100 <span class="keyword">auto</span> <span class="special">[</span><span class="identifier">Q</span><span class="special">,</span> <span class="identifier">p</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span><span class="number">10</span><span class="special">);</span>
 101 </pre>
 102 <p>
 103       Finally, it is sometimes relevant to specify how many degrees of freedom were
 104       used in creating the model from which the residuals were computed. This does
 105       not affect the test statistic <span class="emphasis"><em>Q</em></span>, but only the <span class="emphasis"><em>p</em></span>-value.
 106       If you need to specify the number of degrees of freedom, use
 107     </p>
 108 <pre class="programlisting"><span class="identifier">int64_t</span> <span class="identifier">fit_dof</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
 109 <span class="keyword">auto</span> <span class="special">[</span><span class="identifier">Q</span><span class="special">,</span> <span class="identifier">p</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">ljung_box</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="special">-</span><span class="number">1</span><span class="special">,</span> <span class="identifier">fit_dof</span><span class="special">);</span>
 110 </pre>
 111 <p>
 112       For example, if you fit your data with an ARIMA(<span class="emphasis"><em>p</em></span>, <span class="emphasis"><em>q</em></span>)
 113       model, then <code class="computeroutput"><span class="identifier">fit_dof</span> <span class="special">=</span>
 114       <span class="identifier">p</span> <span class="special">+</span> <span class="identifier">q</span></code>.
 115     </p>
 116 </div>
 117 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 118 <td align="left"></td>
 119 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 120       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 121       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 122       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 123       Daryle Walker and Xiaogang Zhang<p>
 124         Distributed under the Boost Software License, Version 1.0. (See accompanying
 125         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 126       </p>
 127 </div></td>
 128 </tr></table>
 129 <hr>
 130 <div class="spirit-nav">
 131 <a accesskey="p" href="runs_test.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../statistics.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../vector_functionals.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 132 </div>
 133 </body>
 134 </html>