BTSR.parent.models {BTSR}R Documentation

BTSR models with \nu constant over time

Description

Function to simulate, extract components, and fit BTSR parent models

all of which are special cases of the general BTSR structure. See the Section ‘The BTSR Structure’ in btsr-package for details. These functions are maintained for backward compatibility.

All models share core arguments with

Usage

BARFIMA.sim(n = 1, burn = 0, y.start = NULL, xreg = NULL,
  xreg.start = NULL, xregar = TRUE, coefs = NULL, error.scale = 1,
  linkg = "logit", configs.linkg = NULL, inf = 1000, complete = FALSE,
  debug = FALSE)

BARFIMAV.sim(vt.start = NULL, e2.start = NULL, linkg = list(g11 =
  "logit", g2 = "default", g21 = "log"), ...)

GARFIMA.sim(linkg = "log", ...)

GARFIMAV.sim(vt.start = NULL, e2.start = NULL, linkg = list(g11 = "log",
  g2 = "default", g21 = "log"), ...)

KARFIMA.sim(rho = 0.5, y.lower = 0, y.upper = 1, ...)

KARFIMAV.sim(rho = 0.5, y.lower = 0, y.upper = 1, vt.start = NULL,
  e2.start = NULL, linkg = list(g11 = "logit", g2 = "default", g21 =
  "logit"), ...)

MARFIMA.sim(linkg = "cloglog", ...)

ULARFIMA.sim(...)

UWARFIMA.sim(rho = 0.5, ...)

UWARFIMAV.sim(rho = 0.5, vt.start = NULL, e2.start = NULL,
  linkg = list(g11 = "logit", g2 = "default", g21 = "log"), ...)

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

BARFIMAV.extract(vt.start = NULL, e2.start = NULL, linkg = list(g11 =
  "logit", g2 = "default", g21 = "log"), ...)

GARFIMA.extract(linkg = "log", ...)

GARFIMAV.extract(vt.start = NULL, e2.start = NULL, linkg = list(g11 =
  "log", g2 = "default", g21 = "log"), ...)

KARFIMA.extract(rho = 0.5, y.lower = 0, y.upper = 1, ...)

KARFIMAV.extract(rho = 0.5, y.lower = 0, y.upper = 1, vt.start = NULL,
  e2.start = NULL, linkg = list(g11 = "logit", g2 = "default", g21 =
  "logit"), ...)

MARFIMA.extract(linkg = "cloglog", ...)

ULARFIMA.extract(...)

UWARFIMA.extract(rho = 0.5, ...)

UWARFIMAV.extract(rho = 0.5, vt.start = NULL, e2.start = NULL,
  linkg = list(g11 = "logit", g2 = "default", g21 = "log"), ...)

BARFIMA.fit(yt, xreg = NULL, nnew = 0, xnew = NULL, y.start = NULL,
  xreg.start = NULL, p = NULL, d = FALSE, q = NULL, xregar = TRUE,
  inf = 1000, start = NULL, ignore.start = FALSE, lags = NULL,
  fixed.values = NULL, fixed.lags = NULL, lower = NULL, upper = NULL,
  error.scale = 1, linkg = "logit", configs.linkg = NULL, m = 0,
  llk = TRUE, sco = FALSE, info = FALSE, extra = FALSE,
  control = NULL, report = TRUE, debug = FALSE, ...)

BARFIMAV.fit(vt.start = NULL, e2.start = NULL, linkg = list(g11 =
  "logit", g2 = "default", g21 = "log"), ...)

GARFIMA.fit(linkg = "log", ...)

GARFIMAV.fit(vt.start = NULL, e2.start = NULL, linkg = list(g11 = "log",
  g2 = "default", g21 = "log"), ...)

KARFIMA.fit(rho = 0.5, y.lower = 0, y.upper = 1, ...)

KARFIMAV.fit(rho = 0.5, y.lower = 0, y.upper = 1, vt.start = NULL,
  e2.start = NULL, linkg = list(g11 = "logit", g2 = "default", g21 =
  "logit"), ...)

MARFIMA.fit(linkg = "cloglog", ...)

ULARFIMA.fit(...)

UWARFIMA.fit(rho = 0.5, ...)

UWARFIMAV.fit(rho = 0.5, vt.start = NULL, e2.start = NULL,
  linkg = list(g11 = "logit", g2 = "default", g21 = "log"), ...)

Arguments

n

the sample size of the output time series yt after burn-in (simulation only). Default is n = 1.

