The optimization process for selecting the best-fitting SITAR
model involves choosing the optimal degrees of freedom (df
) for the
natural cubic spline curve, as well as determining the appropriate
transformations for the predictor (x
) and/or outcome (y
)
variables.
model |
An object of class bgmfit .
|
newdata |
An optional data frame for estimation. If NULL
(default), newdata is retrieved from the model .
|
optimize_df |
A list of integers specifying the degrees of freedom
(df ) values to be optimized. If NULL (default), the df
is taken from the original model. To optimize over different df
values, for example, df 4 and df 5, the corresponding code
would be optimize_df = list(4, 5) . For univariate_by and
multivariate models, optimize_df can be a single integer
(e.g., optimize_df = 4 ), a list (e.g., optimize_df = list(4,
5) ), or a list of lists. For instance, to optimize over df 4 and
df 5 for the first submodel, and df 5 and df 6 for the
second submodel, the corresponding code would be optimize_df =
list(list(4, 5), list(5, 6)) .
|
optimize_x |
A list specifying the transformations for the predictor
variable (i.e., x ). The available options are NULL ,
'log' , 'sqrt' , or their combinations. Note that the user need
not enclose these options in single or double quotes, as they are handled
internally. The default setting explores all possible combinations, i.e.,
optimize_x = list(NULL, 'log', 'sqrt') . Similar to
optimize_df , the user can specify different optimize_x values
for univariate_by and multivariate submodels. Additionally,
it is possible to pass any primitive function instead of fixed functions
like log and sqrt . This greatly enhances the flexibility of
model optimization by allowing the search for a wide range of x
transformations, such as optimize_x = list(function(x) log(x +
3/4)) .
|
optimize_y |
A list specifying the transformations of the response
variable (i.e., y ). The approach and available options for
optimize_y are the same as described above for optimize_x .
|
transform_prior_class |
A character vector (default NULL )
specifying the parameter classes for which transformations of
user-specified priors should be performed. The prior classes that can be
transformed are 'beta' , 'sd' , 'rsd' , 'sigma' ,
and 'dpar' , and they can be specified as:
transform_prior_class = c('beta', 'sd', 'rsd', 'sigma', 'dpar') .
Note that transformations can only be applied to location-scale based
priors (such as normal() ). For example, the 'log'
transformation of a prior is performed as follows:
log_location = log(location / sqrt(scale^2 / location^2 + 1)) ,
log_scale = sqrt(log(scale^2 / location^2 + 1)) , where
location and scale are the original parameters supplied by
the user, and log_location and log_scale are the equivalent
parameters on the log scale. Note that transform_prior_class is used
on an experimental basis, and therefore the results may not be as intended.
We recommend explicitly setting the desired prior for the y scale.
|
transform_beta_coef |
A character vector (default NULL )
specifying the regression coefficients for which transformations are
applied. The coefficients that can be transformed are 'a' ,
'b' , 'c' , 'd' , and 's' . The default is
transform_beta_coef = c('b', 'c', 'd') , which implies that the
parameters 'b' , 'c' , and 'd' will be transformed,
while parameter 'a' will be left unchanged because the default prior
for parameter 'a' is based on the outcome y scale itself
(e.g., a_prior_beta = normal(ymean, ysd) ), which gets transformed
automatically. Note that transform_beta_coef is ignored when
transform_prior_class = NULL .
|
transform_sd_coef |
A character vector (default NULL ) specifying
the sd parameters for which transformations are applied. The
coefficients that can be transformed are 'a' , 'b' ,
'c' , 'd' , and 's' . The default is
transform_sd_coef = c('b', 'c', 'd') , which implies that the
parameters 'b' , 'c' , and 'd' will be transformed,
while parameter 'a' will be left unchanged because the default prior
for parameter 'a' is based on the outcome y scale itself
(e.g., a_prior_beta = normal(ymean, ysd) ), which gets transformed
automatically. Note that transform_sd_coef is ignored when
transform_prior_class = NULL .
|
exclude_default_funs |
A logical indicating whether transformations for
(x and y ) variables used in the original model fit should be
excluded. If TRUE (default), the transformations specified for the
x and y variables in the original model fit are excluded from
optimize_x and optimize_y . For example, if the original model
is fit with xvar = log and yvar = NULL , then
optimize_x is translated into optimize_x = list(NULL, sqrt) ,
and optimize_y is reset as optimize_y = list(log, sqrt) .
|
add_fit_criteria |
An optional argument (default NULL ) to
indicate whether to add fit criteria to the returned model fit. Available
options are 'loo' , 'waic' , and 'bayes_R2' . Please see
[brms::add_criterion()] for details.
|
byresp |
A logical (default FALSE ) indicating whether
response-wise fit criteria should be calculated. This argument is evaluated
only for the multivariate model, where the user can select whether
to get a joint calculation of point-wise log likelihood (byresp =
FALSE ) or response-specific calculations (byresp = TRUE ). For the
univariate_by model, the only available option is to calculate
separate point-wise log likelihood for each submodel, i.e., byresp =
TRUE .
|
model_name |
Optional name of the model. If NULL
(the default) the name is taken from the call to x .
|
overwrite |
Logical; Indicates if already stored fit
indices should be overwritten. Defaults to FALSE .
Setting it to TRUE is useful for example when changing
additional arguments of an already stored criterion.
|
file |
Either NULL or a character string. In the latter case, the
fitted model object including the newly added criterion values is saved via
saveRDS in a file named after the string supplied in
file . The .rds extension is added automatically. If x
was already stored in a file before, the file name will be reused
automatically (with a message) unless overwritten by file . In any
case, file only applies if new criteria were actually added via
add_criterion or if force_save was set to TRUE .
|
force_save |
Logical; only relevant if file is specified and
ignored otherwise. If TRUE , the fitted model object will be saved
regardless of whether new criteria were added via add_criterion .
|
save_each |
A logical (default FALSE ) indicating whether to save
each model (as a .rds file) when running the loop. Note that the
user can also specify save_each as a named list to pass the
following information when saving each model:
'prefix' a character string (default NULL ),
'suffix' a character string (default NULL ),
'extension' a character string, either .rds or
.RData (default .rds ),
'compress' a character string, either 'xz' , 'gzip' , or
'bzip2' (default 'xz' ). These options are set as follows:
save_each = list(prefix = '', suffix = '', extension = 'rds',
compress = 'xz') .
|
digits |
An integer (default 2 ) to set the decimal places for
rounding the results using the base::round() function.
|
cores |
The number of cores to use in parallel processing (default
1 ). The argument cores is passed to
[brms::add_criterion()] .
|
verbose |
A logical argument (default FALSE ) to specify whether
to print information collected during the setup of the object(s).
|
expose_function |
A logical argument (default FALSE ) to indicate
whether Stan functions should be exposed. If TRUE , any Stan
functions exposed during the model fit using expose_function = TRUE
in the bsitar() function are saved and can be used in post-processing. By
default, expose_function = FALSE in post-processing functions,
except in optimize_model() where it is set to NULL . If
NULL , the setting is inherited from the original model fit. It must
be set to TRUE when adding fit criteria or bayes_R2
during model optimization.
|
usesavedfuns |
A logical value (default NULL ) indicating whether
to use already exposed and saved Stan functions. This is typically set
automatically based on the expose_functions argument from the
bsitar() call. Manual specification of usesavedfuns is rarely
needed and is intended for internal testing, as improper use can lead to
unreliable estimates.
|
clearenvfuns |
A logical value indicating whether to clear the exposed
Stan functions from the environment (TRUE ) or not (FALSE ). If
NULL , clearenvfuns is set based on the value of
usesavedfuns : TRUE if usesavedfuns = TRUE , or
FALSE if usesavedfuns = FALSE .
|
envir |
The environment used for function evaluation. The default is
NULL , which sets the environment to parent.frame() . Since
most post-processing functions rely on brms, it is recommended to set
envir = globalenv() or envir = .GlobalEnv , especially for
derivatives like velocity curves.
|
... |
Other arguments passed to update_model .
|