UArch¶

UArch is short for Univariate ARCH models and MUArch stands for multiple (or many) Univariate ARCH models. In essence MUArch, is a list of many UArch models. This helps when you need to simulate many univariate ARCH models together. Also, it is helpful when you need to specify the marginals as in a Copula-GARCH model.

class muarch.uarch.UArch(mean='Constant', lags=0, vol='GARCH', p=1, o=0, q=1, power=2.0, dist='Normal', hold_back=None, scale=1)[source]¶

Univariate ARCH model that wraps on top of Mean, Volatility and Distribution classes defined in the arch package. Mainly, this class combines the original model and fitted model in the arch package for convenience. It has also some additional methods such as simulate_mc for Monte Carlo simulations.

__init__(mean='Constant', lags=0, vol='GARCH', p=1, o=0, q=1, power=2.0, dist='Normal', hold_back=None, scale=1)[source]¶

Creates the wrapping arch model

Parameters

mean ({ 'zero', 'constant', 'harx', 'har', 'ar', 'arx', 'ls' }, optional) –
Name of the mean model. Currently supported options are:
- Constant (default) - Constant mean model
- Zero - Zero mean model
- AR - Autoregression model
- ARX - Autoregression model with exogenous regressors. Falls back to AR if no exogenous regressors
- HAR - Heterogeneous Autoregression model
- HARX - Heterogeneous Autoregressions with exogenous regressors
- LS - Least squares model
For more information on the different models, check out the documentation at https://arch.readthedocs.io/en/latest/univariate/mean.html
lags (int or list (int), optional) – Either a scalar integer value indicating lag length or a list of integers specifying lag locations.
vol ({ 'GARCH', 'ARCH', 'CONSTANT' 'EGARCH', 'FIGARCH' and 'HARCH', 'CONSTANT' }, optional) –
Name of the volatility model. Currently supported options are:
- GARCH (default) - Standard GARCH process which can be used to specify the following models:
  ARCH(p)
  
  GARCH(p,q)
  
  GJR-GARCH(p,o,q)
  
  AVARCH(p)
  
  AVGARCH(p,q)
  
  TARCH(p,o,q)
  
  Models with arbitrary, pre-specified powers
- ARCH - ARCH process
- EGARCH - EGARCH process
- FIGARCH - Fractionally Integrated (FI) GARCH process
- HARCH - Heterogeneous ARCH process
- Constant (default) - Constant volatility process
p (int, optional) – Lag order of the symmetric innovation
o (int, optional) – Lag order of the asymmetric innovation
q (int, optional) – Lag order of lagged volatility or equivalent
power (float, optional) – Power to use with the innovations. Default is 2.0, which produces ARCH and related models. Using 1.0 produces AVARCH and related models. Other powers can be specified, although these should be strictly positive, and usually larger than 0.25.
dist ({ 'normal', 'gaussian', 'studentst', 't', 'skewstudent', 'skewt', 'ged', 'generalized error' }, optional) –
Name of the distribution for the innovations. Currently supported options are:
- normal, gaussian (default) - Standard Normal distribution
- t, studentst - Standardized Student’s distribution
- skewstudent, skewt - Standardized Skewed Student’s distribution.
- ged, **generalized error” - Generalized Error Distribution
hold_back (int, optional) – Number of observations at the start of the sample to exclude when estimating model parameters. Used when comparing models with different lag lengths to estimate on the common sample.
scale (float) – Factor to scale data up or down by. This is useful when your data is too small leading to numerical errors when fitting. It will be used to scale simulation data

fit(y, x=None, update_freq=1, disp='off', starting_values=None, cov_type='robust', show_warning=True, first_obs=None, last_obs=None, tol=None, options=None, backcast=None)[source]¶

Fits the model given a nobs by 1 vector of sigma2 values

Parameters

y ({ndarray, Series}) – The dependent variable
x ({ndarray, DataFrame}, optional) – Exogenous regressors. Ignored if model does not permit exogenous regressors.
update_freq (int, optional) – Frequency of iteration updates. Output is generated every update_freq iterations. Set to 0 to disable iterative output
disp ('final' or 'off' (default)) – Either ‘final’ to print optimization result or ‘off’ to display nothing
starting_values (ndarray, optional) – Array of starting values to use. If not provided, starting values are constructed by the model components
cov_type (str, optional) – Estimation method of parameter covariance. Supported options are ‘robust’, which does not assume the Information Matrix Equality holds and ‘classic’ which does. In the ARCH literature, ‘robust’ corresponds to Bollerslev-Wooldridge covariance estimator.
show_warning (bool, optional) – Flag indicating whether convergence warnings should be shown.
first_obs ({int, str, datetime, Timestamp}) – First observation to use when estimating model
last_obs ({int, str, datetime, Timestamp}) – Last observation to use when estimating model
tol (float, optional) – Tolerance for termination
options (dict, optional) – Options to pass to scipy.optimize.minimize. Valid entries include ‘ftol’, ‘eps’, ‘disp’, and ‘maxiter’
backcast (float, optional) – Value to use as backcast. Should be measure \(\sigma^2_0\) since model-specific non-linear transformations are applied to value before computing the variance recursions.