burn

the length of the ‘burn-in’ period (simulation only). Default is burn = 0. The first burn values of the time series are discarded.

y.start

optional; an initial value for Y_t (to initialize recursions when t < 1). Default is y.start = NULL, in which case, the recursion assumes that Y_t = g_{12}^{-1}(0), for t < 1. Only relevant if p > 0.

xreg

optional; external regressors. Can be specified as a vector, a matrix or a list. Default is xreg = NULL. For details, see the Section Regressors format.

xreg.start

optional; initial value for the regressors (to initialize recursion). Can be specified as a vector or a list. Default is xreg.start = NULL, in which case, the average of the first p values (AR order) is used. Only relevant if xreg is provided, xregar = TRUE and p > 0. For details, see the Section Regressors format.

xregar

a length 1 or 2 logical vector indicating whether xreg should be included in the AR recursion for each part of the model. Default is xregar = TRUE. Only relevant if p > 0. If a single value is provided and \nu is time-varying, the same option is assumed for both parts of the model. See the Section ‘The BTSR structure’ in btsr-package for details.

coefs

a list with the coefficients of the model (simulation and extraction only). The default is coefs = NULL. For details on the expected format and the arguments that can be passed through coefs, see the Section Model coefficients.

error.scale

either 0 or 1; the scale for the error term. Default is error.scale = 1 (predictive scale).

linkg

link functions. Can be specified as a character, two-character vector or a named list. The corresponding text strings for currently available links are listed in link.btsr. Default values depend on the model. For some models default values override user specifications. See the Section Link defaults for details.

configs.linkg

a list with two elements, ctt and power, which define the constant a and the exponent b in the link function g(x) = a x^b. Each element can be specified as a numeric value, a vector of size 2 or a named list. The default is configs.linkg = NULL. See the Section Link defaults for details.

inf

a length 1 or 2 integer vector given the truncation point for infinite sums. Default is inf = 1000. See the Section Model Order for details.

complete

logical; if FALSE returns only yt, else returns additional components (simulation only). Default is complete = FALSE.

debug

logical, if TRUE the output from FORTRAN is return (for debugging purposes). Default is debug = FALSE.

vt.start

optional; an initial value for \vartheta_t (to initialize recursions when t < 1). Default is vt.start = NULL, in which case, the recursion assumes that \vartheta_t = g_{22}^{-1}(0), for t < 1. Only relevant if \nu is time-varying and p_2 > 0.

e2.start

optional; an initial value for g_{23}(e_{1t}) (to initialize recursions when t < 1). Default is e2.start = NULL, in which case, the recursion assumes that e_{1t} = g_{23}^{-1}(0), for t < 1. Only relevant if \nu is time-varying and q_2 > 0 or d_2 > 0.

...

further arguments passed to the internal functions. See, for instance, summary.btsr for details.

rho

the quantile being considered in the conditional distribution of Y_t (only present in Kumaraswamy and Unit-Weibull based models). It can be any positive number between 0 and 1. Default is rho = 0.5, which corresponds to the median.

y.lower

the lower limit for the Kumaraswamy density support. Default is y.lower = 0.

y.upper

the upper limit for the Kumaraswamy density support. Default is y.upper = 1.

yt

