Repository: statsmodels/statsmodels

Issue:
DOC: Clarify output size in statsmodels.tsa.stattools.acf
#### Autocorrelation output size is inconsistent using statsmodels.tsa.stattools.acf

The statsmodels.tsa.stattools.acf function returns nlags+1 values for the acf and confint return variables (because it includes the output at lag 0 (ie., acf=1)) but nlags values for the qstat and values return variables. I see this as needlessly confusing and easily fixed by making all outputs of size nlags or all of size nlags+1. If otherwise there is a reason for this, I'd love to be educated!

#### Code Sample, a copy-pastable example if possible

```python
import statsmodels.tsa.stattools as smtsa
import numpy as np
x = np.random.randint(0,10,size=20)
acf, confint, qstat, pvalues = smtsa.acf(x, nlags=7, qstat=True, alpha=0.05)

print('len(acf)', len(acf))
print('len(confint)', len(confint))
print('len(qstat)', len(qstat))
print('len(pvalues)', len(pvalues))
```

##### Output

len(acf) 8
len(confint) 8
len(qstat) 7
len(pvalues) 7

#### Expected Output

len(acf) 7
len(confint) 7
len(qstat) 7
len(pvalues) 7

or

len(acf) 8
len(confint) 8
len(qstat) 8
len(pvalues) 8


#### Output of ``import statsmodels.api as sm; sm.show_versions()``

<details>

[paste the output of ``import statsmodels.api as sm; sm.show_versions()`` here below this line]
INSTALLED VERSIONS
------------------
Python: 3.7.12.final.0
OS: Linux 5.4.104+ #1 SMP Sat Jun 5 09:50:34 PDT 2021 x86_64
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8

Statsmodels
===========

Installed: 0.10.2 (/usr/local/lib/python3.7/dist-packages/statsmodels)

Required Dependencies
=====================

cython: 0.29.24 (/usr/local/lib/python3.7/dist-packages/Cython)
numpy: 1.19.5 (/usr/local/lib/python3.7/dist-packages/numpy)
scipy: 1.4.1 (/usr/local/lib/python3.7/dist-packages/scipy)
pandas: 1.1.5 (/usr/local/lib/python3.7/dist-packages/pandas)
    dateutil: 2.8.2 (/usr/local/lib/python3.7/dist-packages/dateutil)
patsy: 0.5.2 (/usr/local/lib/python3.7/dist-packages/patsy)

Optional Dependencies
=====================

matplotlib: 3.2.2 (/usr/local/lib/python3.7/dist-packages/matplotlib)
    backend: module://ipykernel.pylab.backend_inline 
cvxopt: 1.2.7 (/usr/local/lib/python3.7/dist-packages/cvxopt)
joblib: 1.0.1 (/usr/local/lib/python3.7/dist-packages/joblib)

Developer Tools
================

IPython: 5.5.0 (/usr/local/lib/python3.7/dist-packages/IPython)
    jinja2: 2.11.3 (/usr/local/lib/python3.7/dist-packages/jinja2)
sphinx: 1.8.5 (/usr/local/lib/python3.7/dist-packages/sphinx)
    pygments: 2.6.1 (/usr/local/lib/python3.7/dist-packages/pygments)
pytest: 3.6.4 (/usr/local/lib/python3.7/dist-packages)
virtualenv: Not installed

</details>



Discussion:
I think it is because the ACF is well defined for lag 0 (it is the variance) while the q-stat and its p-value are not defined for 0 lags.  Docs could be improved. 
The ACF for lag 0 is 1 if I'm not mistaken, and is therefore trivial?
Yes, sorry. Was thinking of autocov rather than autocorr.  But still well defined.  Of course, has no estimation error too.  Probably not worth the pain to change these to match.  
I understand, thanks!

Resolving patch:
diff --git a/statsmodels/tsa/stattools.py b/statsmodels/tsa/stattools.py
--- a/statsmodels/tsa/stattools.py
+++ b/statsmodels/tsa/stattools.py
@@ -585,7 +585,8 @@ def acf(
        If True, then denominators for autocovariance are n-k, otherwise n.
     nlags : int, optional
         Number of lags to return autocorrelation for. If not provided,
-        uses min(10 * np.log10(nobs), nobs - 1).
+        uses min(10 * np.log10(nobs), nobs - 1). The returned value
+        includes lag 0 (ie., 1) so size of the acf vector is (nlags + 1,).
     qstat : bool, default False
         If True, returns the Ljung-Box q statistic for each autocorrelation
         coefficient.  See q_stat for more information.
@@ -628,14 +629,17 @@ def acf(
     Returns
     -------
     acf : ndarray
-        The autocorrelation function.
+        The autocorrelation function for lags 0, 1, ..., nlags. Shape
+        (nlags+1,).
     confint : ndarray, optional
-        Confidence intervals for the ACF. Returned if alpha is not None.
+        Confidence intervals for the ACF at lags 0, 1, ..., nlags. Shape
+        (nlags + 1, 2). Returned if alpha is not None.
     qstat : ndarray, optional
-        The Ljung-Box Q-Statistic.  Returned if q_stat is True.
+        The Ljung-Box Q-Statistic for lags 1, 2, ..., nlags (excludes lag
+        zero). Returned if q_stat is True.
     pvalues : ndarray, optional
-        The p-values associated with the Q-statistics.  Returned if q_stat is
-        True.
+        The p-values associated with the Q-statistics for lags 1, 2, ...,
+        nlags (excludes lag zero). Returned if q_stat is True.
 
     Notes
     -----
@@ -905,7 +909,8 @@ def pacf(x, nlags=None, method="ywadjusted", alpha=None):
         Observations of time series for which pacf is calculated.
     nlags : int, optional
         Number of lags to return autocorrelation for. If not provided,
-        uses min(10 * np.log10(nobs), nobs // 2 - 1).
+        uses min(10 * np.log10(nobs), nobs // 2 - 1). The returned value
+        includes lag 0 (ie., 1) so size of the pacf vector is (nlags + 1,).
     method : str, default "ywunbiased"
         Specifies which method for the calculations to use.
 
@@ -931,9 +936,11 @@ def pacf(x, nlags=None, method="ywadjusted", alpha=None):
     Returns
     -------
     pacf : ndarray
-        Partial autocorrelations, nlags elements, including lag zero.
+        The partial autocorrelations for lags 0, 1, ..., nlags. Shape
+        (nlags+1,).
     confint : ndarray, optional
-        Confidence intervals for the PACF. Returned if confint is not None.
+        Confidence intervals for the PACF at lags 0, 1, ..., nlags. Shape
+        (nlags + 1, 2). Returned if alpha is not None.
 
     See Also
     --------


Test patch: