optimize_model.bgmfit {bsitar}R Documentation

Optimize SITAR Model

Description

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.

Usage

## S3 method for class 'bgmfit'
optimize_model(
  model,
  newdata = NULL,
  optimize_df = NULL,
  optimize_x = list(NULL, log, sqrt),
  optimize_y = list(NULL, log, sqrt),
  transform_prior_class = NULL,
  transform_beta_coef = NULL,
  transform_sd_coef = NULL,
  exclude_default_funs = TRUE,
  add_fit_criteria = NULL,
  byresp = FALSE,
  model_name = NULL,
  overwrite = FALSE,
  file = NULL,
  force_save = FALSE,
  save_each = FALSE,
  digits = 2,
  cores = 1,
  verbose = FALSE,
  expose_function = NULL,
  usesavedfuns = FALSE,
  clearenvfuns = NULL,
  envir = NULL,
  ...
)

optimize_model(model, ...)

Arguments

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.

Value

A list containing the optimized models of class bgmfit, and the the summary statistics if add_fit_criteria are specified.

Author(s)

Satpal Sandhu satpal.sandhu@bristol.ac.uk

See Also

brms::add_criterion()

Examples




# Fit Bayesian SITAR model 

# To avoid model estimation, which takes time, the Bayesian SITAR model fit  
# to the 'berkeley_exdata' has been saved as an example fit ('berkeley_exfit').
# See 'bsitar' function for details on 'berkeley_exdata' and 'berkeley_exfit'.

# Check and confirm whether the model fit object 'berkeley_exfit' exists
 berkeley_exfit <- getNsObject(berkeley_exfit)

model <- berkeley_exfit

# The following example shows a dummy call for optimization to save time. 
# Note that if the degree of freedom, and both the \code{optimize_x} and 
# \code{optimize_y} are \code{NULL} (i.e., nothing to optimize), the original 
# model object is returned.   
# To explicitly check whether the model is being optimized or not, 
# the user can set \code{verbose = TRUE}. This is useful for getting
# information about what arguments have changed compared to the 
# original model.

model2 <- optimize_model(model, 
  optimize_df = NULL, 
  optimize_x = NULL, 
  optimize_y = NULL,
  verbose = TRUE)




[Package bsitar version 0.3.2 Index]