numeric vector with the observed time series (extract and fit only). Missing values (NA's) are not allowed.

nnew

optional; the number of out-of sample predicted values required (extract and fit only). Default is nnew = 0.

xnew

optional; nnew new observations of the external regressors (extract and fit only). Follows the same format is the same as xreg. Default is xnew = NULL.

p

optional; a length 1 or 2 integer vector given the order of the AR polynomial (extract and fit only). Default is p = NULL. See the Section Model Order for details.

q

optional; a length 1 or 2 integer vector given the order of the MA polynomial (extract and fit only). Default is q = NULL. See the Section Model Order for details.

lags

optional; a list with the lags (integer values) that the entries in coefs or start correspond to (extract and fit only). The default is lags = NULL, in which the lags are computed from the fixed.lags argument (if provided). When components are missing or empty in both, lags and fixed.lags, the default behavior is to include all lags based on nreg = ncol(xreg), p, and q. For details, see the Section Model coefficients.

fixed.values

optional; a list with the values of the coefficients that are fixed (extract and fit only). The default is fixed.values = NULL. See the Section Model coefficients.

fixed.lags

optional; a list with the lags (integer values) that the fixed values in fixed.values correspond to (extract and fit only). The default is fixed.lags = NULL. For missing components, fixed values will are set based on lags.

m

a non-negative integer indicating the starting time for the sum of the partial log-likelihood, given by \ell = \sum_{t = m+1}^n \ell_t (extract and fit only). Default is m = 0. For details, see the Section The log-likelihood.

llk

logical; indicates whether the value of the log-likelihood function should be returned (extract and fit only). Default is llk = TRUE.

sco

logical; indicates whether the score vector should be returned (extract and fit only). Default is sco = FALSE.

info

logical; indicates whether the information matrix should be returned (extract and fit only). Default is info = 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 (extract and fit only). Default is extra = FALSE. Ignored by BARC models.

d

a length 1 or 2 logical vector indicating whether the long memory parameter d should be included in the model either as a fixed or non-fixed parameter (fit only). If d = FALSE, internally the value of the parameter d is fixed as 0. In this case, if start or fixed.values include d, the value provided by the user is ignored. If \nu is time-varying and a single value is provided it is assumed that d_1 = d_2 = d.

start

optional; a list with the starting values for the non-fixed coefficients of the model (fit only). The default is start = NULL, in which case the function coefs.start is used internally to obtain starting values for the parameters. For details on the expected format and the arguments that can be passed through coefs, see the Section Model coefficients.

ignore.start

optional; logical value indicating whether the argument start should be ignored (fit only). 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 ignore.start = FALSE. Partial starting values are not allowed.

lower

optional; list with the lower bounds for the parameters (fit only). Default is lower = NULL. 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. The format of lower and the arguments that can be passed through this list are the same as the ones for start.

upper

optional; list with the upper bounds for the parameters (fit only). Default is upper = NULL. The default is to assume that the parameters have no upper bound. Only the bounds for bounded parameters need to be specified. The format of lower and the arguments that can be passed through this list are the same as the ones for start.

control

a list with configurations to be passed to the optimization subroutines (fit only). Default is control = NULL. Missing arguments will receive default values. For details, see fit.control.

report

logical; indicates whether the summary from the fitted model should be be printed (fit only). Default is report = TRUE, in which case info is automatically set to TRUE.

Details

All functions implemented in the current version of the package are compatible with the new format for the arguments, introduced in version 1.0.0. and the previous format.

Value

These functions return the same ouptuts as btsr.sim, btsr.extract and btsr.fit.

See Also

BTSR.functions, BARC.functions, link.btsr, get.defaults

Examples


#########################################################################
#
#   Examples of usage of "MODEL.sim" type of functions
#
#########################################################################
#------------------------------------------------------------------------
# iid samples
#------------------------------------------------------------------------
# BARFIMA: yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu
# CASE 1: using coefs as in the previous version of the package
set.seed(1234)
yb1 <- BARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5, nu = 20)
)
hist(yb1)

# CASE 2: using the new layout
set.seed(1234)
yb2 <- BARFIMA.sim(
  n = 1000,
  linkg = list(g11 = "linear", g2 = "linear", g21 = "linear"),
  coefs = list(part1 = list(alpha = 0.5), part2 = list(alpha = 20))
)
hist(yb2)

# comparing the results
range(abs(yb2 - yb1))

# samples from other models in the package
yg <- GARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5, nu = 20)
)
yk <- KARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5, nu = 20)
)
ym <- MARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5)
)
yul <- ULARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5)
)
yuw <- UWARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.5, nu = 20)
)

# comparing the different distributions
par(mfrow = c(2, 3))
hist(yb1, xlim = c(0, 1))
hist(yk, xlim = c(0, 1))
hist(yg, xlim = c(0, 1))
hist(ym, xlim = c(0, 1))
hist(yul, xlim = c(0, 1))
hist(yuw, xlim = c(0, 1))

#------------------------------------------------------------------------
#  BARFIMA(1,d,1) with d = 0.25 and no regressors
#------------------------------------------------------------------------

# CASE 1: using coefs as in the previous version of the package
set.seed(1234)
y1 <- BARFIMA.sim(
  n = 1000,
  linkg = "logit",
  coefs = list(alpha = 0.2, phi = 0.2, theta = 0.4, d = 0.25, nu = 20)
)

# CASE 2: using the new layout
set.seed(1234)
y2 <- BARFIMA.sim(
  n = 1000,
  linkg = list(g11 = "logit", g2 = "linear", g21 = "linear"),
  coefs = list(
    part1 = list(alpha = 0.2, phi = 0.2, theta = 0.4, d = 0.25),
    part2 = list(alpha = 20)
  )
)

