Add decorrelation_time

[bradyrx]

Migrate decorrelation time from climpred, since it's not a required function at climpred and doesn't need to be written internally.

@is_xarray(0)
def decorrelation_time(da, r=20, dim='time'):
    """Calculate the decorrelaton time of a time series.

    .. math::
        \\tau_{d} = 1 + 2 * \\sum_{k=1}^{r}(\\alpha_{k})^{k}

    Args:
        da (xarray object): Time series.
        r (optional int): Number of iterations to run the above formula.
        dim (optional str): Time dimension for xarray object.

    Returns:
        Decorrelation time of time series.

    Reference:
        * Storch, H. v, and Francis W. Zwiers. Statistical Analysis in Climate
          Research. Cambridge ; New York: Cambridge University Press, 1999.,
          p.373

    """
    one = xr.ones_like(da.isel({dim: 0}))
    one = one.where(da.isel({dim: 0}).notnull())
    return one + 2 * xr.concat(
        [corr(da, da, dim=dim, lead=i) ** i for i in range(1, r)], 'it'
    ).sum('it')

[bradyrx]

Actually it looks like it's needed for assessing DPP

[aaronspring]

Used in the notebooks. Yes these stats functions for the notebooks are not strictly climpred material but useful to see where predictable variations might stem from.