DOC: Improve documentation

Fix some broken examples
Fix minor typos

Author: bashtage

arch/unitroot/unitroot.py

@@ -1057,7 +1057,7 @@ class KPSS(UnitRootTest):
     >>> print('{0:0.4f}'.format(kpss.stat))
     0.2870
     >>> print('{0:0.4f}'.format(kpss.pvalue))
-    0.1474
+    0.1473
     >>> kpss.trend = 'ct'
     >>> print('{0:0.4f}'.format(kpss.stat))
     0.2075

doc/source/bootstrap/confidence-intervals.rst

@@ -29,7 +29,7 @@ deviation and the Sharpe ratio.
 
 The setup makes use of return data downloaded from Yahoo!
 
-::
+.. code-block:: python
 
     import datetime as dt
 
@@ -47,7 +47,7 @@ The setup makes use of return data downloaded from Yahoo!
 
 The main function used will return a 3-element array containing the parameters.
 
-::
+.. code-block:: python
 
     def sharpe_ratio(x):
         mu, sigma = 12 * x.mean(), np.sqrt(12 * x.var())
@@ -77,7 +77,7 @@ This example makes use of the percentile bootstrap which is conceptually the
 simplest method - it constructs many bootstrap replications and returns
 order statistics from these empirical distributions.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 
@@ -128,7 +128,7 @@ the :math:`\alpha/2` and :math:`1-\alpha/2` empirical quantiles of the bootstrap
 distribution.  When :math:`\theta` is a vector, the empirical quantiles are
 computed element-by-element.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 
@@ -151,7 +151,7 @@ where :math:`\hat{\theta}^{\star}_{l}` and :math:`\hat{\theta}^{\star}_{u}` are
 the :math:`\alpha/2` and :math:`1-\alpha/2` empirical quantiles of the bootstrap
 distribution.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 
@@ -173,7 +173,7 @@ distribution.  The confidence interval is then
 where :math:`\hat{\sigma}` is the bootstrap estimate of the parameter standard
 error.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 
@@ -204,7 +204,7 @@ The version that uses a nested bootstrap is simple to implement although it can
 be slow since it requires :math:`B` inner bootstraps of each of the :math:`B`
 outer bootstraps.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 
@@ -216,7 +216,7 @@ standard error of the parameters.  In this example, this can be done using a
 method-of-moments argument and the delta-method. A detailed description of
 the mathematical formula is beyond the intent of this document.
 
-::
+.. code-block:: python
 
     def sharpe_ratio_se(params, x):
         mu, sigma, sr = params
@@ -236,7 +236,7 @@ the mathematical formula is beyond the intent of this document.
 The studentized bootstrap can then be implemented using the standard error
 function.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
     bs = IIDBootstrap(returns)
@@ -260,7 +260,7 @@ Bias-corrected (``bc``, ``bias-corrected`` or ``debiased``)
 The bias corrected bootstrap makes use of a bootstrap estimate of the bias to
 improve confidence intervals.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
     bs = IIDBootstrap(returns)
@@ -278,7 +278,7 @@ offer higher-order accuracy if some conditions are satisfied. Bias-corrected
 confidence intervals are a special case of BCa intervals where the acceleration
 parameter is set to 0.
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
 

doc/source/bootstrap/low-level-interface.rst

@@ -8,7 +8,7 @@ from a function and the bootstrapped data.
 
 This example makes use of monthly S&P 500 data.
 
-::
+.. code-block:: python
 
     import datetime as dt
 
@@ -27,15 +27,15 @@ This example makes use of monthly S&P 500 data.
 The function will compute the Sharpe ratio -- the (annualized) mean divided by
 the (annualized) standard deviation.
 
-::
+.. code-block:: python
 
     import numpy as np
     def sharpe_ratio(x):
         return np.array([12 * x.mean() / np.sqrt(12 * x.var())])
 
 The bootstrapped Sharpe ratios can be directly computed using `apply`.
 
-::
+.. code-block:: python
 
     import seaborn
     from arch.bootstrap import IIDBootstrap
@@ -59,7 +59,7 @@ arguments passed when constructing the instance.
 This example makes uses of simulated data to demonstrate how to use the
 bootstrap iterator.
 
-::
+.. code-block:: python
 
     import pandas as pd
     import numpy as np

doc/source/bootstrap/parameter-covariance-estimation.rst

@@ -7,7 +7,7 @@ traditional estimators.
 This example estimates the covariance of the mean, standard deviation and
 Sharpe ratio of the S&P 500 using Yahoo! Finance data.
 
