btsr.functions {BTSR} | R Documentation |
These generic functions can be used to simulate, extract components
and fit any model of the class btsr
. All functions are wrappers
for the corresponding function associated to the chosen model.
See ‘The BTSR structure’ and ‘Common Arguments’.
btsr.sim(model, complete = FALSE, ...)
btsr.extract(model, ...)
btsr.fit(model, ...)
model |
character; one of |
complete |
logical; if |
... |
further arguments passed to the functions, according to
the model selected in the argument |
The function btsr.sim
is used to generate random samples
from BTSR models. See ‘The BTSR structure’.
The function btsr.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 functions not available in BTSR Package. At this point, there is no other use for which this function was intended.
The function btsr.fit
fits a BTSR 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.
The function btsr.sim
returns the simulated time series yt by default.
If complete = TRUE
, a list with the following components
is returned instead:
model
: character; one of "BARFIMA"
, "GARFIMA"
,
"KARFIMA"
, "BARC"
. (same as the input argument)
yt
: the simulated time series
gyt
: the transformed time series g2(y_t)
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 btsr.extract
returns a list with the following components.
Each particular model can have additional components in this list.
model
: character; one of "BARFIMA"
, "GARFIMA"
,
"KARFIMA"
, "BARC"
. (same as the input argument)
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).
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)
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
: character; one of "BARFIMA"
, "GARFIMA"
,
"KARFIMA"
, "BARC"
. (same as the input argument)
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
residuals
: the observed minus the fitted values. The same as
the error
term if error.scale = 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 general structure of the deterministic part of a BTSR model is
g_1(\mu_t) = \alpha + X_t\beta +
\sum_{j=1}^p \phi_j[g_2(y_{t-j}) - I_{xregar}X_{t-j}\beta] + h_t
where
I_{xregar}
is 0, if xreg
is not included in the AR part of the model and 1,
otherwise
the term h_t
depends on the argument model
:
for BARC models: h_t = h(T^{t-1}(u_0))
otherwise: h_t = \sum_{k = 1}^\infty c_k r_{t-k}
g_1
and g_2
are the links defined in linkg
.
Notice that g_2
is only used in the AR part of the model and, typically,
g_1 = g_2
.
r_t
depends on the error.scale
adopted:
if error.scale = 0
: r_t = y_t - \mu_t
(data scale)
if error.scale = 1
: r_t = g_1(y_t) - g_1(\mu_t)
(predictive scale)
c_k
are the coefficients of (1-L)^d\theta(L)
.
In particular, if d = 0
, then c_k = \theta_k
, for
k = 1, \dots, q
.
In what follows we describe some of the arguments that are commom to all BTSR models. For more details on extra arguments, see the corresponding function associated to the selected model.
Common arguments passed through "..."
in btsr.sim
are:
n
a strictly positive integer. The sample size of yt (after burn-in).
Default for all models is 1.
burn
a non-negative integer. length of "burn-in" period.
Default for all models is 0.
xreg
optionally, a vector or matrix of external regressors.
For simulation purposes, the length of xreg must be n+burn
.
Default for all models is NULL
coefs
a list with the coefficients of the model. Each model has
its default. An empty list will result in an error. The arguments in this list
are:
alpha
optionally, A numeric value corresponding to the intercept.
If the argument is missing, it will be treated as zero.
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, a vector of size p
, corresponding to the
autoregressive coefficients (including the ones that are zero), where p
is the AR order.
nu
the dispersion parameter. If missing, an error message is issued.
rho, y.lower, y.upper, theta, d, u0
model specif arguments.
See the documentation corresponding to each model.
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 also ‘The BTSR structure’.
Each model has its default.
inf
the truncation point for infinite sums. Default is 1000.
In practice, the Fortran subroutine uses inf = q
, if d = 0
.
BARC models do not have this argument.
linkg
character or a two character vector indicating which
links must be used in the model. See ‘The BTSR structure’.
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. Each model has its default.
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 current options are:
0
: Jason Blevins algorithm. Available at https://jblevins.org/log/openmp
1
: Wichmann-Hill algorithm (Wichmann and Hill, 1982).
2
: Mersenne Twister algorithm (Matsumoto and Nishimura, 1998).
FORTRAN code adapted from https://jblevins.org/mirror/amiller/mt19937.f90 and
https://jblevins.org/mirror/amiller/mt19937a.f90
3
: Marsaglia-MultiCarry algorithm - kiss 32. Random number generator suggested
by George Marsaglia in "Random numbers for C: The END?" posted on sci.crypt.random-numbers
in 1999.
4
: Marsaglia-MultiCarry algorithm - kiss 64. Based on the
64-bit KISS (Keep It Simple Stupid) random number generator distributed by
George Marsaglia in https://groups.google.com/d/topic/comp.lang.fortran/qFv18ql_WlU
5
: Knuth's 2002 algorithm (Knuth, 202). FORTRAN code adapted
from https://www-cs-faculty.stanford.edu/~knuth/programs/frng.f
6
: L'Ecuyer's 1999 algorithm - 64-bits (L'Ecuyer, 1999).
FORTRAN code adapted from https://jblevins.org/mirror/amiller/lfsr258.f90
For more details on these algorithms see Random
and references
therein.
debug
logical, if TRUE
the output from FORTRAN is return (for
debuggin purposes). Default is FALSE
for all models.
Common arguments passed through "..."
in btsr.extract
are:
yt
a numeric vector with the observed time series. If missing, an error
message is issued.
xreg
optionally, a vector or matrix with the regressor's values.
Default is NULL
for all models.
nnew
optionally, the number of out-of sample predicted values required.
Default is 0 for all models.
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).
q,r
a non-negative integer. The order of the MA polynomial and
the size of the vector of parameters for the map function (BARC only).
If missing, the argument is calcualted based on length(coefs$theta)
and length(fixed.values$theta).
coefs
a list with the coefficients of the model. Each model has
its default. Passing both, coefs
and fixed.values
empty
will result in an error. The arguments in this list are
alpha
a numeric value corresponding to the intercept.
If missing, will be set as zero.
beta
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
a vector with the non-fixed values in the vector of
AR coefficients.
nu
the dispersion parameter. If missing, an error message is issued.
theta, d, u0
model specific arguments. See the documentation
corresponding to each model.
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.
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 also ‘The BTSR structure’.
Each model has its default.
inf
the truncation point for infinite sums. Default is 1.
BARC models do not have this argument.
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.
linkg
character or a two character vector indicating which
links must be used in the model. See ‘The BTSR structure’.
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. Each model has its default.
llk
logical, if TRUE
the value of the log-likelihood function
is returned. Default is TRUE
for all models.
sco
logical, if TRUE
the score vector is returned.
Default is FALSE
for all models.
info
logical, if TRUE
the information matrix is returned.
Default is FALSE
for all models.
extra
logical, if TRUE
the matrices and vectors used to
calculate the score vector and the information matrix are returned.
Default is FALSE
for all models.
debug
logical, if TRUE
the output from FORTRAN is return (for
debuggin purposes). Default is FALSE
for all models.
Common arguments passed through "..."
in btsr.fit
are the same as
in btsr.extract
plus the following:
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
for all models, except BARC that does
not have this parameter.
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, upper
optionally, list with the lower and 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 are unbounded.
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
.
Knuth, D. E. (2002). The Art of Computer Programming. Volume 2, third edition, ninth printing.
L'Ecuyer, P. (1999). Good parameters and implementations for combined multiple recursive random number generators. Operations Research, 47, 159-164. doi:10.1287/opre.47.1.159.
Matsumoto, M. and Nishimura, T. (1998). Mersenne Twister: A 623-dimensionally equidistributed uniform pseudo-random number generator, ACM Transactions on Modeling and Computer Simulation, 8, 3-30.
Wichmann, B. A. and Hill, I. D. (1982). Algorithm AS 183: An Efficient and Portable Pseudo-random Number Generator. Applied Statistics, 31, 188-190; Remarks: 34, 198 and 35, 89. doi:10.2307/2347988.
BARFIMA.sim
, GARFIMA.sim
,
KARFIMA.sim
, BARC.sim
BARFIMA.extract
, GARFIMA.extract
,
KARFIMA.extract
, BARC.extract
BARFIMA.fit
, GARFIMA.fit
,
KARFIMA.fit
, BARC.fit
# Generating a Beta model were mut does not vary with time
# yt ~ Beta(a,b), a = mu*nu, b = (1-mu)*nu
y <- btsr.sim(model= "BARFIMA", 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 <- btsr.sim(model= "BARFIMA", linkg = "linear",
n = 100, seed = 2021, complete = TRUE,
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 = btsr.extract(model = "BARFIMA", yt = m1$yt,
coefs = list(alpha = 0.2, nu = 20),
link = "linear", llk = TRUE,
sco = TRUE, info = TRUE)
# Assuming that all coefficients are fixed
e2 = btsr.extract(model = "BARFIMA", yt = m1$yt,
fixed.values = list(alpha = 0.2, nu = 20),
link = "linear", llk = TRUE,
sco = TRUE, info = TRUE)
# Assuming at least one fixed coefficient and one non-fixed
e3 = btsr.extract(model = "BARFIMA", yt = m1$yt,
fixed.values = list(alpha = 0.2, nu = 20),
link = "linear", llk = TRUE,
sco = TRUE, info = TRUE)
e4 = btsr.extract(model = "BARFIMA", yt = m1$yt,
fixed.values = 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), 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 2 values: dl/dmu and dl/dnu
# - e2 must be empty
# - e3 and e4 must have one value corresponding
# to the non-fixed coefficient
#----------------------------------------------------
e1$score
e2$score
e3$score
e4$score
#----------------------------------------------------
# comparing the information matrices.
#----------------------------------------------------
# - e1 must be a 2x2 matrix
# - e2 must be empty
# - e3 and e4 must have one value corresponding
# to the non-fixed coefficient
#----------------------------------------------------
e1$info.Matrix
e2$info.Matrix
e3$info.Matrix
e4$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 <- btsr.sim(model= "BARFIMA", linkg = "linear",
n = 100, seed = 2021,
coefs = list(alpha = 0.2, nu = 20))
# fitting the model
f <- btsr.fit(model = "BARFIMA", yt = y, report = TRUE,
start = list(alpha = 0.5, nu = 10),
linkg = "linear", d = FALSE)