R: Functions to simulate, extract components and fit BARC models

BARC.functions {BTSR}

R Documentation

Functions to simulate, extract components and fit BARC models

Description

These functions can be used to simulate, extract components and fit any model of the class barc. A model with class barc is a special case of a model with class btsr . See ‘The BTSR structure’ in BARC.functions for more details on the general structure. See ‘Details’.

Usage

BARC.sim(n = 1, burn = 0, xreg = NULL, map = 4, coefs = list(alpha =
  0, beta = NULL, phi = NULL, theta = 0.5, nu = 20, u0 = pi/4),
  y.start = NULL, xreg.start = NULL, xregar = TRUE, error.scale = 0,
  complete = FALSE, linkg = c("linear", "linear"), linkh = "linear",
  ctt.h = 1, seed = NULL, rngtype = 2, debug = FALSE)

BARC.extract(yt, xreg = NULL, nnew = 0, xnew = NULL, p, r,
  coefs = list(), lags = list(), fixed.values = list(),
  fixed.lags = list(), y.start = NULL, xreg.start = NULL,
  xregar = TRUE, error.scale = 0, map = 4, linkg = c("linear",
  "linear"), linkh = "linear", ctt.h = 1, llk = TRUE, sco = FALSE,
  info = FALSE, debug = FALSE)

BARC.fit(yt, xreg = NULL, nnew = 0, xnew = NULL, p = 0, r = 1,
  start = list(), lags = list(), fixed.values = list(),
  ignore.start = FALSE, fixed.lags = list(), lower = list(nu = 0, u0 =
  0), upper = list(nu = Inf, u0 = 1), map = 4, linkg = c("linear",
  "linear"), linkh = "linear", ctt.h = 1, sco = FALSE, info = FALSE,
  xregar = TRUE, y.start = NULL, xreg.start = NULL, error.scale = 0,
  control = list(), report = TRUE, debug = FALSE, ...)

Arguments