-::
+.. code-block:: python
 
     import datetime as dt
     import pandas as pd
@@ -24,7 +24,7 @@ Sharpe ratio of the S&P 500 using Yahoo! Finance data.
 
 The function that returns the parameters.
 
-::
+.. code-block:: python
 
     def sharpe_ratio(r):
         mu = 12 * r.mean(0)
@@ -36,7 +36,7 @@ Like all applications of the bootstrap, it is important to choose a bootstrap
 that captures the dependence in the data.  This example uses the stationary
 bootstrap with an average block size of 12.
 
-::
+.. code-block:: python
 
     import pandas as pd
     from arch.bootstrap import StationaryBootstrap
@@ -50,7 +50,7 @@ bootstrap with an average block size of 12.
 
 The output is
 
-::
+.. code-block:: python
 
     >>> params
     mu        8.148534

doc/source/bootstrap/semiparametric-parametric-bootstrap.rst

@@ -16,7 +16,7 @@ For simplicity, consider a semiparametric bootstrap of an OLS regression.
 The bootstrap step will combine the original parameter estimates and original
 regressors with bootstrapped residuals to construct a bootstrapped
 regressand.  The bootstrap regressand and regressors can then be used to
-produce a bootstraped parameter estimate.
+produce a bootstrapped parameter estimate.
 
 The user-provided function must:
 
@@ -25,43 +25,48 @@ The user-provided function must:
   to construct bootstrapped residuals, simulate the regressand, and then
   estimate the bootstrapped parameters
 
-::
+.. code-block:: python
 
     import numpy as np
     def ols(y, x, params=None, x_orig=None):
         if params is None:
-            return np.linalg.pinv(x).dot(y)
+            return np.linalg.pinv(x).dot(y).ravel()
 
         # When params is not None
         # Bootstrap residuals
         resids = y - x.dot(params)
         # Simulated data
         y_star = x_orig.dot(params) + resids
         # Parameter estimates
-        return np.linalg.pinv(x_orig).dot(y_star)
+        return np.linalg.pinv(x_orig).dot(y_star).ravel()
+
+
+.. note::
+
+  The function should return a 1-dimensional array. ``ravel`` is used above to
+  ensure that the parameters estimated are 1d.
 
 This function can then be used to perform a semiparametric bootstrap
 
-::
+.. code-block:: python
 
     from arch.bootstrap import IIDBootstrap
-    x = np.random.randn(100,3)
-    e = np.random.randn(100,1)
-    b = np.arange(1,4)
+    x = np.random.randn(100, 3)
+    e = np.random.randn(100, 1)
+    b = np.arange(1, 4)[:, None]
     y = x.dot(b) + e
     bs = IIDBootstrap(y, x)
     ci = bs.conf_int(ols, 1000, method='percentile',
                      sampling='semi', extra_kwargs={'x_orig': x})
 
-
 Using ``partial`` instead of ``extra_kwargs``
 =============================================
 
 ``functools.partial`` can be used instead to provide a wrapper function which
 can then be used in the bootstrap.  This example fixed the value of ``x_orig``
 so that it is not necessary to use ``extra_kwargs``.
 
-::
+.. code-block:: python
 
     from functools import partial
     ols_partial = partial(ols, x_orig=x)
@@ -77,22 +82,22 @@ the bootstrap.
 
 First, the function used must be account for this structure.
 
-::
+.. code-block:: python
 
     def ols_semi_v2(y, x, resids=None, params=None, x_orig=None):
         if params is None:
-            return np.linalg.pinv(x).dot(y)
+            return np.linalg.pinv(x).dot(y).ravel()
 
         # Simulated data if params provided
         y_star = x_orig.dot(params) + resids
         # Parameter estimates
-        return np.linalg.pinv(x_orig).dot(y_star)
+        return np.linalg.pinv(x_orig).dot(y_star).ravel()
 
 This version can then be used to *directly* implement a semiparametric
 bootstrap, although ultimately it is not meaningfully simpler than the
 previous method.
 
-::
+.. code-block:: python
 
     resids = y - x.dot(ols_semi_v2(y,x))
     bs = IIDBootstrap(y, x, resids=resids)
@@ -139,26 +144,26 @@ This example continues the OLS example from the semiparametric example,
 only assuming that residuals are normally distributed.  The variance
 estimator is the MLE.
 
-::
+.. code-block:: python
 
