R: Functions to simulate, extract components and fit BARFIMA...

BARFIMA.functions {BTSR}

R Documentation

Functions to simulate, extract components and fit BARFIMA models

Description

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

The \betaARMA model, the beta regression and a i.i.d. sample from a beta distribution can be obtained as special cases. See ‘Details’.

Usage

BARFIMA.sim(n = 1, burn = 0, xreg = NULL, coefs = list(alpha = 0, beta
  = NULL, phi = NULL, theta = NULL, d = 0, nu = 20), y.start = NULL,
  xreg.start = NULL, xregar = TRUE, error.scale = 1, complete = FALSE,
  inf = 1000, linkg = c("logit", "logit"), seed = NULL, rngtype = 2,
  debug = FALSE)

BARFIMA.extract(yt, xreg = NULL, nnew = 0, xnew = NULL, p, q,
  coefs = list(), lags = list(), fixed.values = list(),
  fixed.lags = list(), y.start = NULL, xreg.start = NULL,
  xregar = TRUE, error.scale = 1, inf = 1000, m = 0,
  linkg = c("logit", "logit"), llk = TRUE, sco = FALSE, info = FALSE,
  extra = FALSE, debug = FALSE)

BARFIMA.fit(yt, xreg = NULL, nnew = 0, xnew = NULL, p = 0, d = TRUE,
  q = 0, m = 0, inf = 1000, start = list(), ignore.start = FALSE,
  lags = list(), fixed.values = list(), fixed.lags = list(),
  lower = list(nu = 0), upper = list(nu = Inf), linkg = c("logit",
  "logit"), sco = FALSE, info = FALSE, extra = FALSE, xregar = TRUE,
  y.start = NULL, xreg.start = NULL, error.scale = 1, 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. The length of the "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`.
`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` optionally, for the simulation function this must be a vector of size `q`, corresponding to the moving average coefficients (including the ones that are zero), where `q` is the MA order. For the extraction and fitting functions, this is a vector with the non-fixed values in the vector of moving average coefficients. `d` optionally, a numeric value corresponding to the long memory parameter. If the argument is missing, it will be treated as zero. `nu` the dispersion parameter. If missing, an error message is issued.
`y.start`	optionally, an 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 1.
`complete`	logical; if `FALSE` the function returns only the simulated time series yt, otherwise, additional time series are provided. Default is `FALSE`
`inf`	the truncation point for infinite sums. Default is 1,000. In practice, the Fortran subroutine uses `inf = q`, if `d = 0`.
`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("logit", "logit")`. For the linear link, the constant will be always 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: the Mersenne Twister algorithm. See ‘Common Arguments’ in `btsr.functions`.
`debug`	logical, if `TRUE` the output from FORTRAN is return (for debugging 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.
`q`	a non-negative integer. The order of the MA polynomial. If missing, the value of `q` is calculated from length(coefs$theta) and length(fixed.values$theta). For fitting, the default is 0.
`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.
`m`	a non-negative integer indicating the starting time for the sum of the partial log-likelihoods, that is `\ell = \sum_{t = m+1}^n \ell_t`. Default is 0.
`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`.
`extra`	logical, if `TRUE` the matrices and vectors used to calculate the score vector and the information matrix are returned. Default is `FALSE`.
`d`	logical, if `TRUE`, the parameter `d` is included in the model either as fixed or non-fixed. If `d = FALSE` the value is fixed as 0. The default is `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

The \betaARMA model and the beta regression can be obtained as special cases of the \betaARFIMA model.

\betaARFIMA: the model from Pumi et al. (2019) is obtained by setting error.scale = 1 (predictive scale) and xregar = TRUE (so that the regressors are included in the AR part of the model). Variations of this model are obtained by changing error.scale, xregar and/or by using different links for y[t] (in the AR part of the model) and \mu[t].
\betaARMA: the model from Rocha and Cribari-Neto (2009, 2017) is obtained by setting coefs$d = 0 and d = FALSE and error.scale = 1 (predictive scale). Variations of this model are obtained by changing the error scale and/or by using a different link for y[t] in the AR part of the model.
beta regression: the model from Ferrari and Cribari-Neto (2004) is obtained by setting p = 0, q = 0 and coefs$d = 0 and d = FALSE. The error.scale is irrelevant. The second argument in linkg is irrelevant.
an i.i.d. sample from a Beta distribution with parameters shape1 and shape2 (compatible with the one from rbeta) is obtained by setting linkg = "linear", p = 0, q = 0, d = FALSE and, in the coefficient list, alpha = shape1/(shape1+shape2) and nu = shape1+shape2. (error.scale and xregar are irrelevant)

The function BARFIMA.sim generates a random sample from a \betaARFIMA(p,d,q) model.

The function BARFIMA.extract allows the user to extract the components y_t, \mu_t, \eta_t = g(\mu_t), r_t, 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 algorithms not available in the BTSR Package.

The function BARFIMA.fit fits a BARFIMA 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 BARFIMA.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 "BARFIMA"
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 BARFIMA.extract returns a list with the following components.

model: string with the text "BARFIMA"
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).
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)
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 "BARFIMA"
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 (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.

References

Ferrari, S.L.P. and Cribari-Neto, F. (2004). Beta regression for modelling rates and proportions. J. Appl. Stat. 31 (7), 799-815.

Pumi, G.; Valk, M.; Bisognin, C.; Bayer, F.M. and Prass, T.S. (2019). Beta autoregressive fractionally integrated moving average models. Journal of Statistical Planning and Inference (200), 196-212.

Rocha, A.V. and Cribari-Neto, F. (2009). Beta autoregressive moving average models. Test 18 (3), 529–545.

Rocha, A.V. and Cribari-Neto, F. (2017). Erratum to: Beta autoregressive moving average models. Test 26 (2), 451-459.

Examples

# Generating a Beta model were mut does not vary with time
# yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu

y <- BARFIMA.sim(linkg = "linear", n = 1000, seed = 2021,
                 coefs = list(alpha = 0.2, nu = 20))
hist(y)

 #------------------------------------------------------------
 # Generating a Beta model were mut does not vary with time
 # yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu
 #------------------------------------------------------------

 m1 <- BARFIMA.sim(linkg = "linear",n = 100,
                   complete = TRUE, seed = 2021,
                   coefs = list(alpha = 0.2, nu = 20))

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

 # Assuming that all coefficients are non-fixed
 e1 = BARFIMA.extract(yt = m1$yt, coefs = list(alpha = 0.2, nu = 20),
                      link = "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
 #---------------------------------------------------------
 e1$sll
 e1$score
 e1$info.Matrix


# Generating a Beta model were mut does not vary with time
# yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu

y <- BARFIMA.sim(linkg = "linear", n = 100, seed = 2021,
               coefs = list(alpha = 0.2, nu = 20))

# fitting the model
f <- BARFIMA.fit(yt = y, report = TRUE,
                 start = list(alpha = 0.5, nu = 10),
                 linkg = "linear", d = FALSE)

[Package BTSR version 0.1.5 Index]