# vim: set encoding=utf-8

#  Copyright (c) 2016 Intel Corporation 
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#


def timeseries_durbin_watson_test(self, residuals):
    """
    Computes the Durbin-Watson test statistic used to determine the presence of serial correlation in the residuals.
    Serial correlation can show a relationship between values separated from each other by a given time lag. A value
    close to 0.0 gives evidence for positive serial correlation, a value close to 4.0 gives evidence for negative
    serial correlation, and a value close to 2.0 gives evidence for no serial correlation.

    :param residuals: (str) Name of the column that contains residual values
    :return: Durbin-Watson statistics test

    Example
    -------


    In this example, we have a frame that contains time series values.  The inspect command below shows a snippet of
    what the data looks like:

        >>> frame.inspect()
        [#]  timeseries_values
        ======================
        [0]              3.201
        [1]             3.3178
        [2]             3.6279
        [3]             3.5902
        [4]               3.43
        [5]             4.0546
        [6]             3.7606
        [7]             3.1231
        [8]             3.2077
        [9]             4.3383

    Calculate Durbin-Watson test statistic by giving it the name of the column that has the time series values:

        >>> frame.timeseries_durbin_watson_test("timeseries_values")
        0.02678674777710402

    """

    if not isinstance(residuals, str):
        raise TypeError("residuals should be a str (column name).")

    return self._scala.timeSeriesDurbinWatsonTest(residuals)