1[/ 2Copyright (c) 2019 Nick Thompson 3Use, modification and distribution are subject to the 4Boost Software License, Version 1.0. (See accompanying file 5LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6] 7 8[section:ljung_box The Ljung-Box Test] 9 10[heading Synopsis] 11 12``` 13#include <boost/math/statistics/ljung_box.hpp> 14 15namespace boost::math::statistics { 16 17template<class RandomAccessIterator> 18std::pair<Real, Real> ljung_box(RandomAccessIterator begin, RandomAccessIterator end, int64_t lags = -1, int64_t fit_dof = 0); 19 20 21template<class RandomAccessContainer> 22auto ljung_box(RandomAccessContainer const & v, int64_t lags = -1, int64_t fit_dof = 0); 23 24} 25``` 26 27[heading Background] 28 29The Ljung-Box test is used to test if residuals from a fitted model have unwanted autocorrelation. 30If autocorrelation exists in the residuals, then presumably a model with more parameters can be fitted to the original data and explain more of the structure it contains. 31 32The test statistic is 33 34[$../graphs/ljung_box_definition.svg] 35 36where /n/ is the length of /v/ and \u2113 is the number of lags. 37 38The variance of the statistic slightly exceeds the variance of the chi squared distribution, but nonetheless it still is a fairly good test with reasonable computational cost. 39 40An example use is given below: 41 42 43``` 44#include <vector> 45#include <random> 46#include <iostream> 47#include <boost/math/statistics/ljung_box.hpp> 48using boost::math::statistics::ljung_box; 49std::random_device rd; 50std::normal_distribution<double> dis(0, 1); 51std::vector<double> v(8192); 52for (auto & x : v) { x = dis(rd); } 53auto [Q, p] = ljung_box(v); 54// Possible output: Q = 5.94734, p = 0.819668 55``` 56 57Now if the result is clearly autocorrelated: 58 59``` 60for (size_t i = 0; i < v.size(); ++i) { v[i] = i; } 61auto [Q, p] = ljung_box(v); 62// Possible output: Q = 81665.1, p = 0 63``` 64 65By default, the number of lags is taken to be the logarithm of the number of samples, so that the default complexity is [bigO](/n/ ln /n/). 66If you want to calculate a given number of lags, use the second argument: 67 68``` 69int64_t lags = 10; 70auto [Q, p] = ljung_box(v,10); 71``` 72 73Finally, it is sometimes relevant to specify how many degrees of freedom were used in creating the model from which the residuals were computed. 74This does not affect the test statistic /Q/, but only the /p/-value. 75If you need to specify the number of degrees of freedom, use 76 77``` 78int64_t fit_dof = 2; 79auto [Q, p] = ljung_box(v, -1, fit_dof); 80``` 81 82For example, if you fit your data with an ARIMA(/p/, /q/) model, then `fit_dof = p + q`. 83 84 85 86[endsect] 87[/section:ljung_box] 88