`n`	a strictly positive integer. The sample size of yt (after burn-in). Default is 1.
`burn`	a non-negative integer. length of "burn-in" period. Default is 0.
`xreg`	optionally, a vector or matrix of external regressors. For simulation purposes, the length of xreg must be `n+burn`. Default is `NULL`. For extraction or fitting purposes, the length of `xreg` must be the same as the length of the observed time series `y_t`.
`map`	a non-negative integer from 1 to 5 corresponding to the map function. Default is 4. See ‘The map function’.
`coefs`	a list with the coefficients of the model. An empty list will result in an error. The arguments that can be passed through this list are: `alpha` optionally, a numeric value corresponding to the intercept. If the argument is missing, it will be treated as zero. See ‘The BTSR structure’ in `btsr.functions`. `beta` optionally, a vector of coefficients corresponding to the regressors in `xreg`. If `xreg` is provided but `beta` is missing in the `coefs` list, an error message is issued. `phi` optionally, for the simulation function this must be a vector of size `p`, corresponding to the autoregressive coefficients (including the ones that are zero), where `p` is the AR order. For the extraction and fitting functions, this is a vector with the non-fixed values in the vector of autoregressive coefficients. `theta` the parameter (or vector of parameters) corresponding to the map function. If `map = 5` this value is ignored. For simulation, purposes, the default is `map = 4` and `theta = 0.5`. `nu` the dispersion parameter. If missing, an error message is issued. `u0` a numeric value in the interval `(0,1)`, corresponding to the value of the random variable `U_0`. For simulation purposes, the default is `u0 = pi/4`.
`y.start`	optionally, a initial value for yt (to be used in the recursions). Default is `NULL`, in which case, the recursion assumes that `g_2(y_t) = 0`, for `t < 1`.
`xreg.start`	optionally, a vector of initial value for xreg (to be used in the recursions). Default is `NULL`, in which case, the recursion assumes that `X_t = 0`, for `t < 1`. If `xregar = FALSE` this argument is ignored.
`xregar`	logical; indicates if xreg is to be included in the AR part of the model. See ‘The BTSR structure’. Default is `TRUE`.
`error.scale`	the scale for the error term. See ‘The BTSR structure’ in `btsr.functions`. Default is 0.
`complete`	logical; if `FALSE` the function returns only the simulated time series yt, otherwise, additional time series are provided. Default is `FALSE`
`linkg`	character or a two character vector indicating which links must be used in the model. See ‘The BTSR structure’ in `btsr.functions` for details and `link.btsr` for valid links. If only one value is provided, the same link is used for `mu_t` and for `y_t` in the AR part of the model. Default is `c("linear", "linear")`
`linkh`	a character indicating which link must be associated to the the chaotic process. See ‘The BTSR structure’ in `btsr.functions` for details and `link.btsr` for valid links. Default is `"linear"`.
`ctt.h`	numeric; the constant to be associated to the link `h`, when `linkh = "linear"`. Default is 1.
`seed`	optionally, an integer which gives the value of the fixed seed to be used by the random number generator. If missing, a random integer is chosen uniformly from 1,000 to 10,000.
`rngtype`	optionally, an integer indicating which random number generator is to be used. Default is 2. See ‘Common Arguments’ in `btsr.functions`.
`debug`	logical, if `TRUE` the output from FORTRAN is return (for debuggin purposes). Default is `FALSE` for all models.
`yt`	a numeric vector with the observed time series. If missing, an error message is issued.
`nnew`	optionally, the number of out-of sample predicted values required. Default is 0.
`xnew`	a vector or matrix, with `nnew` observations of the regressors observed/predicted values corresponding to the period of out-of-sample forecast. If `xreg = NULL`, `xnew` is ignored.
`p`	a non-negative integer. The order of AR polynomial. If missing, the value of `p` is calculated from length(coefs$phi) and length(fixed.values$phi). For fitting, the default is 0.
`r`	a non-negative integer. The size of the vector theta. If missing, the value of `t` is calculated from length(coefs$theta) and length(fixed.values$theta). For fitting, the default is 1.
`lags`	optionally, a list with the lags that the values in `coefs` correspond to. The names of the entries in this list must match the ones in `coefs`. For one dimensional coefficients, the `lag` is obviously always 1 and can be suppressed. An empty list indicates that either the argument `fixed.lags` is provided or all lags must be used.
`fixed.values`	optionally, a list with the values of the coefficients that are fixed. By default, if a given vector (such as the vector of AR coefficients) has fixed values and the corresponding entry in this list is empty, the fixed values are set as zero. The names of the entries in this list must match the ones in `coefs`.
`fixed.lags`	optionally, a list with the lags that the fixed values in `fixed.values` correspond to. The names of the entries in this list must match the ones in `fixed.values`. ##' For one dimensional coefficients, the `lag` is obviously always 1 and can be suppressed. If an empty list is provided and the model has fixed lags, the argument `lags` is used as reference.
`llk`	logical, if `TRUE` the value of the log-likelihood function is returned. Default is `TRUE`.
`sco`	logical, if `TRUE` the score vector is returned. Default is `FALSE`.
`info`	logical, if `TRUE` the information matrix is returned. Default is `FALSE`. For the fitting function, `info` is automatically set to `TRUE` when `report = TRUE`.
`start`	a list with the starting values for the non-fixed coefficients of the model. If an empty list is provided, the function `coefs.start` is used to obtain starting values for the parameters.
`ignore.start`	logical, if starting values are not provided, the function uses the default values and `ignore.start` is ignored. In case starting values are provided and `ignore.start = TRUE`, those starting values are ignored and recalculated. The default is `FALSE`.
`lower`	optionally, list with the lower bounds for the parameters. The names of the entries in these lists must match the ones in `start`. The default is to assume that the parameters have no lower bound except for `nu`, for which de default is 0. Only the bounds for bounded parameters need to be specified.
`upper`	optionally, list with the upper bounds for the parameters. The names of the entries in these lists must match the ones in `start`. The default is to assume that the parameters have no upper bound. Only the bounds for bounded parameters need to be specified.
`control`	a list with configurations to be passed to the optimization subroutines. Missing arguments will receive default values. See fit.control.
`report`	logical, if `TRUE` the summary from model estimation is printed and `info` is automatically set to `TRUE`. Default is `TRUE`.
`...`	further arguments passed to the internal functions.