Returns

Fitted UArch instance

Return type

UArch

forecast(params=None, horizon=1, start=None, align='origin', method='analytic', simulations=1000, rng=None)[source]¶

Construct forecasts from estimated model

Parameters

params (ndarray, optional) – Alternative parameters to use. If not provided, the parameters estimated when fitting the model are used. Must be identical in shape to the parameters computed by fitting the model.
horizon (int, optional) – Number of steps to forecast
start ({int, datetime, Timestamp, str}, optional) – An integer, datetime or str indicating the first observation to produce the forecast for. Datetimes can only be used with pandas inputs that have a datetime index. Strings must be convertible to a date time, such as in ‘1945-01-01’.
align ({'origin', 'target'}, optional) –
When set to ‘origin’, the t-th row of forecasts contains the forecasts for t+1, t+2, …, t+h.

When set to ‘target’, the t-th row contains the 1-step ahead forecast from time t-1, the 2 step from time t-2, …, and the h-step from time t-h. ‘target’ simplifies computing forecast errors since the realization and h-step forecast are aligned.
method ({'analytic', 'simulation', 'bootstrap'}, optional) – Method to use when producing the forecast. The default is ‘analytic’. The method only affects the variance forecast generation. Not all volatility models support all methods. In particular, volatility models that do not evolve in squares such as EGARCH or TARCH do not support the ‘analytic’ method for horizons > 1.
simulations (int, optional) – Number of simulations to run when computing the forecast using either simulation or bootstrap.
rng ({callable, ndarray}, optional) –
If using a custom random number generator to for simulation-based forecasts, function must produce random samples using the syntax rng(size) where size is a 2-element tuple (simulations, horizon).

Else, if a numpy array is passed in, array must have shape (simulation x horizon).

Returns

forecasts – t by h data frame containing the forecasts. The alignment of the forecasts is controlled by align.

Return type

ARCHModelForecast

Notes

The most basic 1-step ahead forecast will return a vector with the same length as the original data, where the t-th value will be the time-t forecast for time t + 1. When the horizon is > 1, and when using the default value for align, the forecast value in position [t, h] is the time-t, h+1 step ahead forecast.

If model contains exogenous variables (model.x is not None), then only 1-step ahead forecasts are available. Using horizon > 1 will produce a warning and all columns, except the first, will be nan-filled.

If align is ‘origin’, forecast[t,h] contains the forecast made using y[:t] (that is, up to but not including t) for horizon h + 1. For example, y[100,2] contains the 3-step ahead forecast using the first 100 data points, which will correspond to the realization y[100 + 2]. If align is ‘target’, then the same forecast is in location [102, 2], so that it is aligned with the observation to use when evaluating, but still in the same column.

hedgehog_plot(params=None, horizon=10, step=10, start=None, type_='volatility', method='analytic', simulations=1000)[source]¶

Plot forecasts from estimated model

Parameters

params ({Series, ndarray}, optional) – Alternative parameters to use. If not provided, the parameters computed by fitting the model are used. Must be 1-d and identical in shape to the parameters computed by fitting the model
horizon (int, optional) – Number of steps to forecast
step (int, optional) – Non-negative number of forecasts to skip between spines
start (int, datetime or str, optional) – An integer, datetime or str indicating the first observation to produce the forecast for. Datetimes can only be used with pandas inputs that have a datetime index. Strings must be convertible to a date time, such as in ‘1945-01-01’. If not provided, the start is set to the earliest forecastable date
type_ ({'volatility', 'mean'}) – Quantity to plot, the forecast volatility or the forecast mean
method ({'analytic', 'simulation', 'bootstrap'}) – Method to use when producing the forecast. The default is analytic. The method only affects the variance forecast generation. Not all volatility models support all methods. In particular, volatility models that do not evolve in squares such as EGARCH or TARCH do not support the ‘analytic’ method for horizons > 1
simulations (int) – Number of simulations to run when computing the forecast using either simulation or bootstrap

Returns

Handle to the figure

Return type

figure

property params¶: Model Parameters

residual_plot(annualize=None, scale=None)[source]¶

Plot standardized residuals and conditional volatility

Parameters