# comparing the results
range(abs(y1 - y2))

#########################################################################
#
#   Examples of usage of "MODEL.extract" type of functions
#
#########################################################################

#------------------------------------------------------------------------
#  code to simulate and extract components of a BARMA(1,1) model
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar <- cbind(sin(2 * pi * (1:N) / 50), 1:N)

set.seed(1234)
m1 <- BARFIMA.sim(
  linkg = "logit", n = n, burn = burn, xreg = covar,
  coefs = list(
    alpha = 0, phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002), nu = 20
  ), complete = TRUE
)

# Extracting assuming that all coefficients are non-fixed
e1 <- BARFIMA.extract(
  yt = m1$yt, xreg = covar[(burn + 1):N, ], linkg = "logit",
  coefs = list(
    alpha = 0, phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002), nu = 20
  ),
  llk = TRUE, sco = TRUE, info = TRUE
)

# Extracting assuming that all coefficients are fixed
e2 <- BARFIMA.extract(
  yt = m1$yt, xreg = covar[(burn + 1):N, ], linkg = "logit",
  fixed.values = list(
    alpha = 0, phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002), nu = 20
  ),
  llk = TRUE, sco = TRUE, info = TRUE
)

# Extracting using a mix of fixed and non-fixed parameters
e3 <- BARFIMA.extract(
  yt = m1$yt, xreg = covar[(burn + 1):N, ], linkg = "logit",
  coefs = list(
    phi = -0.65, theta = -0.25,
    beta = c(0.6)
  ),
  fixed.values = list(alpha = 0, nu = 20, beta = -0.002),
  fixed.lags = list(beta = 2),
  llk = TRUE, sco = TRUE, info = TRUE
)

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

# comparing the log-likelihood values obtained (must be the all equal)
c(e1$sll, e2$sll, e3$sll)

# comparing the score vectors:
# - e1 must have 6 values: dl/dro values and dl/dlambda values
# - e2 must be empty (all parameters are fixed)
# - e3 must have only the values corresponding to the non-fixed coefficients.
round(e1$score, 4)
e2$score
round(e3$score, 4)

# comparing the information matrices.
# - e1 must be a 6x6 matrix
# - e2 must be empty
# - e3 must have only the value corresponding to the non-fixed coefficient
round(e1$info.Matrix, 4)
e2$info.Matrix
round(e3$info.Matrix, 4)

#########################################################################
#
#   Examples of usage of "MODEL.fit" type of functions
#
#########################################################################

#------------------------------------------------------------------------
#  code to simulate and fit a BARMA(1,1) model
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar <- cbind(sin(2 * pi * (1:N) / 50), 1:N)

set.seed(1234)
m1 <- BARFIMA.sim(
  linkg = "logit", n = n, burn = burn, xreg = covar,
  coefs = list(
    alpha = 0, phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002), nu = 20
  ),
  complete = TRUE
)

plot.ts(m1$yt)

# Fit a model assuming that all coefficients are non-fixed
# for a more simplified summary, set full.report = FALSE
f1 <- BARFIMA.fit(
  yt = m1$yt, xreg = covar[(burn + 1):N, ],
  linkg = "logit", p = 1, q = 1, report = TRUE
)

# the fitted coefficients (full model, including d)
coefficients(f1)

# if you try to use `robust` or `outer` without setting `extra = TRUE`, the
# code issues a message and uses the information matrix
summary(f1, robust = TRUE)
summary(f1, outer = TRUE)

# Fit a model assuming alpha and d are fixed
f2 <- BARFIMA.fit(
  yt = m1$yt, xreg = covar[(burn + 1):N, ], linkg = "logit",
  p = 1, q = 1, fixed.values = list(alpha = 0, d = 0)
)
# Alternatively, set `d = FALSE`
f2 <- BARFIMA.fit(
  yt = m1$yt, xreg = covar[(burn + 1):N, ], linkg = "logit",
  p = 1, q = 1, fixed.values = list(alpha = 0), d = FALSE
)

# comparing the results
true <- c(
  alpha = 0, beta = c(0.6, -0.002),
  phi = -0.65, theta = -0.25,
  d = 0, nu = 20
)
cf1 <- coefficients(f1)
cf2 <- c(NA, coefficients(f2)[1:4], NA, coefficients(f2)[5])
round(cbind(true, cf1, cf2), 3)


[Package BTSR version 1.0.0 Index]