Details

Neither the beta regression or an i.i.d. sample from a beta distribution can be obtained as special cases of the \betaARC model since the term h(T(U_0)) is always present

The model from Pumi et al. (2021) is obtained by setting xregar = TRUE (so that the regressors are included in the AR part of the model) and using the same link for y_t and \mu_t.

The function BARC.sim generates a random sample from a \betaARC(p) model.

The function BARC.extract allows the user to extract the components y_t, \mu_t, \eta_t = g(\mu_t), r_t, T^t(u_0), the log-likelihood, and the vectors and matrices used to calculate the score vector and the information matrix associated to a given set of parameters.

This function can be used by any user to create an objective function that can be passed to optimization functions not available in BTSR Package. At this point, there is no other use for which this function was intended.

The function BARC.fit fits a BARC model to a given univariate time series. For now, available optimization algorithms are "L-BFGS-B" and "Nelder-Mead". Both methods accept bounds for the parameters. For "Nelder-Mead", bounds are set via parameter transformation.

Value

The function BARC.sim returns the simulated time series yt by default. If complete = TRUE, a list with the following components is returned instead:

model: string with the text "BARC"
yt: the simulated time series
mut: the conditional mean
etat: the linear predictor g(\mu_t)
error: the error term r_t
xreg: the regressors (if included in the model).
debug: the output from FORTRAN (if requested).

The function BARC.extract returns a list with the following components.

model: string with the text "BARC".
coefs: the coefficients of the model passed through the coefs argument.
yt: the observed time series.
gyt: the transformed time series g_2(y_t).
mut: the conditional mean.
etat: the linear predictor g_1(\mu_t).
error: the error term r_t.
xreg: the regressors (if included in the model).
TS: the chaotic process T^t(u0).
sll: the sum of the conditional log-likelihood (if requested).
sco: the score vector (if requested).
info: the information matrix (if requested).
Drho, T, E, h: additional matrices and vectors used to calculate the score vector and the information matrix. (if requested).
yt.new: the out-of-sample forecast (if requested).
Ts.new: the out-of-sample forecast for the chaotic process (if requested).
out.Fortran: FORTRAN output (if requested).

The function btsr.fit returns a list with the following components. Each particular model can have additional components in this list.

model: string with the text "BARC"
convergence: An integer code. 0 indicates successful completion. The error codes depend on the algorithm used.
message: A character string giving any additional information returned by the optimizer, or NULL.
counts: an integer giving the number of function evaluations.
control: a list of control parameters.
start: the starting values used by the algorithm.
coefficients: The best set of parameters found.
n: the sample size used for estimation.
series: the observed time series
gyt: the transformed time series g_2(y_t)
fitted.values: the conditional mean, which corresponds to the in-sample forecast, also denoted fitted values
etat: the linear predictor g_1(\mu_t)
error.scale: the scale for the error term.
error: the error term r_t
residual: the observed minus the fitted values. The same as the error term if error.scale = 0.
forecast: the out-of-sample forecast for y_t (if requested).
Ts.forecas: the out-of-sample forecast for T^t(u_0) (if requested).
xnew: the observations of the regressors observed/predicted values corresponding to the period of out-of-sample forecast. Only inlcudes if xreg is not NULL and nnew > 0.
sll: the sum of the conditional log-likelihood (if requested)
info.Matrix: the information matrix (if requested)
configs: a list with the configurations adopted to fit the model. This information is used by the prediction function.
out.Fortran: FORTRAN output (if requested)
call: a string with the description of the fitted model.