annualize (str, optional) – String containing frequency of data that indicates plot should contain annualized volatility. Supported values are ‘D’ (daily), ‘W’ (weekly) and ‘M’ (monthly), which scale variance by 252, 52, and 12 respectively
scale (float, optional) – Value to use when scaling returns to annualize. If scale is provides, annualize is ignored and the value in scale is used.

Returns

Handle to the figure

Return type

figure

residuals(standardize=True) → numpy.ndarray[source]¶

Model residuals

Parameters: standardize (bool, optional) – Whether to standardize residuals. Residuals are standardized by dividing it with the conditional volatility
Returns: Residuals
Return type: ndarray

simulate(nobs: int, burn=500, initial_value: Union[numpy.ndarray, float] = None, x: Union[numpy.ndarray, pandas.core.frame.DataFrame, None] = None, initial_value_vol: Union[numpy.ndarray, float] = None, data_only=False, params: Optional[numpy.ndarray] = None, custom_dist: Union[Callable[[Union[int, Iterable[int]]], numpy.ndarray], numpy.ndarray, None] = None) → Union[pandas.core.frame.DataFrame, numpy.ndarray][source]¶

Simulates data from a ARMA-GARCH model

Parameters

nobs (int) – Length of series to simulate
burn (int, optional) – Number of values to simulate to initialize the model and remove dependence on initial values
initial_value ({ndarray, float}, optional) – Either a scalar value or max(lags) array set of initial values to use when initializing the model. If omitted, 0.0 is used
x ({ndarray, DataFrame}, optional) – nobs + burn by k array of exogenous variables to include in the simulation. This should be a 2D matrix
initial_value_vol ({ndarray, float}, optional) – An array or scalar to use when initializing the volatility process.
data_only (bool, default True) – If True, this returns only the simulated data, omits the volatility and error. In this case, it will return as a numpy array. Otherwise, it returns a data frame with the data, volatility and error
params (ndarray, optional) – If not None, model will use the parameters supplied to generate simulations. Otherwise, it will use the fitted parameters.
custom_dist ({ndarray, Callable}, optional) –
Optional density from which to simulate the innovations (Distribution) in the GARCH models. This is useful when working with the copula-GARCH model where each univariate model innovations has dependence on others. It is assumed that the values supplied are standardized [0, 1] innovations instead of the unstandardized residuals.

The shape of the array must be at least as long as the simulation size required after accounting for burn and type of innovation process. If unsure, use simulation_size_required to check.

If a random number generator function is passed in, ensure that it only takes only argument and returns a numpy array. The argument can be an integer or a tuple of integers. In this case, the size will be automatically derived to save the user the trouble.

Returns

DataFrame with columns data containing the simulated values, volatility, containing the conditional volatility and errors containing the errors used in the simulation. If data_only, it returns the ‘data’ column as a numpy array

Return type

DataFrame or ndarray

simulate_mc(nobs: int, reps: int, burn=500, initial_value: Union[numpy.ndarray, float] = None, x: Union[numpy.ndarray, pandas.core.frame.DataFrame, None] = None, initial_value_vol: Union[numpy.ndarray, float] = None, params: Optional[numpy.ndarray] = None, custom_dist: Union[Callable[[Union[int, Iterable[int]]], numpy.ndarray], numpy.ndarray, None] = None) → Union[pandas.core.frame.DataFrame, numpy.ndarray][source]¶

Simulates data from a ARMA-GARCH model with multiple repetitions.

This is used for Monte Carlo simulations.

Parameters

nobs (int) – Length of series to simulate
reps (int) – Number of repetitions in Monte Carlo simulation
burn (int, optional) – Number of values to simulate to initialize the model and remove dependence on initial values
initial_value ({ndarray, float}, optional) – Either a scalar value or max(lags) array set of initial values to use when initializing the model. If omitted, 0.0 is used
x ({ndarray, DataFrame}, optional) – nobs + burn by k array of exogenous variables to include in the simulation. This should be a 2D matrix
initial_value_vol ({ndarray, float}, optional) – An array or scalar to use when initializing the volatility process.
params ({Series, ndarray}, optional) – If not None, model will use the parameters supplied to generate simulations. Otherwise, it will use the fitted parameters.
custom_dist ({ndarray, Callable}, optional) –
Optional density from which to simulate the innovations (Distribution) in the GARCH models. This is useful when working with the copula-GARCH model where each univariate model innovations has dependence on others. It is assumed that the values supplied are standardized [0, 1] innovations instead of the unstandardized residuals.

The shape of the array must be at least as long as the simulation size required after accounting for burn and type of innovation process. If unsure, use simulation_size_required to check.

If a random number generator function is passed in, he size will be automatically derived to save the user the trouble. However, the function must:
- take as it first argument an integer or a tuple of integer
- have other parameters that are optional
- return a numpy array

Returns

simulated_data – Array containing the simulated values

Return type

ndarray