optimize_model.bgmfit: Optimize SITAR model

In bsitar: Bayesian Super Imposition by Translation and Rotation Growth Curve Analysis

Optimize SITAR model

Description

Select the best fitting SITAR model that involves choosing the optimum degrees of freedom (df) for the natural cubic-spline curve and the appropriate transformations of the predictor x and response 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 = c("beta", "sd", "rsd", "sigma", "dpar"),
  transform_beta_coef = c("b", "c", "d"),
  transform_sd_coef = c("b", "c", "d"),
  exclude_default_funs = TRUE,
  add_fit_criteria = NULL,
  add_bayes_R = NULL,
  byresp = 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 to be used in estimation. If NULL (default), the newdata is retrieved from the model.
optimize_df	A list of integers specifying the degree of freedom (df) values to be optimized. If NULL (default), the df is taken from the original model. For optimization over different df, say for example df 4 and df 5, the corresponding code is optimize_df = list(4,5). For univariate_by and multivariate models, optimize_df can be a single integer (e.g., optimize_df = 4) or a list (e.g., optimize_df = list(4,5)), or a a list of lists. As an example, consider optimization over df 4 and df 5 for the first sub model, and df 5 and df 6 for the second sub model, the corresponding code is optimize_df = list(list(4,5), list(5,6)).
optimize_x	A vector specifying the transformations for the predictor variable (i.e., x). The options available are NULL, 'log', 'sqrt', or their combinations. Note that user need not to enclose these options in a single or double quotes as they are take care of internally. The default setting is to explore all possible combination i.e., optimize_x = list(NULL, log, sqrt). Similar to the optimize_df, user can specify different optimize_x for univariate_by and multivariate sub models.
optimize_y	A vector specifying the transformations of the the response variable (i.e., y). The approach and options available for optimize_y are same as described above for the optimize_x.
transform_prior_class	A character vector (default NULL) specifying the transformations of location-scale based priors such as normal() when response variable (i.e., y) is 'log' or 'sqrt' transformed. The prior type that could be transformed are 'beta', 'sd', 'rsd', 'sigma' and 'dpar'. Currently it is available only for 'log' transformed y. Each prior type (i.e., 'beta', 'sd', 'rsd', 'sigma', 'dpar') specified via transform_prior_class is log transformed 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 the log_location and log_scale are the equivalent parameters on the log scale. For more details, see a_prior_beta argument in bsitar() function. Note that transform_prior_class is used as an experiment and therefore results may not be what user intended. Thus we recommend to explicitly set the desired prior and not to use transform_prior_class.
transform_beta_coef	A character vector (default NULL) specifying the transformations of location-scale based priors for specific regression coefficient(s) when response variable (i.e., y) is 'log' or 'sqrt' transformed. The coefficient that could be transformed are 'a', 'b', 'c', 'd' and 's'. The default is transform_beta_coef = c('b',' b', 'd') which implies that parameters 'a', 'a' and 'a' will be transformed whereas parameter 'a' will be left unchanged because default prior for parameter 'a' is based on outcome y itself (e.g., a_prior_beta = normal(ymean, ysd)) which has be transformed. However, we strongly suggest that user explicitly set the desired prior and not to rely on transform_beta_coef because it is included on experimental basis. See transform_prior_class for details.
transform_sd_coef	A character vector (default NULL) specifying the transformations of location-scale based priors for specific group level coefficient(s) when response variable (i.e., y) is 'log' or 'sqrt' transformed. The coefficient that could be transformed are 'a', 'b', 'c', 'd' and 's'. The default is transform_beta_coef = c('b',' b', 'd'). See transform_prior_class and transform_beta_coef for details.
exclude_default_funs	A logical to indicate 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 the optimize_x and optimize_y. From example, if original model is fit with xvar = log and yvar = NULL, then optimize_x is translated into optimize_x = list(NULL, sqrt), and similarly 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. Options available are 'loo' and 'waic'. Please see brms::add_criterion() for details.
add_bayes_R	An optional argument (default NULL) to indicate whether to add Bayesian R square to the returned model fit. To estimate and add bayes_R2 to the model fit, the argument add_bayes_R is set as add_bayes_R = 'bayes_R2'.
byresp	A logical (default FALSE) to indicate if response wise fit criteria to be calculated. This argument is evaluated only for the multivariate model in which user can select whether to get joint calculation of point wise log likelihood (byresp = FALSE) or response specific (byresp = TRUE). For, univariate_by model, the only option available is to calculate separate point wise log likelihood for each sub-model, i.e., byresp = TRUE.
digits	An integer (default 2) to set the decimal argument for the base::round() function.
cores	The number of cores to used in parallel processing (default 1). The argument cores is passed to the brms::add_criterion().
verbose	An optional argument (logical, default FALSE) to indicate whether to print information collected during setting up the object(s).
expose_function	An optional logical argument to indicate whether to expose Stan functions (default FALSE). Note that if user has already exposed Stan functions during model fit by setting expose_function = TRUE in the bsitar(), then those exposed functions are saved and can be used during post processing of the posterior draws and therefore expose_function is by default set as FALSE in all post processing functions except optimize_model(). For optimize_model(), the default setting is expose_function = NULL. The reason is that each optimized model has different Stan function and therefore it need to be re exposed and saved. The expose_function = NULL implies that the setting for expose_function is taken from the original model fit. Note that expose_function must be set to TRUE when adding fit criteria and/or bayes_R2 during model optimization.
usesavedfuns	A logical (default NULL) to indicate whether to use the already exposed and saved Stan functions. Depending on whether the user have exposed Stan functions within the bsitar() call via expose_functions argument in the bsitar(), the usesavedfuns is automatically set to TRUE (if expose_functions = TRUE) or FALSE (if expose_functions = FALSE). Therefore, manual setting of usesavedfuns as TRUE/FALSE is rarely needed. This is for internal purposes only and mainly used during the testing of the functions and therefore should not be used by users as it might lead to unreliable estimates.
clearenvfuns	A logical to indicate whether to clear the exposed function from the environment (TRUE) or not (FALSE). If NULL (default), then clearenvfuns is set as TRUE when usesavedfuns is TRUE, and FALSE if usesavedfuns is FALSE.
envir	Environment used for function evaluation. The default is NULL which will set parent.frame() as default environment. Note that since most of post processing functions are based on brms, the functions needed for evaluation should be in the .GlobalEnv. Therefore, it is strongly recommended to set envir = globalenv() (or envir = .GlobalEnv). This is particularly true for the derivatives such as velocity curve.
...	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 and/or add_bayes_R are specified.

Author(s)

Satpal Sandhu [e-mail]

See Also

brms::add_criterion()

Examples

# Fit Bayesian SITAR model 

# To avoid mode 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 model fit object 'berkeley_exfit' exists
 berkeley_exfit <- getNsObject(berkeley_exfit)

model <- berkeley_exfit

# Below example shows dummy call to optimization to save time. 
# Note that in case degree of freedom and both  optimize_x and optimize_y are
# NULL (i.e., nothing to optimize), the original model object is returned.   
# To explicitly get this information whether model is being optimized or not, 
# user can set verbose = TRUE. The verbose = TRUE also useful in getting the
# information regarding what all arguments have been changed as compared to
# the original model.

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

bsitar documentation built on May 29, 2024, 7:33 a.m.