bamlss()
is a wrapper function that parses the data
and the model formula
, or
extended bamlss.formula
, as well as the bamlss.family
into a bamlss.frame
. The bamlss.frame
then holds all model
matrices and information that is needed for setting up estimation engines.
The model matrices are based on mgcv
infrastructures, i.e.,
smooth terms are constructed using smooth.construct
and
smoothCon
. Therefore, all mgcv
model term constructors like
s
, te
, t2
and ti
can be used. Identifiability conditions are imposed using function gam.side
. After the bamlss.frame
is set up function bamlss()
applies optimizer
and/or sampling functions. These functions can also be provided by the user. See the details
below on how to create new engines to be used with function bamlss()
. Finally, the estimated parameters and/or samples are used to create model output results like
summary statistics or effect plots. The computation of results may also be controlled by the user.bamlss(formula, family = "gaussian", data = NULL,
start = NULL, knots = NULL, weights = NULL,
subset = NULL, offset = NULL, na.action = na.omit,
contrasts = NULL, reference = NULL, transform = NULL,
optimizer = NULL, sampler = NULL, samplestats = NULL,
results = NULL, cores = NULL, sleep = NULL,
combine = TRUE, model = TRUE, x = TRUE,
light = FALSE, ...)
formula
can be a
list
of formulas where each list entry specifies the details of one parameter
of the modeled response distribution, see bamlss.formula
. For incorporating
smooth terms, all model term constructors implemented in mgcv
such as
s
, te
and ti
can be used, amongst others.bamlss.family
object, specifying the details of the modeled
distribution such as the parameter names, the density function, link functions, etc.
Can be a character without the "_bamlss"
extension of the
bamlss.family
name.data.frame
or list
containing the model
response variable(s) and covariates specified in the formula
.
By default the variables are taken from environment(formula)
:
typically the environment from which bamlss
is called.optimizer
and/or sampler
function. For a possible naming convention for the parameters see
function parameters
, but this is not restrictive and engine specific.gam
.contrasts.arg
of
model.matrix.default
.character
specifying a reference category, e.g., when
fitting a multinomial model.bamlss.frame
.
See, e.g., function randomize
and bamlss.engine.setup
.bfit
. If set to FALSE
, no optimizer function will be used.samplestats
is used. If set to FALSE
, no samplestats
function
will be used. Note that this option is crucial for very large datasets, as computing
statistics from samples this way may be very time consuming!link{results.bamlss.default}
. If set FALSE
no results
function will be used.mclapply
of the parallel
package.mcmc
matrix?FALSE
the model frame used for modeling is not part of the
return value.FALSE
the model matrices are not part of the return value.light = TRUE
the returned
object will not contain the model.frame and design and penalty matrices are deleted.transformer
, optimizer
, sampler
,
results
and samplestats
function."bamlss"
. The object is in principle only a slight extension
of a bamlss.frame
, i.e., if an optimizer
is applied it will hold the
estimated parameters in an additional element named "parameters"
. If a sampler function
is applied it will additionally hold the samples in an element named "samples"
.
The same mechanism is used for results
function. If the optimizer
function computes additional output next to the parameters, this will
be saved in an element named "model.stats"
. If a samplestats
function is applied,
the output will also be saved in the "model.stats"
element. Additionally, all functions that are called are saved as attribute "functions"
in the
returned object.data
, the formula
or the extended
bamlss.formula
as well as the bamlss.family
into a model frame
like object, the bamlss.frame
. This object holds all necessary model matrices
and information that is needed for subsequent model fitting engines. Per default,
all package mgcv
smooth term constructor functions like
s
, te
, t2
and
ti
can be used (see also function smooth.construct
),
however, even special user defined constructors can be included, see the manual of
bamlss.frame
.
bamlss.frame
can be transformed, e.g., if a mixed
model representation of smooth terms is needed, see function randomize
.
optimizer(x, y, family, start, weights, offset, ...)
Internally, function bamlss()
will send the x
object that holds all
model matrices, the response y
object, the family
object, start
ing
values for the parameters, possible weights
and offset
s of the created
bamlss.frame
to the
optimizer function (see the manual of bamlss.frame
for more details on the
x
, y
and other objects). The job of the optimizer is to return a named numeric
vector of optimum parameters. The names of the parameters should be such that they can be
uniquely mapped to the corresponding model matrices in x
. See function
parameters
for more details on parameter names. The default optimizer function
is bfit
. The optimizer can return more information than only the optimum
parameters. It is possible to return a list, the convention here is that an element named
"parameters"
then holds the named vector of estimated parameters. Possible other return
values could be fitted values, the Hessian matrix, information criteria or information
about convergence of the algorithm, etc. Note that the parameters are simply added to the
bamlss.frame
in an (list) entry named parameters
.
sampler
function is started. The arguments of such
sampler functions are the same as for the optimizer
functions sampler(x, y, family, start, weights, offset, ...)
Sampler functions must return a matrix of samples, each row represents one iteration and the matrix
can be coerced to mcmc
objects. The function may return a list of samples,
e.g., if multiple chains are returned each list entry then holds one sample matrix of
one chain. The column names of the sample matrix should be the same as the names of estimated
parameters. For a possible naming convention see function parameters
, which
ensures unique mapping of samples with the model matrices in the x
object of the
bamlss.frame
. The samples are added to the bamlss.frame
in an (list) entry named samples
.
samplestats
function is applied. This function can compute any quantity
from the samples and the x
object, the arguments of such functions are samplestats(samples, x, y, family, ...)
where argument samples
are the samples returned from the sampler
function,
and x
, y
and family
are the same objects as passed to the optimizer
and or sampler functions. For example, the default function in bamlss()
for this task
is also called samplestats
and returns the mean of the log-likelihood and the
log-posterior computed of all samples, as well as the DIC.
results
function. The arguments of such results
functions are results(bamlss.frame, ...)
here, the full bamlss.frame
including possible parameters
and
samples
is passed to the function within bamlss()
. The default function
for this task is results.bamlss.default
which returns an object of class
"bamlss.results"
for which generic plotting functions are and a summary
function is provided. Hence, the user can control the output of the model, the plotting
and summary statistics, too.
transform()
, optimizer()
, sampler()
, samplestats()
and results()
can be provided from the bamlss.family
object, e.g.,
if a bamlss.family
object has an element named "optimizer"
, which
represents a valid optimizer function such as bfit
, exactly this optimizer
function will be used as a default when using the family.bamlss.frame
, family.bamlss
, bamlss.formula
,
randomize
, bamlss.engine.setup
,
bfit
, GMCMC
, continue
,
coef.bamlss
, parameters
, predict.bamlss
,
plot.bamlss
## Not run: ------------------------------------
# ## Simulated data example.
# d <- GAMart()
# f <- num ~ s(x1) + s(x2) + s(x3) + te(lon, lat)
# b <- bamlss(f, data = d)
# summary(b)
# plot(b)
# plot(b, which = 3:4)
# plot(b, which = "samples")
#
# ## Use of optimizer and sampler functions:
# ## * first run optimizer,
# b1 <- bamlss(f, data = d, optimizer = bfit, sampler = FALSE)
# print(b1)
# summary(b1)
#
# ## * afterwards, start sampler with staring values,
# b2 <- bamlss(f, data = d, start = coef(b1), optimizer = FALSE, sampler = GMCMC)
# print(b2)
# summary(b2)
#
# ## Continue sampling.
# b3 <- continue(b2, n.iter = 12000, burnin = 0, thin = 10)
# plot(b3, which = "samples")
# plot(b3, which = "max-acf")
# plot(b3, which = "max-acf", burnin = 500, thin = 4)
## ---------------------------------------------
Run the code above in your browser using DataLab