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 Section ‘The BTSR structure’ in
btsr-package for more details on the general structure. See also
‘Details’ below.
Usage
BARC.sim(n = 1, burn = 0, y.start = NULL, xreg = NULL,
xreg.start = NULL, xregar = TRUE, coefs = NULL, map = 4,
error.scale = 0, linkg = "linear", configs.linkg = NULL,
linkh = "linear", configs.linkh = list(ctt = 1, power = 1),
complete = FALSE, debug = FALSE)
BARC.extract(yt, y.start = NULL, xreg = NULL, xreg.start = NULL,
xnew = NULL, xregar = TRUE, nnew = 0, p = NULL, coefs = NULL,
lags = NULL, fixed.values = NULL, fixed.lags = NULL, error.scale = 0,
map = 4, linkg = "linear", configs.linkg = NULL, linkh = "linear",
configs.linkh = list(ctt = 1, power = 1), llk = TRUE, sco = FALSE,
info = FALSE, debug = FALSE)
BARC.fit(yt, y.start = NULL, xreg = NULL, xreg.start = NULL,
xregar = TRUE, xnew = NULL, nnew = 0, p = NULL,
ignore.start = FALSE, start = NULL, lags = NULL, fixed.values = NULL,
fixed.lags = NULL, lower = NULL, upper = NULL, map = 4,
linkg = "linear", configs.linkg = NULL, linkh = "linear",
configs.linkh = list(ctt = 1, power = 1), sco = FALSE, info = FALSE,
error.scale = 0, control = NULL, report = TRUE, debug = FALSE, ...)
Arguments
n |
a strictly positive integer. The sample size of |
burn |
a non-negative integer. length of "burn-in" period. Default is
|
y.start |
optionally, an initial value for |
xreg |
optionally, a vector or matrix of external regressors. Default
is |
xreg.start |
optionally, a vector of initial value for
|
xregar |
logical; indicates whether |
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
For simulation purposes, an empty list will result in an error message. For
extraction purposes, an error message will be issued if both |
map |
a non-negative integer from 1 to 5 corresponding to the map
function. Default is |
error.scale |
the scale for the error term. Default is |
linkg |
character or a two character vector indicating which links must
be used in the model. See the Section ‘The BTSR structure’ in
btsr-package for details and link.btsr for valid links. If only one
value is provided, the same link is used for |
configs.linkg |
a list with two elements, |
linkh |
a character indicating which link must be associated to the
chaotic process. See the Section ‘The BTSR structure’ in
btsr-package for details and link.btsr for valid links. Default is
|
configs.linkh |
a list with extra configurations for the link |
complete |
logical; if FALSE returns only |
debug |
logical, if |
yt |
a numeric vector with the observed time series. If missing, an error message is issued. |
xnew |
a vector or matrix, with |
nnew |
optionally, the number of out-of sample predicted values
required. Default is |
p |
optionally, a non-negative integer. The order of the AR polynomial.
Default is |
lags |
optionally, a list with the lags that the values in |
fixed.values |
optionally, a list with the values of the coefficients
that are fixed. The default is |
fixed.lags |
optionally, a list with the lags that the fixed values in
|
llk |
logical; indicates whether the value of the log-likelihood
function should be returned. Default is |
sco |
logical; indicates whether the score vector should be returned.
Default is |
info |
logical; indicates whether the information matrix should be
returned. Default is |
ignore.start |
logical; indicates whether the argument |
start |
a list with the starting values for the non-fixed coefficients
of the model. The default is |
lower |
optionally, list with the lower bounds for the parameters. The
names of the entries in these lists must match the ones in |
upper |
optionally, list with the upper bounds for the parameters. The
names of the entries in these lists must match the ones in |
control |
a list with configurations to be passed to the optimization
subroutines. Default is |
report |
logical; indicates whether the summary from the fitted model
should be be printed. Default is |
... |
further arguments passed to the internal functions. See, for instance, summary.btsr for details. |
Details
Sim, Extract and Fit functions
The function BARC.sim
generates a random sample from a BARC(p
)
model.
The function BARC.extract
allows the user to extract the components
Y_t
, \mu_t
, \eta_t = g(\mu_t)
, e_t
, T^t(U_0)
,
the log-likelihood, 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 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.
Particular cases
Neither the beta regression or an i.i.d. sample from a beta distribution can
be obtained as special cases of the BARC 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
.
Value
By default, the function BARC.sim
returns the simulated time series yt
.
If complete = TRUE
, it returns a list with the following components
-
model
: string with the text"BARC"
-
yt
: the simulated time seriesY_t
-
mut
: the conditional mean\mu_t
-
etat
: the linear predictor\eta_t = g_{11}(\mu_t)
-
u0
: the starting values ofU_0
-
Ts
: the chaotic processT^t(U_0)
-
error
: the error terme_{1t}
-
out.Fortran
: the output from FORTRAN (if requested).
The function BARC.extract
returns a list with the following components.
-
model
: string with the text"BARC"
-
yt
: the observed time seriesY_t
-
TS
: the chaotic processT^t(U_0)
. -
mut
: the conditional mean\mu_t
-
etat
: the linear predictor\eta_t = g_{11}(\mu_t)
-
error
: the error terme_{1t}
-
forecast
: the out-of-sample forecast (if requested) -
xnew
: the out-of-sample values ofxreg
provided by the user (only present if the model includes regressors and forecast is requested) -
sll
: the sum of the conditional log-likelihood (if requested) -
score
: the score vector (if requested) -
info.Matrix.
: the score vector (if requested) -
out.Fortran
: FORTRAN output (if requested)
The function BARC.fit
returns a list with the following components.
-
model
: string with the text"BARC"
-
call
: string with a complete description of the model, including the AR and MA order. -
n
: the sample size used for estimation. -
series
: the observed time seriesY_t
-
gyt
: a vector or a matrix with the transformed time seriesg_{11}(Y_t)
andg_{12}(Y_t)
. Only returns a matrix if the linksg_{11}
andg_{12}
are not the same. -
xreg
: a vector or matrix of regressors\boldsymbol{X}_t
(if included in the model). -
control
: a list of control parameters. -
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 (if any), orNULL
. -
counts
: an integer giving the number of function evaluations. -
start
: the starting values used by the algorithm. -
coefficients
: The best set of parameters found. -
fitted.values
: the conditional time series\mu_t
and the chaotic processT^t(U_0)
, which corresponds to the in-sample forecast, also denoted fitted values. -
etat
: the linear predictor\eta_{1t} = g_{11}(\mu_t)
-
error
: the error terme_{1t}
-
residual
: the observed valuesY_t
minus the fitted values\mu_t
. The same as theerror
term iferror.scale = 0
. -
forecast
: a matrix with the out-of-sample forecast (if requested) for\mu_t
and\eta_{1t}
-
xnew
: the observations of the regressors observed/predicted values corresponding to the period of out-of-sample forecast. Only included ifxreg
is notNULL
andnnew > 0
. -
sll
: the sum of the conditional log-likelihood (if requested) -
score
: the score vector (if requested) -
info.Matrix
: the information matrix (if requested) -
link
: the codes for the link functions (for summary purposes) -
configs
: a list with the configurations passed to FORTRAN to fit the model. This information is used by the prediction function. -
out.Fortran
: FORTRAN output (if requested).
The map function
The map function T:[0,1] \to [0,1]
in BARC models is a dynamical
system, i.e., a function, potentially depending on a r
-dimensional
vector of parameters \theta
. As for today, for all implemented maps,
r = 1
.
Available choices are
-
map = 1
,\theta = k
, fork
integer greater or equal to 2.T(u) = (ku)(\text{mod } 1)
-
map = 2
,0 \le \theta \le 1
T(u) = \dfrac{u}{\theta}I( u < \theta) + \theta\dfrac{(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})(\text{mod } 1)
-
map = 5
(Lasota-Mackey's map),T(u) = \dfrac{u}{(1 - u)}I(u \le 0.5) + (2u - 1)I(u > 0.5)
References
Pumi G, Prass TS, Souza RR (2021). “A dynamic model for double bounded time series with chaotic driven conditional averages.” Scandinavian Journal of Statistics, 48(1), 68–86. doi:10.1111/sjos.12439.
See Also
BTSR.functions: sim, extract and fit functions for BTSR models
BTSR.parent.models: sim, extract and fit functions for parent models
get.defaults: Retrieve default arguments for BTSR package functions
Examples
#########################################################################
#
# Example of usage of BARC.sim, BARC.extract and BARC.fit
#
#########################################################################
#------------------------------------------------------------
# Generating a sample from a BARC model
#------------------------------------------------------------
set.seed(1234)
m1 <- BARC.sim(
coefs = list(nu = 15, theta = 0.85, u0 = pi / 4),
linkg = "linear",
linkh = "linear",
configs.linkh = list(ctt = 0.6),
n = 100,
complete = TRUE
)
plot.ts(m1$yt)
lines(m1$mut, col = "red")
#------------------------------------------------------------
# Extracting the conditional time series given yt and
# a set of parameters
#------------------------------------------------------------
e1 <- BARC.extract(
yt = m1$yt,
map = 4,
coefs = list(nu = 15, theta = 0.85),
fixed.values = list(u0 = pi / 4),
linkg = "linear",
linkh = "linear",
configs.linkh = list(ctt = 0.6),
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
#------------------------------------------------------------
# Fitting a BARC model. Assuming only alpha fixed.
#------------------------------------------------------------
f1 <- BARC.fit(
yt = m1$yt,
map = 4,
configs.linkh = list(ctt = 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[, "mut"], col = "red")
#------------------------------------------------------------
# Out-of-sample forecast
#------------------------------------------------------------
pred <- predict(f1, nnew = 5)
pred$forecast