The map function

The map function T:[0,1] \to [0,1] is a dynamical system, i.e., a function, potentially depending on a r-dimensional vector of parameters \theta. Available choices are

map = 1, \theta = k, for k integer greater or equal to 2.

T(u) = (ku)(mod 1)
map = 2, 0 \le \theta \le 1

T(u) = \frac{u}{\theta}I_( u < \theta) + \theta\frac{(u - \theta)}{(1 - \theta)}I(u \ge \theta)
map = 3 (logistic map), 0 \le \theta \le 4,

T(u) = \theta(1-\theta)
map = 4 (Manneville-Pomeau map), 0 < \theta < 1

T(u) = (u + u^{1+\theta})(mod 1)
map = 5 (Lasota-Mackey's map),

T(u) = \frac{u}{(1 - u)}I(u \le 0.5) + (2u - 1)I(u > 0.5)

References

Pumi, G.; Prass, T.S. and Souza, R.R. (2021). A dynamic model for double bounded time series with chaotic driven conditional averages. Scandinavian Journal of Statistics. Vol 48 (1), 68-86.

Examples

m1 <- BARC.sim(linkg = "linear", linkh = "linear",
              n = 100, seed = 2021, complete = TRUE, ctt.h = 0.6,
             coefs = list(nu = 15, theta = 0.85, u0 = pi/4))

plot.ts(m1$yt)
lines(m1$mut, col = "red")

 #------------------------------------------------------------
 # Generating a sample from a BARC model
 #------------------------------------------------------------

 m1 <- BARC.sim(linkg = "linear", linkh = "linear",
               n = 100, seed = 2021, complete = TRUE, ctt.h = 0.6,
               coefs = list(nu = 15, theta = 0.85, u0 = pi/4))

 #------------------------------------------------------------
 #  Extracting the conditional time series given yt and
 #  a set of parameters
 #------------------------------------------------------------

  e1 = BARC.extract(yt = m1$yt, map = 4, ctt.h = 0.6,
                    coefs = list(nu = 15, theta = 0.85),
                    fixed.values = list(u0 = pi/4),
                    linkg = "linear", linkh = "linear", llk = TRUE,
                    sco = TRUE, info = TRUE)

 #----------------------------------------------------
 # comparing the simulated and the extracted values
 #----------------------------------------------------
 cbind(head(m1$mut), head(e1$mut))

 #---------------------------------------------------------
 # the log-likelihood, score vector and information matrix
 # score vector and information matrix are obtained
 # numerically.
 #---------------------------------------------------------
 e1$sll
 e1$score
 e1$info.Matrix


 #------------------------------------------------------------
 # Generating a sample from a BARC model
 #------------------------------------------------------------

 m1 <- BARC.sim(linkg = "linear", linkh = "linear",
               n = 100, seed = 2021, complete = TRUE, ctt.h = 0.6,
               coefs = list(nu = 15, theta = 0.85, u0 = pi/4))

 #------------------------------------------------------------
 #  Fitting a BARC model. Assuming only alpha fixed.
 #------------------------------------------------------------
  f1 = BARC.fit(yt = m1$yt, map = 4, ctt.h = 0.6,
                start = list(nu = 10, theta = 0.6, u0 = 0.5),
                lower = list(nu = 0, theta = 0, u0 = 0),
                upper = list(theta = 1, u0 = 1),
                fixed.values = list(alpha = 0),
                control = list(iprint = -1, method = "Nelder-Mead"))

  coefficients(f1)

  plot.ts(m1$yt)
  lines(f1$fitted.values, col = "red")

 #------------------------------------------------------------
 #  Out-of-sample forecast
 #------------------------------------------------------------
 pred = predict(f1, nnew = 5)
 pred$forecast
 pred$Ts.forecast

[Package BTSR version 0.1.5 Index]