BTSR.functions {BTSR}R Documentation

Generic functions to simulate, extract components and fit BTSR models

Description

These generic functions can be used to simulate, extract components and fit any model of the class btsr. See ‘Details’ below.

The package handles function arguments in two compatible formats

All functions accept both formats seamlessly, ensuring backward compatibility. The internal processing automatically standardizes to the new structure.

Usage

btsr.sim(model, ...)

btsr.extract(model, ...)

btsr.fit(model, ...)

Arguments

model

character string (case-insensitive) indicating the model to be fitted to the data. Must be one of the options listed in the Section Supported Models.

...

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

Details

A detailed description of the general structure (mathematical formulation) of BTSR models, associated to the btsr class, is presented in Section ‘The BTSR Structure’ of btsr-package. Particular models are discussed in arguments.model.

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

For compatibility with previous versions of the package, all functions associated to parent models (e.g. BARFIMA) are still available (see BTSR.parent.models). Also, analogous functions are available for parent models with time varying \nu (e.g. BARFIMAV). The list of arguments and default values for these specific functions can be accessed using the function get.defaults.

Particular models (e.g. BETA, BARMA) share the same arguments as the parent model, however, some arguments can have different default values (see the documentation for shared arguments for details). Information on the parent model can be obtained using the function BTSR.model.defaults.

Value

By default, the simulation function return the simulated time series yt. If complete = TRUE, it returns a list with the following components

The extraction function returns a list with the following components

The fitting function returns a list with the following components.

See Also

BARC.functions: sim, extract and fit functions for BARC models

BTSR.parent.models: sim, extract and fit functions for parent models

get.defaults: Retrieve default arguments for BTSR package functions

Examples


#########################################################################
#
#   Examples of usage of btsr.sim
#
#########################################################################
#------------------------------------------------------------------------
# Generating a Beta model were both mu and nu do not vary with time
# yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu
#------------------------------------------------------------------------

# CASE 1: using the legacy format for coefs
set.seed(1234)
y1 <- btsr.sim(
  model = "BETA", n = 1000,
  coefs = list(alpha = 0.2, nu = 20)
)
hist(y1)

# CASE 2: using the new layout for coefs
set.seed(1234)
y2 <- btsr.sim(
  model = "BETA", n = 1000,
  coefs = list(part1 = list(alpha = 0.2), part2 = list(alpha = 20))
)
hist(y2)

# CASE 3: function for the parent model plus legacy format for coefs.
# - requires setting linkg = "linear", otherwhise the default "logit"
#   link is used.
set.seed(1234)
y3 <- BARFIMA.sim(
  linkg = "linear", n = 1000,
  coefs = list(alpha = 0.2, nu = 20)
)
hist(y3)

# CASE 4: function for the parent model plus new format for coefs.
# - requires setting linkg = "linear", otherwhise the default "logit"
#   link is used.
set.seed(1234)
y4 <- BARFIMA.sim(
  n = 1000, linkg = "linear",
  coefs = list(part1 = list(alpha = 0.2), part2 = list(alpha = 20))
)
hist(y4)

# comparing the results:
range(abs(y2 - y1))
range(abs(y3 - y1))
range(abs(y3 - y4))

#------------------------------------------------------------------------
# Generating a sample from a Beta regression model
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar <- cbind(sin(2 * pi * (1:N) / 50), 1:N)

set.seed(1234)
y1 <- btsr.sim(
  model = "BREG", linkg = "logit",
  n = n, burn = burn, xreg = covar,
  coefs = list(alpha = -1.3, beta = c(0.6, 0.002), nu = 30),
  complete = TRUE
)

# The regressors: X1 = sin(2*pi*t/50) and X2 = t
plot.ts(
  covar,
  main = "Regressors" ~ X[1][t] == sin(2 * pi * t / 50) ~ "and" ~ X[2][t] == t
)

# Conditional time series:
plot.ts(y1$etat, main = "Linear predictor" ~ eta[t] == g[11](mu[t]))
plot.ts(y1$mut, main = "Conditional mean" ~ mu[t])
plot.ts(y1$yt, main = "Time series" ~ Y[t])

#########################################################################
#
#   Examples of usage of btsr.extract
#
#########################################################################
#------------------------------------------------------------------------
# Generating a sample from a BARMAX(1,1) model (BARMA with covariates)
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar <- cbind(sin(2 * pi * (1:N) / 50), 1:N)

set.seed(1234)
m1 <- btsr.sim(
  model = "BARMA", 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
  ),
  error.scale = 1, complete = TRUE
)