-    def ols_para(y, x, params=None, rng=None, x_orig=None):
+    def ols_para(y, x, params=None, state=None, x_orig=None):
         if params is None:
             beta = np.linalg.pinv(x).dot(y)
             e = y - x.dot(beta)
-            sigma2 = e.dot(e) / e.shape[0]
-            return np.hstack([beta,sigma2])
+            sigma2 = e.T.dot(e) / e.shape[0]
+            return np.r_[beta.ravel(), sigma2.ravel()]
 
         beta = params[:-1]
         sigma2 = params[-1]
-        e = rng.standard_normal(x_orig.shape[0])
-        ystar = x_orig.dot(params) + np.sqrt(sigma2) * e
+        e = state.standard_normal(x_orig.shape[0])
+        ystar = x_orig.dot(beta) + np.sqrt(sigma2) * e
 
         # Use the plain function to compute parameters
         return ols_para(ystar, x_orig)
 
 This function can then be used to form parametric bootstrap confidence intervals.
 
-::
+.. code-block:: python
 
     bs = IIDBootstrap(y,x)
     ci = bs.conf_int(ols_para, 1000, method='percentile',

doc/source/unitroot/introduction.rst

@@ -7,15 +7,17 @@ contains a single variable.
 
 All tests share a common structure.  The key elements are:
 
-* `stat` - Returns the test statistic
-* `pvalue` - Returns the p-value of the test statistic
-* `lags` - Sets or gets the number of lags used in the model.  In most test, can be `None` to trigger automatic selection.
-* `trend` - Sets of gets the trend used in the model.  Supported trends vary by model, but include:
+- `stat` - Returns the test statistic
+- `pvalue` - Returns the p-value of the test statistic
+- `lags` - Sets or gets the number of lags used in the model.  In most test, can be ``None`` to trigger automatic selection.
+- `trend` - Sets or gets the trend used in the model.  Supported trends vary by model, but include:
+
    - `'nc'`: No constant
    - `'c'`: Constant
    - `'ct'`: Constant and time trend
    - `'ctt'`: Constant, time trend and quadratic time trend
-* `summary()` - Returns a summary object that can be printed to get a formatted table
+
+- `summary()` - Returns a summary object that can be printed to get a formatted table
 
 
 Basic Example
@@ -26,7 +28,7 @@ defined as the difference between the yields of large portfolios of BAA and AAA
 uses a constant and time trend.
 
 
-::
+.. code-block:: python
 
     import datetime as dt
 

doc/source/univariate/forecasting.rst

@@ -41,7 +41,7 @@ the choices available for forecasting.  The model can be described as
 
 In code this model can be constructed using data from the S&P 500 using
 
-::
+.. code-block:: python
 
     from arch import arch_model
     import datetime as dt
@@ -55,7 +55,7 @@ In code this model can be constructed using data from the S&P 500 using
 The model will be estimated using the first 10 years to estimate parameters
 and then forecasts will be produced for the final 5.
 
-::
+.. code-block:: python
 
     split_date = dt.datetime(2010,1,1)
     res = am.fit(last_obs=split_date)
@@ -79,7 +79,7 @@ Variance forecasts are constructed for the conditional variances as
                      & = & \omega + \left(\alpha  + \beta\right) E_{t}[\sigma^2_{t+h-1}] \, h \geq 2
    \end{eqnarray}
 
-::
+.. code-block:: python
 
    forecasts = res.forecast(horizon=5, start=split_date)
    forecasts.variance[split_date:].plot()
@@ -121,7 +121,7 @@ The final variance forecasts are then computed using the :math:`B` simulations
         E_t[\epsilon^2_{t+h}] = \sigma^2_{t+h} = B^{-1}\sum_{b=1}^B \sigma^2_{t+h,b}.
    \end{equation}
 
-::
+.. code-block:: python
 
    forecasts = res.forecast(horizon=5, start=split_date, method='simulation')
 
@@ -188,7 +188,7 @@ The three core attributes are
 
 Each attribute contains a ``DataFrame`` with a common structure.
 
-::
+.. code-block:: python
 
    print(forecasts.variance.tail())
 
@@ -213,7 +213,7 @@ made using data **up to and including** December 31, 2013.
 By default forecasts are only produced for observations after the final
 observation used to estimate the model.
 
-::
+.. code-block:: python
 
    day = dt.timedelta(1)
    print(forecasts.variance[split_date - 5 * day:split_date + 5 * day])