From 8a3c5ff0a67198120f0483768ba3c58614f6379b Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Fri, 21 Dec 2018 14:48:18 +0000 Subject: [PATCH] DOC: Improve documentation Fix some broken examples Fix minor typos --- arch/unitroot/unitroot.py | 2 +- doc/source/bootstrap/confidence-intervals.rst | 22 ++++----- doc/source/bootstrap/low-level-interface.rst | 8 ++-- .../parameter-covariance-estimation.rst | 8 ++-- .../semiparametric-parametric-bootstrap.rst | 47 ++++++++++--------- doc/source/unitroot/introduction.rst | 14 +++--- doc/source/univariate/forecasting.rst | 12 ++--- doc/source/univariate/introduction.rst | 8 ++-- 8 files changed, 64 insertions(+), 57 deletions(-) diff --git a/arch/unitroot/unitroot.py b/arch/unitroot/unitroot.py index 56d2baa604..e89587188e 100644 --- a/arch/unitroot/unitroot.py +++ b/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 diff --git a/doc/source/bootstrap/confidence-intervals.rst b/doc/source/bootstrap/confidence-intervals.rst index f55f513deb..a373707750 100644 --- a/doc/source/bootstrap/confidence-intervals.rst +++ b/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 diff --git a/doc/source/bootstrap/low-level-interface.rst b/doc/source/bootstrap/low-level-interface.rst index 712114e896..98e68f7bdb 100644 --- a/doc/source/bootstrap/low-level-interface.rst +++ b/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,7 +27,7 @@ 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): @@ -35,7 +35,7 @@ the (annualized) standard deviation. 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 diff --git a/doc/source/bootstrap/parameter-covariance-estimation.rst b/doc/source/bootstrap/parameter-covariance-estimation.rst index 65af8002c8..78f2cfdcfa 100644 --- a/doc/source/bootstrap/parameter-covariance-estimation.rst +++ b/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 diff --git a/doc/source/bootstrap/semiparametric-parametric-bootstrap.rst b/doc/source/bootstrap/semiparametric-parametric-bootstrap.rst index 1a83bb28f6..59b3a92bef 100644 --- a/doc/source/bootstrap/semiparametric-parametric-bootstrap.rst +++ b/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,12 +25,12 @@ 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 @@ -38,22 +38,27 @@ The user-provided function must: # 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`` ============================================= @@ -61,7 +66,7 @@ Using ``partial`` instead of ``extra_kwargs`` 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', diff --git a/doc/source/unitroot/introduction.rst b/doc/source/unitroot/introduction.rst index 2f93d93b16..5cdca67194 100644 --- a/doc/source/unitroot/introduction.rst +++ b/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 diff --git a/doc/source/univariate/forecasting.rst b/doc/source/univariate/forecasting.rst index 406106c55d..6d64fd53e6 100644 --- a/doc/source/univariate/forecasting.rst +++ b/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]) diff --git a/doc/source/univariate/introduction.rst b/doc/source/univariate/introduction.rst index 8dc69cb840..543dcac018 100644 --- a/doc/source/univariate/introduction.rst +++ b/doc/source/univariate/introduction.rst @@ -23,7 +23,7 @@ A complete ARCH model is divided into three components: However, the simplest method to construct this model is to use the constructor function :py:meth:`~arch.arch_model` -:: +.. code-block:: python import datetime as dt @@ -40,7 +40,7 @@ function :py:meth:`~arch.arch_model` Alternatively, the same model can be manually assembled from the building blocks of an ARCH model -:: +.. code-block:: python from arch import ConstantMean, GARCH, Normal @@ -50,7 +50,7 @@ blocks of an ARCH model In either case, model parameters are estimated using -:: +.. code-block:: python res = am.fit() @@ -77,7 +77,7 @@ with the following output Function evaluations: 85 Gradient evaluations: 12 -:: +.. code-block:: python print(res.summary())