# Extracting components assuming that all coefficients are non-fixed
e1 <- btsr.extract(
  model = "BARMA", 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 components assuming that all coefficients are fixed
#  - no need to provide fixed.lags in this case.
e2 <- btsr.extract(
  model = "BARMA", 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 components assuming that some coefficients are fixed
#  - e3 and e4 give the same result
#  - e3 uses legacy format for all arguments
#  - e4 uses the new format for all arguments (not optimal here)
e3 <- btsr.extract(
  model = "BARMA", yt = m1$yt,
  xreg = covar[(burn + 1):N, ], linkg = "logit",
  coefs = list(
    phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002)
  ),
  fixed.values = list(alpha = 0, nu = 20),
  llk = TRUE, sco = TRUE, info = TRUE
)

e4 <- btsr.extract(
  model = "BARMA", yt = m1$yt,
  xreg = list(part1 = covar[(burn + 1):N, ]),
  linkg = list(g11 = "logit"),
  coefs = list(part1 = list(
    phi = -0.65, theta = -0.25,
    beta = c(0.6, -0.002)
  )),
  fixed.values = list(
    part1 = list(alpha = 0),
    part2 = list(alpha = 20)
  ),
  llk = TRUE, sco = TRUE, info = TRUE
)

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

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

#----------------------------------------------------
# comparing the score vectors:
#----------------------------------------------------
# - e1 must have 6 values: dl/dro values and dl/dlambda values
# - e2 must be empty
# - e3 and e4 must have only the values corresponding
#    to the non-fixed coefficient. The value sof
#    dl/dlambda are the same as in e1, but dl/drho are
#    differente since the mixed derivatives are not present.
#----------------------------------------------------
round(e1$score, 4)
e2$score
e3$score
e4$score

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

#------------------------------------------------------------------------
# Generating a sample from a BARFIMAVX(1,d1,1)x(1,0,1) with d1 = 0.35
# (BARFIMAV with covariates)
# Here using the nre format for coefficients and xreg is required.
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar1 <- cbind(sin(2 * pi * (1:N) / 50), 1:N)
covar2 <- sin(2 * pi * (1:N) / 25)

set.seed(1234)
m1 <- btsr.sim(
  model = "BARFIMAV",
  linkg = list(g11 = "logit", g2 = "default", g21 = "logit"),
  n = n, burn = burn, xreg = list(part1 = covar1, part2 = covar2),
  coefs = list(
    part1 = list(
      alpha = 0, d = 0.35, phi = -0.65,
      theta = -0.25, beta = c(0.6, -0.002)
    ),
    part2 = list(
      alpha = -3, phi = 0.25,
      theta = -0.2, beta = -0.15
    )
  ),
  error.scale = 1, complete = TRUE, vt.start = 0.02
)


# Extracting components assuming that all coefficients are non-fixed
e1 <- btsr.extract(
  model = "BARFIMAV", yt = m1$yt,
  xreg = list(part1 = covar1[(burn + 1):N, ], part2 = covar2[(burn + 1):N]),
  linkg = list(g11 = "logit", g2 = "default", g21 = "logit"),
  coefs = list(
    part1 = list(
      alpha = 0, d = 0.35, phi = -0.65,
      theta = -0.25, beta = c(0.6, -0.002)
    ),
    part2 = list(
      alpha = -3, phi = 0.25,
      theta = -0.2, beta = -0.15
    )
  ),
  vt.start = 0.02,
  llk = TRUE, sco = TRUE, info = TRUE, extra = TRUE, debug = TRUE
)

# score vector
e1$score

# information matrix
e1$info.Matrix

#########################################################################
#
#   Examples of usage of btsr.fit
#
#########################################################################
#------------------------------------------------------------------------
#  Generating a sample from a BARMAVX(1,0)x(0,1) (BARMAV with covariates)
#------------------------------------------------------------------------
burn <- 100
n <- 500
N <- n + burn
covar1 <- cbind(sin(2 * pi * (1:N) / 50), 1:N)
covar2 <- sin(2 * pi * (1:N) / 25)

set.seed(1234)
m1 <- btsr.sim(
  model = "BARMAV",
  linkg = list(g11 = "logit", g2 = "default", g21 = "logit"),
  n = n, burn = burn, xreg = list(part1 = covar1),
  coefs = list(
    part1 = list(
      alpha = 0, phi = -0.3,
      beta = c(0.6, -0.002)
    ),
    part2 = list(alpha = -2.5, theta = -0.4)
  ),
  error.scale = 1, complete = TRUE
)

# fitting the model
f1 <- btsr.fit(
  model = "BARMAV", yt = m1$yt, report = FALSE, info = TRUE,
  xreg = list(part1 = covar1[(burn + 1):N, ]),
  linkg = list(g11 = "logit", g2 = "default", g21 = "logit"),
  p = c(1, 0), q = c(0, 1)
)

# fitting the model using the name string for the parent model
#   - same result
f2 <- btsr.fit(
  model = "BARFIMAV", yt = m1$yt, report = FALSE, info = TRUE,
  xreg = list(part1 = covar1[(burn + 1):N, ]),
  linkg = list(g11 = "logit", g2 = "default", g21 = "logit"),
  p = c(1, 0), q = c(0, 1), d = FALSE
)

summary(f1, full.report = TRUE) # default
summary(f2, full.report = TRUE)

summary(f1, full.report = FALSE) # simplified output
summary(f2, full.report = FALSE)



[Package BTSR version 1.0.0 Index]