Package 'bsitar'

An object of class bgmfit representing the model to which the fit criteria will be added.

Names of model fit criteria to compute. Currently supported are "loo", "waic", "kfold", "loo_subsample", "bayes_R2" (Bayesian R-squared), "loo_R2" (LOO-adjusted R-squared), and "marglik" (log marginal likelihood).

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

A flag indicating if the information criteria of the models should be compared to each other via loo_compare.

A flag indicating whether to compute the full log-likelihood matrix at once or separately for each observation. The latter approach is usually considerably slower but requires much less working memory. Accordingly, if one runs into memory issues, pointwise = TRUE is the way to go.

If NULL (the default) will use model names derived from deparsing the call. Otherwise will use the passed values as model names.

A logical value indicating whether only the estimate should be computed (TRUE), or whether the estimate along with SE and CI should be returned (FALSE, default). Setting summary to FALSE will increase computation time. Note that summary = FALSE is required to obtain correct estimates when re_formula = NULL.

A logical value to specify the summary options. If FALSE (default), the mean is used as the measure of central tendency and the standard deviation as the measure of variability. If TRUE, the median and median absolute deviation (MAD) are applied instead. Ignored if summary is FALSE.

The percentiles to be computed by the quantile function. Only used if summary is TRUE.

An optional data frame for estimation. If NULL (default), newdata is retrieved from the model.

A character string (default NULL) to specify the response variable when processing posterior draws for univariate_by and multivariate models. See bsitar() for details on univariate_by and multivariate models.

The number of cores to be used for parallel computations if future = TRUE. On non-Windows systems, this argument can be set globally via the mc.cores option. By default, NULL, the number of cores is automatically determined using future::availableCores(), and it will use the maximum number of cores available minus one (i.e., future::availableCores() - 1).

A logical value specifying whether to estimate the velocity curve from the derivative function or by differentiating the distance curve. Set deriv_model = TRUE for functions that require the velocity curve, such as growthparameters() and plot_curves(). Set it to NULL for functions that use the distance curve (i.e., fitted values), such as loo_validation() and plot_ppc().

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

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.

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.

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.

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.

Additional arguments passed to the brms::fitted.brmsfit() and brms::predict() functions.

Predictor variable (typically age in years). For a univariate model, x is a single variable. For univariate_by and multivariate models, x can either be the same for all sub-models, or different for each sub-model. For example, when fitting a bivariate model, x = list(x1, x2) specifies that x1 is the predictor variable for the first sub-model, and x2 is the predictor for the second sub-model. To use x1 as a common predictor variable for both sub-models, you can specify x = list(x1) or simply x = x1.

Response variable (e.g., repeated height measurements). For univariate and univariate_by models, y is specified as a single variable. In the case of a univariate_by model, the response vector for each sub-model is created and named internally based on the factor levels of the variable used to define the sub-model. For example, specifying univariate_by = sex creates response vectors Female and Male when Female is the first level and Male is the second level of the sex variable. In a multivariate model, the response variables are provided as a list, such as y = list(y1, y2), where y1 is the response variable for the first sub-model, and y2 is the response for the second sub-model. Note that for the multivariate model, the data are not stacked; instead, response vectors are separate variables in the data and must be of equal length.

A factor variable uniquely identifying the groups (e.g., individuals) in the data frame. For univariate_by and multivariate models, the id can be the same (typically) for all sub-models, or different for each sub-model (see the x argument for details on setting different arguments for sub-models).

A data frame containing variables such as x, y, id, etc.

Degrees of freedom for the natural cubic spline design matrix (default 4). The df is used internally to construct knots (quantiles of the x distribution) for the spline design matrix. For univariate_by and multivariate models, the df can be the same across sub-models (e.g., df = 4) or different for each sub-model, such as df = list(4, 5), where df = 4 applies to the first sub-model and df = 5 applies to the second sub-model.

A numeric vector specifying the knots for the natural cubic spline design matrix (default NULL). Note that you cannot specify both df and knots at the same time, nor can both be NULL. In other words, either df or knots must be specified. Like df, the knots can be the same for all sub-models, or different for each sub-model when fitting univariate_by and multivariate models (see df for details).

A character string specifying the fixed effects structure (default 'a+b+c'). For univariate_by and multivariate models, you can specify different fixed effect structures for each sub-model. For example, fixed = list('a+b+c', 'a+b') implies that the fixed effects structure for the first sub-model is 'a+b+c', and for the second sub-model it is 'a+b'.

A character string specifying the random effects structure (default 'a+b+c'). The approach to setting the random is the same as for the fixed effects structure (see fixed).

An optional character string or numeric value to set the origin of the predictor variable, x (i.e., centering of x). Available options include:

• 'mean': The mean of x (i.e., mean(x)),

• 'max': The maximum value of x (i.e., max(x)),

• 'min': The minimum value of x (i.e., min(x)),

• 'apv': Age at peak velocity estimated from the velocity curve derived from a simple linear model fit to the data,

• Any real number (e.g., xoffset = 12). The default is xoffset = 'mean'.

For univariate_by and multivariate models, xoffset can be the same or different for each sub-model (see x for details on setting different arguments for sub-models). If xoffset is a numeric value, it will be transformed internally (e.g., log or sqrt) depending on the xfun argument. Similarly, when xoffset is 'mean', 'min', or 'max', these values are calculated after applying the log or sqrt transformation to x.

An optional character string or numeric value to set the origin of the fixed effect parameter b. The bstart argument is used to establish the location parameter for location-scale based priors (such as normal()) via the b_prior_beta argument, and/or the initial value via the b_init_beta argument. The available options for bstart are:

• 'mean': The mean of x (i.e., mean(x)),

• 'min': The minimum value of x (i.e., min(x)),

• 'max': The maximum value of x (i.e., max(x)),

• 'apv': Age at peak velocity estimated from the velocity curve derived from a simple linear model fit to the data,

• Any real number (e.g., bstart = 12).

The default is bstart = 'xoffset' (i.e., the same value as xoffset). For univariate_by and multivariate models, bstart can be the same for all sub-models (typically), or different for each sub-model (refer to x for details on setting different arguments for sub-models).

An optional character string or numeric value to set the origin of the fixed effect parameter c. The cstart argument is used to establish the location parameter for location-scale based priors (such as normal()) via the c_prior_beta argument, and/or the initial value via the c_init_beta argument. The available options for cstart are:

• 'pv': Peak velocity estimated from the velocity curve derived from the simple linear model fit to the data,

• Any real number (e.g., cstart = 1).

Note that since parameter c is estimated on the exponential scale, the cstart should be adjusted accordingly. The default cstart is '0' (i.e., cstart = '0'). For univariate_by and multivariate models, cstart can be the same for all sub-models (typically), or different for each sub-model (refer to x for details on setting different arguments for sub-models).

An optional character string specifying the transformation of the predictor variable x. The default value is NULL, indicating that no transformation is applied and the model is fit to the data with the original scale of x. The available transformation options are:

• 'log': Logarithmic transformation,

• 'sqrt': Square root transformation.

For univariate_by and multivariate models, the xfun can be the same for all sub-models (typically), or different for each sub-model (refer to x for details on setting different arguments for sub-models).

An optional character string specifying the transformation of the response variable y. The default value is NULL, indicating that no transformation is applied and the model is fit to the data with the original scale of y. The available transformation options are:

• 'log': Logarithmic transformation,

• 'sqrt': Square root transformation.

For univariate_by and multivariate models, the yfun can be the same for all sub-models (typically), or different for each sub-model (refer to x for details on setting different arguments for sub-models).

An optional real number specifying the value by which the span of the predictor variable x should be extended (default is 0.04). This extension can help in modeling edge cases. For more details, refer to the sitar package documentation. For univariate_by and multivariate models, the bound can be the same for all sub-models (typically), or different for each sub-model (refer to x for details on setting different arguments for sub-models).

A character string or a named list specifying the spline type to be used. The available options are:

• 'rcs': Constructs the spline design matrix using the truncated power basis (Harrell's method), implemented in Hmisc::rcspline.eval().

• 'nks': Implements a B-spline based natural cubic spline method, similar to splines2::nsk().

• 'nsp': Implements a B-spline based natural cubic spline method, similar to splines2::nsp(). The default is 'nsp'.

The 'rcs' method uses a truncated power basis, whereas 'nks' and 'nsp' are B-spline-based methods. Unlike splines2::nsp() and splines2::nsk(), which normalize the spline basis by default, 'nks' and 'nsp' return the non-normalized version of the spline. If normalization is desired, the user can specify normalize = TRUE in a list. For example, to use a normalized 'nsp', one can specify stype = list(type = 'nsp', normalize = TRUE).

For more details, see Hmisc::rcspline.eval(), splines2::nsk(), and splines2::nsp().

An optional character string (default NULL) specifying terms on the right-hand side of the response variable, but before the formula tilde sign ~. The terms_rhs is used when fitting a measurement error model.

For example, when fitting a model with measurement error in the response variable, the formula in brms::brmsformula() could be specified as brmsformula(y | mi(sdy) ~ ...). In this case, mi(sdy) is passed to the formula via terms_rhs = 'mi(sdy)'.

For a multivariate model, each outcome can have its own measurement error variable. For instance, the terms_rhs can be specified as a list: terms_rhs = list(mi(sdy1), mi(sdy2)).

Note that brms::brmsformula() does not allow combining mi() with the subset() formulation used in fitting univariate_by models.

Formula for the fixed effect parameter, a (default ~ 1). Users can specify different formulas when fitting univariate_by and multivariate models.

For example, a_formula = list(~1, ~1 + cov) specifies that the a_formula for the first sub-model includes only an intercept, while the second sub-model includes both an intercept and a covariate cov. The covariate(s) can be either continuous or factor variables. For factor covariates, dummy variables are created internally using stats::model.matrix().

The formula can include a combination of continuous and factor variables, as well as their interactions.

Formula for the fixed effect parameter, b (default ~ 1). See a_formula for details on how to specify the formula. The behavior and structure of b_formula are similar to a_formula.

Formula for the fixed effect parameter, c (default ~ 1). See a_formula for details on how to specify the formula. The behavior and structure of c_formula are similar to a_formula.

Formula for the fixed effect parameter, d (default ~ 1). See a_formula for details on how to specify the formula. The behavior and structure of d_formula are similar to a_formula.

Formula for the fixed effect parameter, s (default ~ 1). The s_formula sets up the spline design matrix. Typically, covariates are not included in the s_formula to limit the population curve to a single curve for the entire data. In fact, the sitar package does not provide an option to include covariates in the s_formula. However, the bsitar package allows the inclusion of covariates. In such cases, the user must justify the modeling of separate curves for each category when the covariate is a factor variable.

Formula for the random effect parameter, a (default ~ 1). Similar to a_formula, users can specify different formulas when fitting univariate_by and multivariate models. The formula can include continuous and/or factor variables, including their interactions as covariates (see a_formula for details). In addition to setting up the design matrix for the random effect parameter a, users can define the group identifier and the correlation structure for random effects using the vertical bar || notation. For example, to include only an intercept for the random effects a, b, and c, you can specify:

a_formula_gr = ~1, b_formula_gr = ~1, c_formula_gr = ~1.

To specify the group identifier (e.g., id) and an unstructured correlation structure, use the vertical bar notation:

a_formula_gr = ~ (1|i|id)
b_formula_gr = ~ (1|i|id)
c_formula_gr = ~ (1|i|id)

Here, i within the vertical bars is a placeholder, and a common identifier (e.g., i) shared across the random effect formulas will model them as unstructured correlated random effects. For more details on this vertical bar approach, please see [brms::brm()].

An alternative approach to specify the group identifier and correlation structure is through the group_by argument. To achieve the same setup as described above with the vertical bar approach, users can define the formula part as:

a_formula_gr = ~1, b_formula_gr = ~1, c_formula_gr = ~1,

and use group_by as group_by = list(groupvar = id, cor = un), where id specifies the group identifier and un sets the unstructured correlation structure. See the group_by argument for more details.

Formula for the random effect parameter, b (default ~ 1). Similar to a_formula_gr, user can specify different formulas when fitting univariate_by and multivariate models. The formula can include continuous and/or factor variable(s), including their interactions as covariates (see a_formula_gr for details). In addition to setting up the design matrix for the random effect parameter b, the user can set up the group identifier and the correlation structure for random effects via the vertical bar || approach. For example, consider only an intercept for the random effects a, b, and c specified as a_formula_gr = ~1, b_formula_gr = ~1 and c_formula_gr = ~1. To specify the group identifier (e.g., id) and an unstructured correlation structure, the formula argument can be specified as:
a_formula_gr = ~ (1|i|id)
b_formula_gr = ~ (1|i|id)
c_formula_gr = ~ (1|i|id)
where i within the vertical bars || is just a placeholder. A common identifier (i.e., i) shared across random effect formulas are modeled as unstructured correlated. For more details on the vertical bar approach, please see brms::brm().

Formula for the random effect parameter, c (default ~ 1). See b_formula_gr for details.

Formula for the random effect parameter, d (default ~ 1). See b_formula_gr for details.

Formula for the random effect parameter, a (default NULL), used when fitting a hierarchical model with three or more levels of hierarchy. For example, a model applied to data that includes repeated measurements (level 1) on individuals (level 2), which are further nested within growth studies (level 3).

For a_formula_gr_str argument, only the vertical bar approach (see a_formula_gr) can be used to define the group identifiers and correlation structure. An example of setting up a formula for a three-level model with random effect parameters a, b, and c is as follows:
a_formula_gr_str = ~ (1|i|id:study) + (1|i2|study)
b_formula_gr_str = ~ (1|i|id:study) + (1|i2|study)
c_formula_gr_str = ~ (1|i|id:study) + (1|i2|study)

In this example, |i| and |i2| set up unstructured correlation structures for the random effects at the individual and study levels, respectively. Note that |i| and |i2| must be distinct, as random effect parameters cannot be correlated across different levels of hierarchy.

Additionally, users can specify models with any number of hierarchical levels and include covariates in the random effect formula.

Formula for the random effect parameter, b (default NULL), used when fitting a hierarchical model with three or more levels of hierarchy. For details, see a_formula_gr_str.

Formula for the random effect parameter, c (default NULL), used when fitting a hierarchical model with three or more levels of hierarchy. For details, see a_formula_gr_str.

Formula for the random effect parameter, d (default NULL), used when fitting a hierarchical model with three or more levels of hierarchy. For details, see a_formula_gr_str.

A logical indicator to adjust the scale of the predictor variable x when fitting the model with the random effect parameter d. The coefficient of parameter d is estimated as a linear function of x, i.e., d * x. If FALSE (default), the original x is used. When d_adjusted = TRUE, x is adjusted for the timing (b) and intensity (c) parameters as x - b) * exp(c) i.e., d * ((x-b)*exp(c)). The adjusted scale of x reflects individual developmental age rather than chronological age. This makes d more sensitive to the timing of puberty in individuals. See sitar::sitar() function for details.

Formula for the fixed effect distributional parameter, sigma. The sigma_formula sets up the fixed effect design matrix, which may include continuous and/or factor variables (and their interactions) as covariates for the distributional parameter. In other words, setting up the covariates for sigma_formula follows the same approach as for other fixed parameters, such as a (see a_formula for details). Note that sigma_formula estimates the sigma parameter on the log scale. By default, sigma_formula is NULL, as the brms::brm() function itself models sigma as a residual standard deviation (RSD) parameter on the link scale. The sigma_formula, along with the arguments sigma_formula_gr and sigma_formula_gr_str, allows sigma to be estimated as a random effect. The setup for fixed and random effects for sigma is similar to the approach used for other parameters such as a, b, and c.

It is important to note that an alternative way to set up the fixed effect design matrix for the distributional parameter sigma is to use the dpar_formula argument. The advantage of dpar_formula over sigma_formula is that it allows users to specify both linear and nonlinear formulations using the brms::lf() and brms::nlf() syntax. These functions offer more flexibility, such as centering the predictors and enabling or disabling cell mean centering by excluding the intercept via 0 + formulation. However, a disadvantage of the dpar_formula approach is that random effects cannot be included for sigma.

sigma_formula and dpar_formula cannot be specified together. When either sigma_formula or dpar_formula is used, the default estimation of RSD by brms::brm() is automatically turned off.

Users can specify an external function, such as poly, but only with a single argument (the predictor), i.e., poly(age). Additional arguments must be specified externally. For example, to set the degree of the polynomial to 3, a copy of the poly function can be created and modified as follows:
mypoly = poly; formals(mypoly)[['degree']] <- 3; mypoly(age).

Formula for the random effect parameter, sigma (default NULL). See a_formula_gr for details. Similar to sigma_formula, external functions such as poly can be used. For further details, please refer to the description of sigma_formula.

Formula for the random effect parameter, sigma, when fitting a hierarchical model with three or more levels of hierarchy. See a_formula_gr_str for details. As with sigma_formula, external functions such as poly can be used. For further details, please refer to the description of sigma_formula.

Formula for the random effect parameter, sigma, provided as a character string that explicitly uses the brms::nlf() and brms::lf() functions (default NULL). An example is:
nlf(sigma ~ z) + lf(z ~ 1 + age + (1 + age |55| gr(id, by = NULL))).

Another use case for sigma_formula_manual is modeling a location-scale model in the SITAR framework, where the same SITAR formula can be used to model the scale (sigma). An example is:

nlf(sigma ~ sigmaSITARFun(logage, sigmaa, sigmab, sigmac, sigmas1, sigmas2, sigmas3, sigmas4), loop = FALSE) + lf(sigmaa ~ 1 + (1 |110| gr(id, by = NULL))+(1 |330| gr(study, by = NULL))) + lf(sigmab ~ 1 + (1 |110| gr(id, by = NULL))+(1 |330| gr(study, by = NULL))) + lf(sigmac ~ 1 + (1 |110| gr(id, by = NULL))+(1 |330| gr(study, by = NULL))) + lf(sigmas1 + sigmas2 + sigmas3 + sigmas4 ~ 1).

Here, sigmaSITARFun (and all other required sub-functions) are defined through the sigmax, sigmadf, sigmaknots, sigmafixed, sigmarandom, sigmaxoffset, sigmaxfun, and sigmabound arguments. Ensure the sigma_formula_manual code matches the sigmaSITARFun function created by these arguments.

Note that for sigma_formula_manual, priors must be set up manually using the add_self_priors argument. To see which priors are required, the user can run the code with get_priors = TRUE. Additionally, no initial values are defined, so initial values for these parameters should be set to either 0 or random.

Predictor for the distributional parameter sigma. See x for details. Ignored if sigma_formula_manual = NULL.

Degree of freedom for the spline function used for sigma. See df for details. Ignored if sigma_formula_manual = NULL.

Knots for the spline function used for sigma. See knots for details. Ignored if sigma_formula_manual = NULL.

Fixed effect formula for the sigma structure. See fixed for details. Ignored if sigma_formula_manual = NULL.

Random effect formula for the sigma structure. See random for details. Ignored if sigma_formula_manual = NULL. Currently not used even when sigma_formula_manual is specified.

Offset for the x in the sigma structure. See xoffset for details. Ignored if sigma_formula_manual = NULL.

Starting value for the b parameter in the sigma structure. See bstart for details. Ignored if sigma_formula_manual = NULL. Currently not used even when sigma_formula_manual is specified.

Starting value for the c parameter in the sigma structure. See cstart for details. Ignored if sigma_formula_manual = NULL. Currently not used even when sigma_formula_manual is specified.

Transformation function for x in the sigma structure. See xfun for details. Ignored if sigma_formula_manual = NULL.

Bounds for the x in the sigma structure. See bound for details. Ignored if sigma_formula_manual = NULL.

Formula for the distributional fixed effect parameter, sigma (default NULL). See sigma_formula for details.

Formula to set up the autocorrelation structure of residuals (default NULL). Allowed autocorrelation structures include:

• autoregressive moving average (arma) of order p and q, specified as autocor_formula = ~arma(p = 1, q = 1).

• autoregressive (ar) of order p, specified as autocor_formula = ~ar(p = 1).

• moving average (ma) of order q, specified as autocor_formula = ~ma(q = 1).

• unstructured (unstr) over time (and individuals), specified as autocor_formula = ~unstr(time, id).

See brms::brm() for further details on modeling the autocorrelation structure of residuals.

Family distribution (default gaussian) and the link function (default identity). See brms::brm() for details on available distributions and link functions, and how to specify them. For univariate_by and multivariate models, the family can be the same for all sub-models (e.g., family = gaussian()) or different for each sub-model, such as family = list(gaussian(), student()), which sets gaussian distribution for the first sub-model and student_t distribution for the second. Note that the family argument is ignored if custom_family is specified (i.e., if custom_family is not NULL).

Specifies custom families (i.e., response distribution). Default is NULL. For details, see brms::custom_family(). Note that user-defined Stan functions must be exposed by setting expose_functions = TRUE.

Allows the preparation and passing of user-defined variables to be added to Stan's program blocks (default NULL). This is primarily useful when defining a custom_family. For more details on specifying stanvars, see brms::custom_family(). Note that custom_stanvars are passed directly without conducting any sanity checks.

Specify arguments for group-level random effects. The group_arg should be a named list that may include groupvar, dist, cor, and by as described below:

• groupvar specifies the subject identifier. If groupvar = NULL (default), groupvar is automatically assigned based on the id argument.

• dist specifies the distribution from which the random effects are drawn (default gaussian). Currently, gaussian is the only available distribution (as per the brms::brm() documentation).

• by can be used to estimate a separate variance-covariance structure (i.e., standard deviation and correlation parameters) for random effect parameters (default NULL). If specified, the variable used for by must be a factor variable. For example, by = 'sex' estimates separate variance-covariance structures for males and females.

• cor specifies the covariance (i.e., correlation) structure for random effect parameters. The default covariance is unstructured (cor = un) for all model types (i.e., univariate, univariate_by, and multivariate). The alternative correlation structure available for univariate and univariate_by models is diagonal, which estimates only the variance parameters (standard deviations), while setting the covariance (correlation) parameters to zero. For multivariate models, options include un, diagonal, and un_s. The un structure models a full unstructured correlation, meaning that the group-level random effects across response variables are drawn from a joint multivariate normal distribution with shared correlation parameters. The cor = diagonal option estimates only variance parameters for each sub-model, while setting the correlation parameters to zero. The cor = un_s option allows for separate estimation of unstructured variance-covariance parameters for each response variable.

Note that it is not necessary to define all or any of these options (groupvar, dist, cor, or by), as they will automatically be set to their default values if unspecified. Additionally, only groupvar from the group_arg argument is passed to the univariate_by and multivariate models, as these models have their own additional options specified via the univariate_by and multivariate arguments. Lastly, the group_arg is ignored when random effects are specified using the vertical bar || approach (see a_formula_gr for details) or when fitting a hierarchical model with three or more levels of hierarchy (see a_formula_gr_str for details).

Specify arguments for modeling distributional-level random effects for sigma. The setup for sigma_group_arg follows the same approach as described for group-level random effects (see group_arg for details).

Set up the univariate-by-subgroup model fitting (default NULL) via a named list with the following elements:

• by (optional, character string): Specifies the factor variable used to define the sub-models (default NA).

• cor (optional, character string): Defines the correlation structure. Options include un (default) for a full unstructured variance-covariance structure and diagonal for a structure with only variance parameters (i.e., standard deviations) and no covariance (i.e., correlations set to zero).

• terms (optional, character string): Specifies the method for setting up the sub-models. Options are 'subset' (default) and 'weights'. See brms::`addition-terms` for more details.

Set up the multivariate model fitting (default NULL) using a named list with the following elements:

• mvar (logical, default FALSE): Indicates whether to fit a multivariate model.

• cor (optional, character string): Specifies the correlation structure. Available options are:

  • un (default): Models a full unstructured correlation, where group-level random effects across response variables are drawn from a joint multivariate normal distribution with shared correlation parameters.

  • diagonal: Estimates only the variance parameters for each sub-model, with the correlation parameters set to zero.

  • un_s: Estimates unstructured variance-covariance parameters separately for each response variable.

• rescor (logical, default TRUE): Indicates whether to estimate the residual correlation between response variables.

Specify priors for the fixed effect parameter, a. (default normal(lm, ysd, autoscale = TRUE)). The following key points are applicable for all prior specifications. For full details, see brms::prior():

• Allowed distributions: normal, student_t, cauchy, lognormal, uniform, exponential, gamma, and inv_gamma (inverse gamma).

• For each distribution, upper and lower bounds can be set via lb and ub (default NA).

• Location-scale based distributions (such as normal, student_t, cauchy, and lognormal) have an autoscale option (default FALSE). This option multiplies the scale parameter by a numeric value. While brms typically uses a scaling factor of 1.0 or 2.5, the bsitar package allows any real number to be used (e.g., autoscale = 5.0).

• For location-scale distributions, fxl (function location) and fxs (function scale) are available to apply transformations to the location and scale parameters. For example, setting normal(2, 5, fxl = 'log', fxs = 'sqrt') translates to normal(log(2), sqrt(5)).

• fxls (function location scale) transforms both location and scale parameters. The transformation applies when both parameters are involved, as in the log-transformation for normal priors: log_location = log(location / sqrt(scale^2 / location^2 + 1)), log_scale = sqrt(log(scale^2 / location^2 + 1)). This can be specified as a character string or a list of functions.

• For strictly positive distributions like exponential, gamma, and inv_gamma, the lower bound (lb) is automatically set to zero.

• For uniform distributions, the option addrange widens the prior range symmetrically. For example, uniform(a, b, addrange = 5) adjusts the range to uniform(a-5, b+5).

• For exponential distributions, the rate parameter is evaluated as the inverse of the specified value. For instance, exponential(10.0) is internally treated as exponential(1.0 / 10.0) = exponential(0.1).

• Users do not need to specify each option explicitly, as missing options will automatically default to their respective values. For example, a_prior_beta = normal(location = 5, scale = 1) is equivalent to a_prior_beta = normal(5, 1).

• For univariate_by and multivariate models, priors can either be the same for all submodels (e.g., a_prior_beta = normal(5, 1)) or different for each submodel (e.g., a_prior_beta = list(normal(5, 1), normal(10, 5))).

• For location-scale distributions, the location parameter can be specified as the mean (ymean) or median (ymedian) of the response variable, and the scale parameter can be specified as the standard deviation (ysd) or median absolute deviation (ymad). Alternatively, coefficients from a simple linear model can be used (e.g., lm(y ~ age)).

  Example prior specifications include: a_prior_beta = normal(ymean, ysd), a_prior_beta = normal(ymedian, ymad), a_prior_beta = normal(lm, ysd).

  Note that options such as ymean, ymedian, ysd, ymad, and lm are available only for the fixed effect parameter a, not for other parameters like b, c, or d.

Specify priors for the fixed effect parameter, b. The default prior is normal(0, 1.5, autoscale = FALSE). For full details on prior specification, please refer to a_prior_beta.

• Allowed distributions include normal, student_t, cauchy, lognormal, uniform, exponential, gamma, and inv_gamma.

• You can set upper and lower bounds (lb, ub) as needed (default is NA).

• The autoscale option controls scaling of the prior’s scale parameter. By default, this is set to FALSE.

• Further customization and transformations can be applied, similar to the a_prior_beta specification.

Specify priors for the fixed effect parameter, c. The default prior is normal(0, 0.5, autoscale = FALSE). For full details on prior specification, please refer to a_prior_beta.

• Allowed distributions include normal, student_t, cauchy, lognormal, uniform, exponential, gamma, and inv_gamma.

• Upper and lower bounds (lb, ub) can be set as necessary (default is NA).

• The autoscale option is also available for scaling the prior's scale parameter (default FALSE).

• Similar to a_prior_beta, further transformations or customization can be applied.

Specify priors for the fixed effect parameter, d. The default prior is normal(0, 1.0, autoscale = FALSE). For full details on prior specification, please refer to a_prior_beta.

• Allowed distributions include normal, student_t, cauchy, lognormal, uniform, exponential, gamma, and inv_gamma.

• The option to set upper and lower bounds (lb, ub) is available (default is NA).

• autoscale allows scaling of the prior’s scale parameter and is FALSE by default.

• For more advanced transformations or customization, similar to a_prior_beta, these options are available.

Specify priors for the fixed effect parameter, s (i.e., spline coefficients). The default prior is normal(0, 'lm', autoscale = TRUE). The general approach is similar to the one described for other fixed effect parameters (see a_prior_beta for details). Key points to note:

• When using location-scale based priors with 'lm' (e.g., s_prior_beta = normal(lm, 'lm')), the location parameter is set from the spline coefficients obtained from the simple linear model fit, and the scale parameter is based on the standard deviation of the spline design matrix. The location parameter is typically set to 0 (default), and autoscale is set to TRUE.

• For location-scale based priors, the option sethp (logical, default FALSE) is available to define hierarchical priors. Setting sethp = TRUE alters the prior setup to use hierarchical priors: s ~ normal(0, 'lm') becomes s ~ normal(0, 'hp'), where 'hp' is defined as hp ~ normal(0, 'lm'). The scale for the hierarchical prior is automatically taken from the s parameter, and it can also be defined using the same sethp option. For example, s_prior_beta = normal(0, 'lm', sethp = cauchy) will result in s ~ normal(0, 'lm'), hp ~ cauchy(0, 'lm') .

• For uniform priors, you can use the option addrange to symmetrically expand the prior range.

It is observed that location-scale based prior distributions (such as normal, student_t, and cauchy) typically work well for spline coefficients.

Specify priors for the covariate(s) included in the fixed effect parameter, a (default normal(0, 5.0, autoscale = FALSE)). The approach for specifying priors is similar to a_prior_beta, with a few differences:

• The options 'ymean', 'ymedian', 'ysd', and 'ymad' are not allowed for a_cov_prior_beta.

• The 'lm' option for the location parameter allows the covariate coefficient(s) to be obtained from a simple linear model fit to the data. Note that the 'lm' option is only allowed for a_cov_prior_beta and not for covariates in other fixed or random effect parameters.

• Separate priors can be specified for submodels when fitting univariate_by and a_prior_beta models (see a_prior_beta for details).

Specify priors for the covariate(s) included in the fixed effect parameter, b (default normal(0, 1.0, autoscale = FALSE)). See a_cov_prior_beta for details.

Specify priors for the covariate(s) included in the fixed effect parameter, c (default normal(0, 0.1, autoscale = FALSE)). See a_cov_prior_beta for details.

Specify priors for the covariate(s) included in the fixed effect parameter, d (default normal(0, 1.0, autoscale = FALSE)). See a_cov_prior_beta for details.

Specify priors for the covariate(s) included in the fixed effect parameter, s (default normal(0, 10.0, autoscale = FALSE)). As described in s_formula, the SITAR model does not allow covariates in the spline design matrix. If covariates are specified (see s_formula), the approach to setting priors for the covariates in parameter s is the same as for a (see a_cov_prior_beta). For location-scale based priors, the option 'lm' sets the location parameter based on spline coefficients obtained from fitting a simple linear model to the data.

Specify priors for the random effect parameter, a. (default normal(0, 'ysd', autoscale = FALSE)). The prior is applied to the standard deviation (the square root of the variance), not the variance itself. The approach for setting the prior is similar to a_prior_beta, with the location parameter always set to zero. The lower bound is automatically set to 0 by brms::brm(). For univariate_by and multivariate models, priors can be the same or different for each submodel (see a_prior_beta).

Specify priors for the random effect parameter, b. (default normal(0, 1.0, autoscale = FALSE)). See a_prior_sd for details.

Specify priors for the random effect parameter, c. (default normal(0, 0.25, autoscale = FALSE)). See a_prior_sd for details.

Specify priors for the random effect parameter, d. (default normal(0, 1.0, autoscale = FALSE)). See a_prior_sd for details.

Specify priors for the covariate(s) included in the random effect parameter, a. (default normal(0, 5.0, autoscale = FALSE)). The approach is the same as described for a_cov_prior_beta, except that no pre-defined options (e.g., 'lm') are allowed.

Specify priors for the covariate(s) included in the random effect parameter, b. (default normal(0, 1.0, autoscale = FALSE)). See a_cov_prior_sd for details.

Specify priors for the covariate(s) included in the random effect parameter, c. (default normal(0, 0.1, autoscale = FALSE)). See a_cov_prior_sd for details.

Specify priors for the covariate(s) included in the random effect parameter, d. (default normal(0, 1.0, autoscale = FALSE)). See a_cov_prior_sd for details.

Specify priors for the random effect parameter, a, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_prior_sd.

Specify priors for the random effect parameter, b, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_prior_sd_str.

Specify priors for the random effect parameter, c, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_prior_sd_str.

Specify priors for the random effect parameter, d, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_prior_sd_str.

Specify priors for the covariate(s) included in the random effect parameter, a, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_cov_prior_sd.

Specify priors for the covariate(s) included in the random effect parameter, b, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_cov_prior_sd_str.

Specify priors for the covariate(s) included in the random effect parameter, c, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_cov_prior_sd_str.

Specify priors for the covariate(s) included in the random effect parameter, d, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). The approach is the same as described for a_cov_prior_sd_str.

Specify priors for the fixed effect distributional parameter, sigma. (default normal(0, 1.0, autoscale = FALSE)). The approach is similar to that for a_prior_beta.

Specify priors for the covariate(s) included in the fixed effect distributional parameter, sigma. (default normal(0, 0.5, autoscale = FALSE)). Follows the same approach as a_cov_prior_beta.

Specify priors for the random effect distributional parameter, sigma. (default normal(0, 0.25, autoscale = FALSE)). Same approach as a_prior_sd.

Specify priors for the covariate(s) included in the random effect distributional parameter, sigma. (default normal(0, 0.15, autoscale = FALSE)). Follows the same approach as a_cov_prior_sd.

Specify priors for the random effect distributional parameter, sigma, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). Same approach as a_prior_sd_str.

Specify priors for the covariate(s) included in the random effect distributional parameter, sigma, when fitting a hierarchical model with three or more levels of hierarchy. (default NULL). Follows the same approach as a_cov_prior_sd_str.

Specify priors for the residual standard deviation parameter sigma (default normal(0, 'ysd', autoscale = FALSE)). Evaluated when both dpar_formula and sigma_formula are NULL. For location-scale based distributions, user can specify standard deviation (ysd) or the median absolute deviation (ymad) of outcome as the scale parameter. Also, residual standard deviation from the linear mixed model (nlme::lme()) or the linear model (base::lm()) fitted to the data. These are specified as 'lme_rsd' and 'lm_rsd', respectively. Note that if nlme::lme() fails to converge, the option 'lm_rsd' is set automatically. The argument rsd_prior_sigma is evaluated when both dpar_formula and sigma_formula are set to NULL.

Specify priors for the fixed effect distributional parameter sigma (default normal(0, 'ysd', autoscale = FALSE)). Evaluated when sigma_formula is NULL. See rsd_prior_sigma for details.

Specify priors for the covariate(s) included in the fixed effect distributional parameter sigma. (default normal(0, 1.0, autoscale = FALSE)). Evaluated when sigma_formula is NULL.

Specify priors for the autocorrelation parameters when fitting a model with 'arma', 'ar', or 'ma' autocorrelation structures (see autocor_formula). The only allowed distribution is uniform, bounded between -1 and +1 (default uniform(-1, 1, autoscale = FALSE)). For the unstructured residual correlation structure, use autocor_prior_unstr_acor.

Specify priors for the autocorrelation parameters when fitting a model with the unstructured ('un') autocorrelation structure (see autocor_formula). The only allowed distribution is lkj (default lkj(1)). See gr_prior_cor for details on setting up the lkj prior.

Specify priors for the correlation parameter(s) of group-level random effects (default lkj(1)). The only allowed distribution is lkj, specified via a single parameter eta (see brms::prior() for details).

Specify priors for the correlation parameter(s) of group-level random effects when fitting a hierarchical model with three or more levels of hierarchy (default lkj(1)). Same as gr_prior_cor.

Specify priors for the correlation parameter(s) of distributional random effects sigma (default lkj(1)). The only allowed distribution is lkj (see gr_prior_cor for details). Note that brms::brm() does not currently allow different lkj priors for the group level and distributional random effects sharing the same group identifier (id).

Specify priors for the correlation parameter(s) of distributional random effects sigma when fitting a hierarchical model with three or more levels of hierarchy (default lkj(1)). Same as sigma_prior_cor.

Specify priors for the residual correlation parameter when fitting a multivariate model (default lkj(1)). The only allowed distribution is lkj (see gr_prior_cor for details).

Initial values for the sampler. Options include:

• '0': All parameters are initialized to zero.

• 'random': Stan randomly generates initial values for each parameter within a range defined by init_r (see below), or between -2 and 2 in unconstrained space if init_r = NULL.

• 'prior': Initializes parameters based on the specified prior.

• NULL (default): Initial values are provided by the corresponding init arguments defined below.

A positive real value that defines the range for the random generation of initial values (default NULL). This argument is used only when init = 'random'.

Initial values for the fixed effect parameter, a (default 'random'). Available options include:

• '0': Initializes the parameter to zero.

• 'random': Initializes with random values within a specified range.

• 'prior': Uses values drawn from the prior distribution.

• 'ymean': Initializes with the mean of the response variable.

• 'ymedian': Initializes with the median of the response variable.

• 'lm': Initializes with the coefficients from a simple linear model fitted to the data.

Note that options 'ymean', 'ymedian', and 'lm' are only available for the fixed effect parameter a. For univariate_by and multivariate models, initial values can be the same across submodels (e.g., a_init_beta = '0') or different for each submodel (e.g., list(a_init_beta = '0', a_init_beta = 'lm')).

Initial values for the fixed effect parameter, b (default 'random'). See a_init_beta for details on available options.

Initial values for the fixed effect parameter, c (default 'random'). See a_init_beta for details on available options.

Initial values for the fixed effect parameter, d (default 'random'). See a_init_beta for details on available options.

Initial values for the fixed effect parameter, s (default 'random'). Available options include:

• '0': Initializes the parameter to zero.

• 'random': Initializes with random values within a specified range.

• 'prior': Uses values drawn from the prior distribution.

• 'lm': Initializes with the coefficients from a simple linear model fitted to the data.

Initial values for the covariate(s) included in the fixed effect parameter, a (default 'random'). Available options include:

• '0': Initializes the covariates to zero.

• 'random': Initializes with random values within a specified range.

• 'prior': Uses values drawn from the prior distribution.

• 'lm': Initializes with the coefficients from a simple linear model fitted to the data.

Note that the 'lm' option is only available for a_cov_init_beta and not for covariates in other parameters such as b, c, or d.

Initial values for the covariate(s) included in the fixed effect parameter, b (default 'random'). See a_cov_init_beta for details.

Initial values for the covariate(s) included in the fixed effect parameter, c (default 'random'). See a_cov_init_beta for details.

Initial values for the covariate(s) included in the fixed effect parameter, d (default 'random'). See a_cov_init_beta for details.

Initial values for the covariate(s) included in the fixed effect parameter, s (default 'lm'). See a_cov_init_beta for details. The option 'lm' sets the spline coefficients obtained from a simple linear model fitted to the data. However, note that s_cov_init_beta serves as a placeholder and is not evaluated, as covariates are not allowed for the s parameter. For more details on covariates for s, refer to s_formula.

Initial value for the standard deviation of the group-level random effect parameter, a (default 'random'). Available options are:

• 'random': Initializes with random values within a specified range.

• 'prior': Uses values drawn from the prior distribution.

• 'ysd': Sets the standard deviation (sd) of the response variable as the initial value.

• 'ymad': Sets the median absolute deviation (mad) of the response variable as the initial value.

• 'lme_sd_a': Sets the initial value based on the standard deviation of the random intercept obtained from a linear mixed model (nlme::lme()) fitted to the data. If nlme::lme() fails to converge, the option 'lm_sd_a' will be used automatically.

• 'lm_sd_a': Sets the square root of the residual variance obtained from a simple linear model applied to the data as the initial value.

Note that the options 'ysd', 'ymad', 'lme_sd_a', and 'lm_sd_a' are available only for the random effect parameter a and not for other group-level random effects.

Additionally, when fitting univariate_by and multivariate models, the user can set the same initial values for all sub-models, or different initial values for each sub-model.

Initial value for the standard deviation of the group-level random effect parameter, b (default 'random'). Refer to a_init_sd for available options and details.

Initial value for the standard deviation of the group-level random effect parameter, c (default 'random'). Refer to a_init_sd for available options and details.

Initial value for the standard deviation of the group-level random effect parameter, d (default 'random'). Refer to a_init_sd for available options and details.

Initial values for the covariate(s) included in the random effect parameter a (default 'random'). Available options include:

• 'random': Random initialization.

• 'prior': Uses prior distribution values.

Initial values for the covariate(s) included in the random effect parameter b (default 'random'). Refer to a_cov_init_sd for available options and details.

Initial values for the covariate(s) included in the random effect parameter c (default 'random'). Refer to a_cov_init_sd for available options and details.

Initial values for the covariate(s) included in the random effect parameter d (default 'random'). Refer to a_cov_init_sd for available options and details.

Initial values for the fixed effect distributional parameter sigma (default 'random'). Available options include:

• 'random': Random initialization.

• 'prior': Uses prior distribution values.

Initial values for the covariate(s) included in the fixed effect distributional parameter sigma (default 'random'). Refer to sigma_init_beta for available options and details.

Initial value for the standard deviation of the distributional random effect parameter sigma (default 'random'). The approach is the same as described earlier for the group-level random effect parameters such as a (See a_init_sd for details).

Initial values for the covariate(s) included in the distributional random effect parameter sigma (default 'random'). The approach is the same as described for a_cov_init_sd (See a_cov_init_sd for details).

Initial values for the correlation parameters of group-level random effects parameters (default 'random'). Allowed options are:

• 'random': Random initialization.

• 'prior': Uses prior distribution values.

Initial values for the correlation parameters of distributional random effects parameter sigma (default 'random'). Allowed options are:

• 'random': Random initialization.

• 'prior': Uses prior distribution values.

Initial values for the residual standard deviation parameter, sigma (default 'random'). Options available are:

• '0': Initializes the residual standard deviation to zero.

• 'random': Random initialization of the residual standard deviation.

• 'prior': Initializes the residual standard deviation based on prior distribution values.

• 'lme_rsd': Sets the initial value based on the standard deviation of residuals obtained from the linear mixed model (nlme::lme()) fitted to the data.

• 'lm_rsd': Sets the initial value as the square root of the residual variance from the simple linear model fitted to the data.

Note that if nlme::lme() fails to converge, the option 'lm_rsd' is set automatically. The argument rsd_init_sigma is evaluated when both dpar_formula and sigma_formula are set to NULL.

Initial values for the distributional parameter sigma (default 'random'). The approach and available options are the same as described for rsd_init_sigma. This argument is evaluated only when dpar_formula is not NULL.

Initial values for the covariate(s) included in the distributional parameter sigma (default 'random'). Allowed options are '0', 'random', and 'prior'.

Initial values for the autocorrelation parameter (see autocor_formula for details). Allowed options are '0', 'random', and 'prior' (default 'random').

Initial values for unstructured residual autocorrelation parameters (default 'random'). Allowed options are '0', 'random', and 'prior'. The approach for setting initials for autocor_init_unstr_acor is the same as for gr_init_cor.

Initial values for the residual correlation parameter when fitting a multivariate model (default 'random'). Allowed options are '0', 'random', and 'prior'.

Initial values for the standardized group-level random effect parameters (default 'random'). These parameters are part of the Non-Centered Parameterization (NCP) approach used in the brms::brm().

A logical (default FALSE) to set initial values for variance (standard deviation) and covariance (correlation) parameters to zero. This allows for setting custom initial values for the fixed effects parameters while keeping the variance-covariance parameters at zero.

A proportion (between 0 and 1) to perturb the initial values for fixed effect parameters. The default is NULL, which means that the same initial values are used across all chains. A sensible option might be jitter_init_beta = 0.1, which mildly perturbs the initial values. Note that the jitter is applied as a proportion of the specified initial value, not an absolute amount. For example, if the initial value is 100, setting jitter_init_beta = 0.1 means the perturbed initial value will be within the range 90 to 110. Conversely, if the initial value is 10, the perturbed value will fall within the range 9 to 11.

A proportion (between 0 and 1) to perturb the initial values for the standard deviation of random effect parameters. The default is NULL, which means the same initial values are used across all chains. A reasonable option might be jitter_init_sd = 0.01, which was found to work well during early testing.

A proportion (between 0 and 1) to perturb the initial values for the correlation parameters of random effects. The default is NULL, which means the same initial values are used across all chains. An option of setting jitter_init_cor = 0.001 was found to be effective during early testing.

An optional argument (a named list, default NULL) that can be used to pass information to the prior arguments for each parameter (e.g., a_prior_beta). The prior_data is particularly helpful when passing a long vector or matrix as priors. These vectors and matrices can be created in the R framework and then passed using the prior_data. For example, to pass a vector of location and scale parameters when setting priors for covariate coefficients (with 10 dummy variables) included in the fixed effects parameter a, the following steps can be used:

• Create the named objects prior_a_cov_location and prior_a_cov_scale in the R environment: prior_a_cov_location <- rnorm(n = 10, mean = 0, sd = 1) prior_a_cov_scale <- rep(5, 10).

• Specify these objects in the prior_data list: prior_data = list(prior_a_cov_location = prior_a_cov_location, prior_a_cov_scale = prior_a_cov_scale).

• Use the prior_data objects to set up the priors: a_cov_prior_beta = normal(prior_a_cov_location, prior_a_cov_scale).

An optional argument (a named list, default NULL) that can be used to pass information to the initial arguments. The approach is identical to how prior_data is handled (as described above).

Specify a custom initialization object (a named list). The named list is directly passed to the init argument without verifying the dimensions or name matching. If initial values are set for some parameters via parameter-specific arguments (e.g., a_init_beta = 0), init_custom will only be passed to those parameters that do not have initialized values. To override this behavior and use all of init_custom values regardless of parameter-specific initials, set init = 'custom'.

An optional argument (logical, default FALSE) to indicate whether to print information collected during setting up the model formula priors, and initials. As an example, the user might be interested in knowing the response variables created for the sub model when fitting a univariate-by-subgroup model. This information can then be used in setting the desired order of options passed to each such model such as df, prior, initials etc.

An optional argument (logical, default FALSE) to indicate whether to expose the Stan function used in model fitting.

An optional argument (logical, default FALSE) to retrieve the Stan code (see [brms::stancode()] for details).

An optional argument (logical, default FALSE) to retrieve the Stan data (see [brms::standata()] for details).

An optional argument (logical, default FALSE) to retrieve the model formula (see [brms::brmsformula()] for details).

An optional argument (logical, default FALSE) to retrieve the Stan variables (see [brms::stanvar()] for details).

An optional argument (logical, default FALSE) to retrieve the priors (see [brms::get_prior()] for details).

An optional argument (logical, default FALSE) to retrieve the priors specified by the user.

An optional argument (logical, default FALSE) to retrieve the initial values specified by the user.

An optional argument (logical, default FALSE) to validate the specified priors (see [brms::validate_prior()] for details).

An optional argument (default NULL) to manually specify the priors. set_self_priors is passed directly to [brms::brm()] without performing any checks.

An optional argument (default NULL) to append part of the prior object. This is for internal use only.

An optional argument (default NULL) to replace part of the prior object. This is for internal use only.

An optional argument (default NULL) to replace part of the prior object. This is for internal use only.

An optional argument (default NULL) to remove outliers. This should be a named list passed directly to [sitar::velout()] and [sitar::zapvelout()] functions. This is for internal use only.

An optional formula defining variables that are unused in the model but should still be stored in the model's data frame. Useful when variables are needed during post-processing.

The number of Markov chains (default 4).

The total number of iterations per chain, including warmup (default 2000).

A positive integer specifying the number of warmup (aka burn-in) iterations. This also specifies the number of iterations used for stepsize adaptation, so warmup draws should not be used for inference. The number of warmup iterations should not exceed iter, and the default is iter/2.

A positive integer specifying the thinning interval. Set thin > 1 to save memory and computation time if iter is large. Thinning is often used in cases with high autocorrelation of MCMC draws. An indication of high autocorrelation is poor mixing of chains (i.e., high rhat values) despite the model recovering parameters well. A useful diagnostic to check for autocorrelation of MCMC draws is the mcmc_acf function from the bayesplot package.

Number of cores to be used when executing the chains in parallel. See brms::brm() for details. Unlike brms::brm(), which defaults the cores argument to cores=getOption("mc.cores", 1), the default cores in the bsitar package is cores=getOption("mc.cores", 'optimize'), which optimizes the utilization of system resources. The maximum number of cores that can be deployed is calculated as the maximum number of available cores minus 1. When the number of available cores exceeds the number of chains (see chains), then the number of cores is set equal to the number of chains.

Another option is to set cores as getOption("mc.cores", 'maximise'), which sets the number of cores to the maximum number of cores available on the system regardless of the number of chains specified. Alternatively, the user can specify cores in the same way as brms::brm() with getOption("mc.cores", 1).

These options can be set globally using options(mc.cores = x), where x can be 'optimize', 'maximise', or 1. The cores argument can also be directly specified as an integer (e.g., cores = 4).

A character string specifying the package to be used when executing the Stan model. The available options are "rstan" (the default) or "cmdstanr". The backend can also be set globally for the current R session using the "brms.backend" option. See brms::brm() for more details.

Number of threads to be used in within-chain parallelization. Note that unlike the brms::brm() which sets the threads argument as getOption("brms.threads", NULL) implying that no within-chain parallelization is used by default, the bsitar package, by default, sets threads as getOption("brms.threads", 'optimize') to utilize the available resources from the modern computing systems. The number of threads per chain is set as the maximum number of cores available minus 1. Another option is to set threads as getOption("brms.threads", 'maximise') which set the number threads per chains same as the maximum number of cores available. User can also set the threads similar to the brms i.e., getOption("brms.threads", NULL). All these three options can be set globally as options(brms.threads = x) where x can be 'optimize', 'maximise' or NULL. Alternatively, the number of threads can be set directly as threads = threading(x) where X is an integer. Other arguments that can be passed to the threads are grainsize and the static. See brms::brm() for further details on within-chain parallelization.

The platform and device IDs of the OpenCL device to use for GPU support during model fitting. If you are unsure about the IDs of your OpenCL device, c(0,0) is typically the default that should work. For more details on how to find the correct platform and device IDs, refer to brms::opencl(). This parameter can also be set globally for the current R session using the "brms.opencl" option.

Logical flag indicating whether normalization constants should be included in the Stan code (default is TRUE). If set to FALSE, normalization constants are omitted, which may increase sampling efficiency. However, this requires Stan version >= 2.25. Note that setting normalize = FALSE will disable some post-processing functions, such as brms::bridge_sampler(). This option can be controlled globally via the brms.normalize option.

A character string specifying the estimation method to use. Available options are:

• "sampling" (default): Markov Chain Monte Carlo (MCMC) method.

• "meanfield": Variational inference with independent normal distributions.

• "fullrank": Variational inference with a multivariate normal distribution.

• "fixed_param": Sampling from fixed parameter values.

This parameter can be set globally via the "brms.algorithm" option (see options for more details).

A named list to control the sampler's behavior. The default settings are the same as those in brms::brm(), with one exception: the max_treedepth has been increased from 10 to 12 to better explore the typically challenging posterior geometry in nonlinear models. However, the adapt_delta, which is often increased for nonlinear models, retains its default value of 0.8 to avoid unnecessarily increasing sampling time. For full details on control parameters and their default values, refer to brms::brm().

Logical. If TRUE, the Stan model is not created and compiled and the corresponding 'fit' slot of the brmsfit object will be empty. This is useful if you have estimated a brms-created Stan model outside of brms and want to feed it back into the package.

For internal use only.

A named list of arguments passed to the 'pathfinder' algorithm. This is used to set 'pathfinder'-based initial values for the 'MCMC' sampling. Note that 'pathfinder_args' currently only works when backend = "cmdstanr". If pathfinder_args is not NULL and the user specifies backend = "rstan", the backend will automatically be changed to cmdstanr.

A logical value (default FALSE) indicating whether to use initial values from the 'pathfinder' algorithm when fitting the final model (i.e., 'MCMC' sampling). Note that 'pathfinder_args' currently works only when backend = "cmdstanr". If pathfinder_args is not NULL and the user specifies backend = "rstan", the backend will automatically switch to cmdstanr. The arguments passed to the 'pathfinder' algorithm are specified via 'pathfinder_args'; if 'pathfinder_args' is NULL, the default arguments from 'cmdstanr' will be used.

A named list of objects containing data, which cannot be passed via argument data. Required for some objects used in autocorrelation structures to specify dependency structures as well as for within-group covariance matrices.

A data.frame object (default NULL). This is mainly for internal testing and not be used for routine model fitting.

A character string indicating whether to draw samples from the priors in addition to the posterior draws. Options are "no" (the default), "yes", and "only". These prior draws can be used for various purposes, such as calculating Bayes factors for point hypotheses via brms::hypothesis(). Note that improper priors (including the default improper priors used by brm) are not sampled. For proper priors, see brms::set_prior(). Also, prior draws for the overall intercept are not obtained by default for technical reasons. See brms::brmsformula() for instructions on obtaining prior draws for the intercept. If sample_prior is set to "only", draws will be taken solely from the priors, ignoring the likelihood, which allows you to generate draws from the prior predictive distribution. In this case, all parameters must have proper priors.

An object generated by brms::save_pars() that controls which parameters should be saved in the model. This argument does not affect the model fitting process itself but provides control over which parameters are retained in the final output.

A logical value indicating whether unused factor levels in the data should be dropped. The default is TRUE.

A list of additional arguments passed to rstan::stan_model when using the backend = "rstan" or backend = "cmdstanr". This allows customization of how models are compiled.

An integer specifying the frequency of printing every nth iteration. By default, NULL indicates that the refresh rate will be automatically set by brms::brm(). Setting refresh is especially useful when thin is greater than 1, in which case the refresh rate is recalculated as (refresh * thin) / thin.

A verbosity level between 0 and 2. When set to 1 (the default), most informational messages from the compiler and sampler are suppressed. Setting it to 2 suppresses even more messages. The sampling progress is still printed. To turn off all printing, set refresh = 0. Additionally, when using backend = "rstan", you can prevent the opening of additional progress bars by setting open_progress = FALSE.

An integer or NA (default) specifying the seed for random number generation, ensuring reproducibility of results. If set to NA, Stan will randomly select the seed.

A character string or NULL (default). If provided, the Stan code for the model will be saved in a text file with the name corresponding to the string specified in save_model.

An instance of class brmsfit from a previous fit (default is NA). If a brmsfit object is provided, the compiled model associated with the fitted result is reused, and any arguments that modify the model code or data are ignored. It is generally recommended to use the update method for this purpose, rather than directly passing the fit argument.

Either NULL or a character string. If a character string is provided, the fitted model object is saved using saveRDS in a file named after the string supplied in file. The .rds extension is automatically added. If the specified file already exists, the existing model object is loaded and returned instead of refitting the model. To overwrite an existing file, you must manually remove the file or specify the file_refit argument. The file name is stored within the brmsfit object for later use.

Logical or a character string, specifying one of the compression algorithms supported by saveRDS. If the file argument is provided, this compression will be used when saving the fitted model object.

Modifies when the fit stored via the file argument is re-used. This can be set globally for the current R session via the "brms.file_refit" option (see options). The possible options are:

• "never" (default): The fit is always loaded if it exists, and fitting is skipped.

• "always": The model is always refitted, regardless of existing fits.

• "on_change": The model is refitted only if the model, data, algorithm, priors, sample_prior, stanvars, covariance structure, or similar parameters have changed.

If you believe a false positive occurred, you can use [brms::brmsfit_needs_refit()] to investigate why a refit is deemed necessary. A refit will not be triggered for changes in additional parameters of the fit (e.g., initial values, number of iterations, control arguments). A known limitation is that a refit will be triggered if within-chain parallelization is switched on/off.

Logical; If TRUE, the future package is used for parallel execution of the chains. In this case, the cores argument will be ignored. The execution type is controlled via plan (see the examples section below). This argument can be set globally for the current R session via the "future" option.

A character string specifying the type of parameterization to use for drawing group-level random effects. Options are: 'ncp' for Non-Centered Parameterization (NCP), and 'cp' for Centered Parameterization (CP).

The NCP is generally recommended when the likelihood is weak (e.g., few observations per individual) and is the default approach (and only option) in brms::brm().

The CP parameterization is typically more efficient when a relatively large number of observations are available across individuals. We consider a 'relatively large number' as at least 10 repeated measurements per individual. If there are fewer than 10, NCP is used automatically. This behavior applies only when parameterization = NULL. To explicitly set CP parameterization, use parameterization = 'cp'.

Note that since brms::brm() does not support CP, the stancode generated by brms::brm() is edited internally before fitting the model using rstan::rstan() or "cmdstanr", depending on the chosen backend. Therefore, CP parameterization is considered experimental and may fail if the structure of the generated stancode changes in future versions of brms::brm().

Further arguments passed to brms::brm(). This can include additional arguments that are either passed directly to the underlying model fitting function or used for internal purposes. Specifically, the ... can also be used to pass arguments used for testing and debugging, such as: match_sitar_a_form, match_sitar_d_form, sigmamatch_sitar_a_form, displayit, setcolh, setcolb.

These internal arguments are typically not used in regular model fitting but can be relevant for certain testing scenarios or advanced customization. Users are generally not expected to interact with these unless working on debugging or testing specific features of the model fitting process.

An object of class bgmfit.

A character string containing the user-defined Stan function(s) in Stan code. If NULL (the default), the scode will be retrieved from the model.

A logical (default TRUE) to indicate whether to expose the functions and add them as an attribute to the model.

A character string (default NULL) to specify the model name. This parameter is for internal use only.

A logical (default TRUE) to specify whether to return the model object. If expose = TRUE, it is advisable to set returnobj = TRUE.

A logical (default FALSE) to indicate whether the exposed functions should be vectorized using base::Vectorize(). Note that currently, vectorize should be set to FALSE, as setting it to TRUE may not work as expected.

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

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.

Additional arguments passed to the rstan::expose_stan_functions() function. The "..." can be used to set the compiler, which can be either rstan::stanc() or rstan::stan_model(). You can also pass other compiler-specific arguments such as save_dso for rstan::stan_model(). Note that while both rstan::stanc() and rstan::stan_model() can be used as compilers before calling rstan::expose_stan_functions(), it is important to note that the execution time for rstan::stan_model() is approximately twice as long as rstan::stanc().

An object of class bgmfit.

An optional data frame for estimation. If NULL (default), newdata is retrieved from the model.

A character string (default NULL) to specify the response variable when processing posterior draws for univariate_by and multivariate models. See bsitar() for details on univariate_by and multivariate models.

Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned.

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

Option to indicate whether or not to include individual/group-level effects in the estimation. When NA (default), individual-level effects are excluded, and population average growth parameters are computed. When NULL, individual-level effects are included in the computation, and the resulting growth parameters are individual-specific. In both cases (NA or NULL), continuous and factor covariates are appropriately included in the estimation. Continuous covariates are set to their means by default (see numeric_cov_at for details), while factor covariates remain unaltered, allowing for the estimation of covariate-specific population average and individual-specific growth parameters.

A flag indicating if new levels of group-level effects are allowed (defaults to FALSE). Only relevant if newdata is provided.

Indicates how to sample new levels for grouping factors specified in re_formula. This argument is only relevant if newdata is provided and allow_new_levels is set to TRUE. If "uncertainty" (default), each posterior sample for a new level is drawn from the posterior draws of a randomly chosen existing level. Each posterior sample for a new level may be drawn from a different existing level such that the resulting set of new posterior draws represents the variation across existing levels. If "gaussian", sample new levels from the (multivariate) normal distribution implied by the group-level standard deviations and correlations. This options may be useful for conducting Bayesian power analysis or predicting new levels in situations where relatively few levels where observed in the old_data. If "old_levels", directly sample new levels from the existing levels, where a new level is assigned all of the posterior draws of the same (randomly chosen) existing level.

A flag indicating if correlation structures originally specified via autocor should be included in the predictions. Defaults to TRUE.

An optional (named list) argument to specify the value of continuous covariate(s). The default NULL option sets the continuous covariate(s) to their mean. Alternatively, a named list can be supplied to manually set these values. For example, numeric_cov_at = list(xx = 2) will set the continuous covariate variable 'xx' to 2. The argument numeric_cov_at is ignored when no continuous covariates are included in the model.

An optional argument to specify the ids for the hierarchical model (default NULL). It is used only when the model is applied to data with three or more levels of hierarchy. For a two-level model, levels_id is automatically inferred from the model fit. For models with three or more levels, levels_id is inferred from the model fit under the assumption that hierarchy is specified from the lowest to the uppermost level, i.e., id followed by study, where id is nested within study. However, it is not guaranteed that levels_id is sorted correctly, so it is better to set it manually when fitting a model with three or more levels of hierarchy.

An optional argument (default NULL) to calculate (marginal/average) curves and growth parameters, such as APGV and PGV. If specified, it must be a named list indicating the over (typically a level 1 predictor, such as age), feby (fixed effects, typically a factor variable), and reby (typically NULL, indicating that parameters are integrated over the random effects). For example, avg_reffects = list(feby = 'study', reby = NULL, over = 'age').

An optional argument to specify the variable(s) that can be passed to the ipts argument (see below). This is useful when fitting location-scale models and measurement error models. If post-processing functions throw an error such as variable 'x' not found in either 'data' or 'data2', consider using aux_variables.

An integer to set the length of the predictor variable for generating a smooth velocity curve. If NULL, the original values are returned. If an integer (e.g., ipts = 10, default), the predictor is interpolated. Note that these interpolations do not alter the range of the predictor when calculating population averages and/or individual-specific growth curves.

An integer indicating whether to estimate the distance curve or its derivative (velocity curve). The default deriv = 0 is for the distance curve, while deriv = 1 is for the velocity curve.

A logical value specifying whether to estimate the velocity curve from the derivative function or by differentiating the distance curve. Set deriv_model = TRUE for functions that require the velocity curve, such as growthparameters() and plot_curves(). Set it to NULL for functions that use the distance curve (i.e., fitted values), such as loo_validation() and plot_ppc().

A logical value indicating whether only the estimate should be computed (TRUE), or whether the estimate along with SE and CI should be returned (FALSE, default). Setting summary to FALSE will increase computation time. Note that summary = FALSE is required to obtain correct estimates when re_formula = NULL.

A logical value to specify the summary options. If FALSE (default), the mean is used as the measure of central tendency and the standard deviation as the measure of variability. If TRUE, the median and median absolute deviation (MAD) are applied instead. Ignored if summary is FALSE.

A function applied to individual draws from the posterior distribution before computing summaries. The argument transform is based on the marginaleffects::predictions() function. This should not be confused with transform from brms::posterior_predict(), which is now deprecated.

The percentiles to be computed by the quantile function. Only used if summary is TRUE.

An integer to set the predictor range (e.g., age) when executing the interpolation via ipts. By default, NULL sets the individual-specific predictor range. Setting xrange = 1 applies the same range for individuals within the same higher grouping variable (e.g., study). Setting xrange = 2 applies an identical range across the entire sample. Alternatively, a numeric vector (e.g., xrange = c(6, 20)) can be provided to set the range within the specified values.

A vector of length two or a character string 'range' to set the range of the predictor variable (x) within which growth parameters are searched. This is useful when there is more than one peak and the user wants to summarize the peak within a specified range of the x variable. The default value is xrange_search = NULL.

A logical value to specify whether or not to compute growth parameters on the fly. This is for internal use only and is mainly needed for compatibility across internal functions.

A character string specifying the method used when evaluating parms_eval. The default method is getPeak, which uses the sitar::getPeak() function from the sitar package. Alternatively, findpeaks uses the findpeaks function from the pracma package. This parameter is for internal use and ensures compatibility across internal functions.

A character string to indicate the interpolation method. The number of interpolation points is set by the ipts argument. Available options for idata_method are method 1 (specified as 'm1') and method 2 (specified as 'm2').

• Method 1 ('m1') is adapted from the iapvbs package and is documented here.

• Method 2 ('m2') is based on the JMbayes package and is documented here. The 'm1' method works by internally constructing the data frame based on the model configuration, while the 'm2' method uses the exact data frame from the model fit, accessible via fit$data. If idata_method = NULL (default), method 'm2' is automatically selected. Note that method 'm1' may fail in certain cases, especially when the model includes covariates (particularly in univariate_by models). In such cases, it is recommended to use method 'm2'.

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

A logical value indicating whether to return a fullframe object in which newdata is bound to the summary estimates. Note that fullframe cannot be used with summary = FALSE, and it is only applicable when idata_method = 'm2'. A typical use case is when fitting a univariate_by model. This option is mainly for internal use.

A named list (default NULL) to convert dummy variables into a factor variable. The list must include the following elements:

• factor.dummy: A character vector of dummy variables to be converted to factors.

• factor.name: The name for the newly created factor variable (default is 'factor.var' if NULL).

• factor.level: A vector specifying the factor levels. If NULL, levels are taken from factor.dummy. If factor.level is provided, its length must match factor.dummy.

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.

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.

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.

A list (default NULL) specifying function names. This is rarely needed, as required functions are typically retrieved automatically. A use case for funlist is when sigma_formula, sigma_formula_gr, or sigma_formula_gr_str use an external function (e.g., poly(age)). The funlist should include function names defined in the globalenv(). For functions needing both distance and velocity curves (e.g., plot_curves(..., opt = 'dv')), funlist must include two functions: one for the distance curve and one for the velocity curve.

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.

Additional arguments passed to the brms::fitted.brmsfit() function. For details on available options, please refer to brms::fitted.brmsfit().

A symbol representing the object to be retrieved. The input must be a symbol (i.e., not a character string) corresponding to an existing object within the specified namespace.

A character string specifying the namespace to check for the object. If the object exists within the given namespace, it will be returned.

An environment in which to search for the object. If set to NULL (default), the function uses the global environment.

An object of class bgmfit.

A character string (default NULL) to specify the response variable when processing posterior draws for univariate_by and multivariate models. See bsitar() for details on univariate_by and multivariate models.

Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned.

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

An optional data frame for estimation. If NULL (default), newdata is retrieved from the model.

A grid of user-specified values to be used in the newdata argument of various functions in the marginaleffects package. This allows you to define the regions of the predictor space where you want to evaluate the quantities of interest. See marginaleffects::datagrid() for more details. By default, the datagrid is set to NULL, meaning no custom grid is constructed. To set a custom grid, the argument should either be a data frame created using marginaleffects::datagrid(), or a named list, which is internally used for constructing the grid. For convenience, you can also pass an empty list datagrid = list(), in which case essential arguments like model and newdata are inferred from the respective arguments specified elsewhere. Additionally, the first-level predictor (such as age) and any covariates included in the model (e.g., gender) are automatically inferred from the model object.

Option to indicate whether or not to include individual/group-level effects in the estimation. When NA (default), individual-level effects are excluded, and population average growth parameters are computed. When NULL, individual-level effects are included in the computation, and the resulting growth parameters are individual-specific. In both cases (NA or NULL), continuous and factor covariates are appropriately included in the estimation. Continuous covariates are set to their means by default (see numeric_cov_at for details), while factor covariates remain unaltered, allowing for the estimation of covariate-specific population average and individual-specific growth parameters.

A flag indicating if new levels of group-level effects are allowed (defaults to FALSE). Only relevant if newdata is provided.

Indicates how to sample new levels for grouping factors specified in re_formula. This argument is only relevant if newdata is provided and allow_new_levels is set to TRUE. If "uncertainty" (default), each posterior sample for a new level is drawn from the posterior draws of a randomly chosen existing level. Each posterior sample for a new level may be drawn from a different existing level such that the resulting set of new posterior draws represents the variation across existing levels. If "gaussian", sample new levels from the (multivariate) normal distribution implied by the group-level standard deviations and correlations. This options may be useful for conducting Bayesian power analysis or predicting new levels in situations where relatively few levels where observed in the old_data. If "old_levels", directly sample new levels from the existing levels, where a new level is assigned all of the posterior draws of the same (randomly chosen) existing level.

A single character string or a character vector specifying the growth parameter(s) to be estimated. Options include 'tgv' (takeoff growth velocity), 'atgv' (age at takeoff growth velocity), 'pgv' (peak growth velocity), 'apgv' (age at peak growth velocity), 'cgv' (cessation growth velocity), 'acgv' (age at cessation growth velocity), and 'all'. If parameter = NULL (default), age at peak growth velocity ('apgv') is estimated. When parameter = 'all', all six parameters are estimated. Note that the 'all' option cannot be used when the by argument is set to TRUE.

An integer to set the predictor range (e.g., age) when executing the interpolation via ipts. By default, NULL sets the individual-specific predictor range. Setting xrange = 1 applies the same range for individuals within the same higher grouping variable (e.g., study). Setting xrange = 2 applies an identical range across the entire sample. Alternatively, a numeric vector (e.g., xrange = c(6, 20)) can be provided to set the range within the specified values.

A real number specifying the percentage of peak growth velocity to be used as the cessation velocity when estimating the cgv and acgv growth parameters. The acg_velocity should be greater than 0 and less than 1. The default value of acg_velocity = 0.10 indicates that 10 percent of the peak growth velocity will be used to calculate the cessation growth velocity and the corresponding age at cessation velocity. For example, if the peak growth velocity estimate is 10 mm/year, then the cessation growth velocity will be 1 mm/year.

An integer (default 2) specifying the number of decimal places to round the estimated growth parameters. The digits value is passed to the base::round() function.

An optional (named list) argument to specify the value of continuous covariate(s). The default NULL option sets the continuous covariate(s) to their mean. Alternatively, a named list can be supplied to manually set these values. For example, numeric_cov_at = list(xx = 2) will set the continuous covariate variable 'xx' to 2. The argument numeric_cov_at is ignored when no continuous covariates are included in the model.

An optional argument to specify the variable(s) that can be passed to the ipts argument (see below). This is useful when fitting location-scale models and measurement error models. If post-processing functions throw an error such as variable 'x' not found in either 'data' or 'data2', consider using aux_variables.

An optional argument to specify the ids for the hierarchical model (default NULL). It is used only when the model is applied to data with three or more levels of hierarchy. For a two-level model, levels_id is automatically inferred from the model fit. For models with three or more levels, levels_id is inferred from the model fit under the assumption that hierarchy is specified from the lowest to the uppermost level, i.e., id followed by study, where id is nested within study. However, it is not guaranteed that levels_id is sorted correctly, so it is better to set it manually when fitting a model with three or more levels of hierarchy.

An optional argument (default NULL) to calculate (marginal/average) curves and growth parameters, such as APGV and PGV. If specified, it must be a named list indicating the over (typically a level 1 predictor, such as age), feby (fixed effects, typically a factor variable), and reby (typically NULL, indicating that parameters are integrated over the random effects). For example, avg_reffects = list(feby = 'study', reby = NULL, over = 'age').

A character string to indicate the interpolation method. The number of interpolation points is set by the ipts argument. Available options for idata_method are method 1 (specified as 'm1') and method 2 (specified as 'm2').

• Method 1 ('m1') is adapted from the iapvbs package and is documented here.

• Method 2 ('m2') is based on the JMbayes package and is documented here. The 'm1' method works by internally constructing the data frame based on the model configuration, while the 'm2' method uses the exact data frame from the model fit, accessible via fit$data. If idata_method = NULL (default), method 'm2' is automatically selected. Note that method 'm1' may fail in certain cases, especially when the model includes covariates (particularly in univariate_by models). In such cases, it is recommended to use method 'm2'.

An integer to set the length of the predictor variable for generating a smooth velocity curve. If NULL, the original values are returned. If an integer (e.g., ipts = 10, default), the predictor is interpolated. Note that these interpolations do not alter the range of the predictor when calculating population averages and/or individual-specific growth curves.

An integer (default 123) that is passed to the estimation method to ensure reproducibility.

A logical value (default FALSE) to specify whether or not to perform parallel computations. If set to TRUE, the future.apply::future_sapply() function is used to summarize the posterior draws in parallel.

A character string specifying the session type when future = TRUE. The 'multisession' (default) option sets the multisession environment, while the 'multicore' option sets up a multicore session. Note that 'multicore' is not supported on Windows systems. For more details, see future.apply::future_sapply().

A list (default NULL) that can be an unnamed numeric list, a logical value, or a numeric vector of length 1 or 2. It is used to split the processing of posterior draws into smaller subsets for parallel computation.

• If passed as a list (e.g., future_splits = list(1:6, 7:10)), each sequence of numbers is passed to the draw_ids argument.

• If passed as a numeric vector (e.g., future_splits = c(10, 2)), the first element specifies the number of draws (see draw_ids) and the second element indicates the number of splits. The splits are created using parallel::splitIndices().

• If passed as a numeric vector of length 1, the first element is internally set as the number of draws (ndraws or draw_ids) depending on which one is not NULL.

• If TRUE, a numeric vector for future_splits is created based on the number of draws (ndraws) and the number of cores (cores).

• If FALSE, future_splits is ignored. The use case for future_splits is to save memory and improve performance, especially on Linux systems when future::plan() is set to multicore. Note: on Windows systems, R processes may not be freed automatically when using 'multisession'. In such cases, the R processes can be interrupted using installr::kill_all_Rscript_s().

A character string (default 'future') to specify the method for parallel computation. Options include:

• 'future': Uses future::future() along with future.apply::future_lapply() for parallel execution.

• 'foreach': Uses foreach::foreach() with the 'dofuture' function from the doFuture package for parallel execution.

A logical (default NULL) to indicate whether to re-expose Stan functions when future = TRUE. This is especially relevant when future::plan() is set to 'multisession', as already exposed C++ Stan functions cannot be passed across multiple sessions.

• When future_re_expose = NULL (the default), future_re_expose is automatically set to TRUE for the 'multisession' plan.

• It is advised to explicitly set future_re_expose = TRUE for speed gains when using parallel processing with future = TRUE.

A logical (default FALSE) indicating whether to use the dtplyr package for summarizing the draws. This package uses data.table as a back-end. It is useful when the data has a large number of observations. For typical use cases, it does not make a significant performance difference. The usedtplyr argument is evaluated only when method = 'custom'.

A logical (default FALSE) to indicate whether to use the collapse package for summarizing the draws.

A logical (default FALSE) indicating whether to use parallel computation (via doParallel and foreach) when usecollapse = TRUE. When parallel = TRUE, parallel::makeCluster() sets the cluster type as "PSOCK", which works on all operating systems, including Windows. If you want to use a faster option for Unix-based systems, you can set parallel = "FORK", but note that it is not compatible with Windows systems.

A positive integer (default 1) specifying the number of CPU cores to use when parallel = TRUE. To automatically detect the number of available cores, set cores = NULL. This is useful for optimizing performance when working with large datasets.

A logical value indicating whether to internally call the marginaleffects::comparisons() or the marginaleffects::avg_comparisons() function. If FALSE (default), marginaleffects::comparisons() is called, otherwise marginaleffects::avg_comparisons() is used when average = TRUE.

A logical value specifying whether to plot comparisons by calling the marginaleffects::plot_comparisons() function (TRUE) or not (FALSE). If FALSE (default), then marginaleffects::comparisons() or marginaleffects::avg_comparisons() are called to compute predictions (see the average argument for details).

A logical value to specify whether to show legends (TRUE) or not (FALSE). If NULL (default), the value of showlegends is internally set to TRUE if re_formula = NA, and FALSE if re_formula = NULL.

A named list specifying the level 1 predictor, such as age or time, used for estimating growth parameters in the current use case. The variables list is set via the esp argument (default value is 1e-6). If variables is NULL, the relevant information is retrieved internally from the model. Alternatively, users can define variables as a named list, e.g., variables = list('x' = 1e-6) where 'x' is the level 1 predictor. By default, variables = list('age' = 1e-6) in the marginaleffects package, as velocity is usually computed by differentiating the distance curve using the dydx approach. When using this default, the argument deriv is automatically set to 0 and deriv_model to FALSE. If parameters are to be estimated based on the model's first derivative, deriv must be set to 1 and variables will be defined as variables = list('age' = 0). Note that if the default behavior is used (deriv = 0 and variables = list('x' = 1e-6)), additional arguments cannot be passed to variables. In contrast, when using an alternative approach (deriv = 0 and variables = list('x' = 0)), additional options can be passed to the marginaleffects::comparisons() and marginaleffects::avg_comparisons() functions.

A numeric value specifying whether to estimate parameters based on the differentiation of the distance curve or the model's first derivative. Please refer to the variables argument for more details.

A logical value specifying whether to estimate the velocity curve from the derivative function or by differentiating the distance curve. Set deriv_model = TRUE for functions that require the velocity curve, such as growthparameters() and plot_curves(). Set it to NULL for functions that use the distance curve (i.e., fitted values), such as loo_validation() and plot_ppc().

A character string indicating whether to compute estimates using the 'marginaleffects' package (method = 'pkg') or custom functions for efficiency and speed (method = 'custom', default). The method = 'pkg' option is only suitable for simple cases and should be used with caution. method = 'custom' is the preferred option because it allows for simultaneous estimation of multiple parameters (e.g., 'apgv' and 'pgv'). This method works during the post-draw stage, supports multiple parameter comparisons via the hypothesis argument, and allows users to add or return draws (see pdraws for details). If method = 'pkg', the by argument must not contain the predictor (e.g., age), and variables must either be NULL (which defaults to list(age = 1e-6)) or a list with factor variables like variables = list(class = 'pairwise') or variables = list(age = 1e-6, class = 'pairwise'). With method = 'custom', the by argument can include predictors, which will be ignored, and variables should not contain predictors, but can accept factor variables as a vector (e.g., variables = c('class')). Using method = 'custom' is strongly recommended for better performance and flexibility.

A list, data.frame, or tibble returned by the marginaleffects functions (default NULL). This is only evaluated when method = 'custom'. The marginals can be the output from marginaleffects functions or posterior draws from marginaleffects::posterior_draws(). The marginals argument is primarily used for internal purposes.

A character string (default FALSE) that indicates whether to return the raw posterior draws. Options include:

• 'return': returns the raw draws,

• 'add': adds the raw draws to the final return object,

• 'returns': returns the summary of the raw draws,

• 'adds': adds the summary of raw draws to the final return object.

The pdraws are the velocity estimates for each posterior sample. For more details, see marginaleffects::posterior_draws().

A character string (default FALSE) to indicate whether to return the original posterior draws for parameters. Options include:

• 'return': returns the original posterior draws,

• 'add': adds the original posterior draws to the outcome.

When pdrawso = TRUE, the default behavior is pdrawso = 'return'. Note that the posterior draws are returned before calling marginaleffects::posterior_draws().

A character string (default FALSE) to indicate whether to return the posterior draws for parameters. Options include:

• 'return': returns the posterior draws for parameters,

• 'add': adds the posterior draws to the outcome.

When pdrawsp = TRUE, the default behavior is pdrawsp = 'return'. The pdrawsp represent the parameter estimates for each of the posterior samples, and the summary of these are the estimates returned.

A character string (default FALSE) to indicate whether to return the posterior draws for parameter contrasts. Options include:

• 'return': returns the posterior draws for contrasts.

The summary of posterior draws for parameters is the default returned object. The pdrawsh represent the contrast estimates for each of the posterior samples, and the summary of these are the contrast returned.

A character string specifying the comparison type for growth parameter estimation. Options are 'difference' and 'differenceavg'. This argument sets up the internal function for estimating parameters using sitar::getPeak(), sitar::getTakeoff(), and sitar::getTrough() functions. These options are restructured according to the user-specified hypothesis argument.

string indicates the type (scale) of the predictions used to compute contrasts or slopes. This can differ based on the model type, but will typically be a string such as: "response", "link", "probs", or "zero". When an unsupported string is entered, the model-specific list of acceptable values is returned in an error message. When type is NULL, the first entry in the error message is used by default.

Aggregate unit-level estimates (aka, marginalize, average over). Valid inputs:

• FALSE: return the original unit-level estimates.

• TRUE: aggregate estimates for each term.

• Character vector of column names in newdata or in the data frame produced by calling the function without the by argument.

• Data frame with a by column of group labels, and merging columns shared by newdata or the data frame produced by calling the same function without the by argument.

• See examples below.

• For more complex aggregations, you can use the FUN argument of the hypotheses() function. See that function's documentation and the Hypothesis Test vignettes on the marginaleffects website.

A character string (default NULL) specifying the variables over which the parameters need to be summarized. If bys is not NULL, the summary statistics will be calculated for each unique combination of the specified variables.

numeric value between 0 and 1. Confidence level to use to build a confidence interval.

A function applied to individual draws from the posterior distribution before computing summaries. The argument transform is based on the marginaleffects::predictions() function. This should not be confused with transform from brms::posterior_predict(), which is now deprecated.

• FALSE: Contrasts represent the change in adjusted predictions when one predictor changes and all other variables are held constant.

• TRUE: Contrasts represent the changes in adjusted predictions when all the predictors specified in the variables argument are manipulated simultaneously (a "cross-contrast").

logical, string or numeric: weights to use when computing average predictions, contrasts or slopes. These weights only affect the averaging in ⁠avg_*()⁠ or with the by argument, and not unit-level estimates. See ?weighted.mean

• string: column name of the weights variable in newdata. When supplying a column name to wts, it is recommended to supply the original data (including the weights variable) explicitly to newdata.

• numeric: vector of length equal to the number of rows in the original data or in newdata (if supplied).

• FALSE: Equal weights.

• TRUE: Extract weights from the fitted object with insight::find_weights() and use them when taking weighted averages of estimates. Warning: newdata=datagrid() returns a single average weight, which is equivalent to using wts=FALSE

specify a hypothesis test or custom contrast using a number , formula, string equation, vector, matrix, or function.

• Number: The null hypothesis used in the computation of Z and p (before applying transform).

• String: Equation to specify linear or non-linear hypothesis tests. If the terms in coef(object) uniquely identify estimates, they can be used in the formula. Otherwise, use b1, b2, etc. to identify the position of each parameter. The ⁠b*⁠ wildcard can be used to test hypotheses on all estimates. If a named vector is used, the names are used as labels in the output. Examples:

  • hp = drat

  • hp + drat = 12

  • b1 + b2 + b3 = 0

  • ⁠b* / b1 = 1⁠

• Formula: lhs ~ rhs | group

  • lhs

    • ratio

    • difference

    • Leave empty for default value

  • rhs

    • pairwise and revpairwise: pairwise differences between estimates in each row.

    • reference: differences between the estimates in each row and the estimate in the first row.

    • sequential: difference between an estimate and the estimate in the next row.

    • meandev: difference between an estimate and the mean of all estimates.

    • 'meanotherdev: difference between an estimate and the mean of all other estimates, excluding the current one.

    • poly: polynomial contrasts, as computed by the stats::contr.poly() function.

    • helmert: Helmert contrasts, as computed by the stats::contr.helmert() function. Contrast 2nd level to the first, 3rd to the average of the first two, and so on.

    • trt_vs_ctrl: difference between the mean of estimates (except the first) and the first estimate.

    • I(fun(x)): custom function to manipulate the vector of estimates x. The function fun() can return multiple (potentially named) estimates.

  • group (optional)

    • Column name of newdata. Conduct hypothesis tests withing subsets of the data.

  • Examples:

    • ~ poly

    • ~ sequential | groupid

    • ~ reference

    • ratio ~ pairwise

    • difference ~ pairwise | groupid

    • ~ I(x - mean(x)) | groupid

    • ⁠~ I(\(x) c(a = x[1], b = mean(x[2:3]))) | groupid⁠

• Matrix or Vector: Each column is a vector of weights. The the output is the dot product between these vectors of weights and the vector of estimates. The matrix can have column names to label the estimates.

• Function:

  • Accepts an argument x: object produced by a marginaleffects function or a data frame with column rowid and estimate

  • Returns a data frame with columns term and estimate (mandatory) and rowid (optional).

  • The function can also accept optional input arguments: newdata, by, draws.

  • This function approach will not work for Bayesian models or with bootstrapping. In those cases, it is easy to use get_draws() to extract and manipulate the draws directly.

• See the Examples section below and the vignette: https://marginaleffects.com/chapters/hypothesis.html

Numeric vector of length 2: bounds used for the two-one-sided test (TOST) of equivalence, and for the non-inferiority and non-superiority tests. See Details section below.

NULL or numeric value which determines the step size to use when calculating numerical derivatives: (f(x+eps)-f(x))/eps. When eps is NULL, the step size is 0.0001 multiplied by the difference between the maximum and minimum values of the variable with respect to which we are taking the derivative. Changing eps may be necessary to avoid numerical problems in certain models.

A character vector (default FALSE) specifying the variable(s) by which estimates and contrasts (during the post-draw stage) should be computed using the hypothesis argument. The variable(s) in constrats_by should be a subset of those specified in the by argument. If constrats_by = NULL, it will copy all variables from by, except for the level-1 predictor (e.g., age). To disable this automatic behavior, use constrats_by = FALSE. This argument is evaluated only when method = 'custom' and hypothesis is not NULL.

A named list (default FALSE) to specify the values at which estimates and contrasts should be computed during the post-draw stage using the hypothesis argument. The values can be specified as 'max', 'min', 'unique', or 'range' (e.g., constrats_at = list(age = 'min')) or as numeric values or vectors (e.g., constrats_at = list(age = c(6, 7))). If constrats_at = NULL, level-1 predictors (e.g., age) are automatically set to their unique values (i.e., constrats_at = list(age = 'unique')). To turn off this behavior, use constrats_at = FALSE. Note that constrats_at only affects data subsets prepared via marginaleffects::datagrid() or the newdata argument. The argument is evaluated only when method = 'custom' and hypothesis is not NULL.

A named list (default FALSE) to filter the estimates at which contrasts are computed using the hypothesis argument. This is similar to constrats_at, except that constrats_subset filters based on a character vector of variable names (e.g., constrats_subset = list(id = c('id1', 'id2'))) rather than numeric values. The argument is evaluated only when method = 'custom' and hypothesis is not NULL.

A logical (default TRUE) indicating whether to reformat the output returned by marginaleffects as a data frame. Column names are redefined as conf.low to Q2.5 and conf.high to Q97.5 (assuming conf_int = 0.95). Additionally, some columns (term, contrast, etc.) are dropped from the data frame.

A character string (default NULL) specifying how to center estimates: either 'mean' or 'median'. This option sets the global options as follows: options("marginaleffects_posterior_center" = "mean") or options("marginaleffects_posterior_center" = "median"). These global options are restored upon function exit using base::on.exit().

A character string (default NULL) to specify the type of credible intervals: 'eti' for equal-tailed intervals or 'hdi' for highest density intervals. This option sets the global options as follows: options("marginaleffects_posterior_interval" = "eti") or options("marginaleffects_posterior_interval" = "hdi"), and is restored on exit using base::on.exit().

A named list (default NULL) to convert dummy variables into a factor variable. The list must include the following elements:

• factor.dummy: A character vector of dummy variables to be converted to factors.

• factor.name: The name for the newly created factor variable (default is 'factor.var' if NULL).

• factor.level: A vector specifying the factor levels. If NULL, levels are taken from factor.dummy. If factor.level is provided, its length must match factor.dummy.

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

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.

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.

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.

A list (default NULL) specifying function names. This is rarely needed, as required functions are typically retrieved automatically. A use case for funlist is when sigma_formula, sigma_formula_gr, or sigma_formula_gr_str use an external function (e.g., poly(age)). The funlist should include function names defined in the globalenv(). For functions needing both distance and velocity curves (e.g., plot_curves(..., opt = 'dv')), funlist must include two functions: one for the distance curve and one for the velocity curve.

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.

Additional arguments passed to the brms::fitted.brmsfit() and brms::predict() functions.

An object of class bgmfit.

An optional data frame for estimation. If NULL (default), newdata is retrieved from the model.

A character string (default NULL) to specify the response variable when processing posterior draws for univariate_by and multivariate models. See bsitar() for details on univariate_by and multivariate models.

Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned.

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

A logical value indicating whether only the estimate should be computed (TRUE), or whether the estimate along with SE and CI should be returned (FALSE, default). Setting summary to FALSE will increase computation time. Note that summary = FALSE is required to obtain correct estimates when re_formula = NULL.

A logical value to specify the summary options. If FALSE (default), the mean is used as the measure of central tendency and the standard deviation as the measure of variability. If TRUE, the median and median absolute deviation (MAD) are applied instead. Ignored if summary is FALSE.

A function applied to individual draws from the posterior distribution before computing summaries. The argument transform is based on the marginaleffects::predictions() function. This should not be confused with transform from brms::posterior_predict(), which is now deprecated.

Option to indicate whether or not to include individual/group-level effects in the estimation. When NA (default), individual-level effects are excluded, and population average growth parameters are computed. When NULL, individual-level effects are included in the computation, and the resulting growth parameters are individual-specific. In both cases (NA or NULL), continuous and factor covariates are appropriately included in the estimation. Continuous covariates are set to their means by default (see numeric_cov_at for details), while factor covariates remain unaltered, allowing for the estimation of covariate-specific population average and individual-specific growth parameters.

A logical value (default TRUE) indicating whether to calculate the age at peak velocity (APGV) and the peak velocity (PGV) parameters.

A logical value (default FALSE) indicating whether to calculate the age at takeoff velocity (ATGV) and the takeoff growth velocity (TGV) parameters.

A logical value (default FALSE) indicating whether to calculate the age at cessation of growth velocity (ACGV) and the cessation of growth velocity (CGV) parameters.

A logical value (default FALSE) indicating whether to calculate the age at cessation of growth velocity from the velocity curve. If TRUE, the age at cessation of growth velocity (ACGV) and the cessation growth velocity (CGV) are calculated based on the percentage of the peak growth velocity, as defined by the acgv_velocity argument (see below). The acgv_velocity is typically set at 10 percent of the peak growth velocity. ACGV and CGV are calculated along with the uncertainty (SE and CI) around the ACGV and CGV parameters.

The percentage of the peak growth velocity to use when estimating acgv. The default value is 0.10, i.e., 10 percent of the peak growth velocity.

A character string specifying the estimation method when calculating the velocity from the posterior draws. The 'fitted' method internally calls fitted_draws(), while the 'predict' method calls predict_draws(). See brms::fitted.brmsfit() and brms::predict.brmsfit() for details.

A flag indicating if new levels of group-level effects are allowed (defaults to FALSE). Only relevant if newdata is provided.

Indicates how to sample new levels for grouping factors specified in re_formula. This argument is only relevant if newdata is provided and allow_new_levels is set to TRUE. If "uncertainty" (default), each posterior sample for a new level is drawn from the posterior draws of a randomly chosen existing level. Each posterior sample for a new level may be drawn from a different existing level such that the resulting set of new posterior draws represents the variation across existing levels. If "gaussian", sample new levels from the (multivariate) normal distribution implied by the group-level standard deviations and correlations. This options may be useful for conducting Bayesian power analysis or predicting new levels in situations where relatively few levels where observed in the old_data. If "old_levels", directly sample new levels from the existing levels, where a new level is assigned all of the posterior draws of the same (randomly chosen) existing level.

A flag indicating if correlation structures originally specified via autocor should be included in the predictions. Defaults to TRUE.

An optional (named list) argument to specify the value of continuous covariate(s). The default NULL option sets the continuous covariate(s) to their mean. Alternatively, a named list can be supplied to manually set these values. For example, numeric_cov_at = list(xx = 2) will set the continuous covariate variable 'xx' to 2. The argument numeric_cov_at is ignored when no continuous covariates are included in the model.

An optional argument to specify the ids for the hierarchical model (default NULL). It is used only when the model is applied to data with three or more levels of hierarchy. For a two-level model, levels_id is automatically inferred from the model fit. For models with three or more levels, levels_id is inferred from the model fit under the assumption that hierarchy is specified from the lowest to the uppermost level, i.e., id followed by study, where id is nested within study. However, it is not guaranteed that levels_id is sorted correctly, so it is better to set it manually when fitting a model with three or more levels of hierarchy.

An optional argument (default NULL) to calculate (marginal/average) curves and growth parameters, such as APGV and PGV. If specified, it must be a named list indicating the over (typically a level 1 predictor, such as age), feby (fixed effects, typically a factor variable), and reby (typically NULL, indicating that parameters are integrated over the random effects). For example, avg_reffects = list(feby = 'study', reby = NULL, over = 'age').

An optional argument to specify the variable(s) that can be passed to the ipts argument (see below). This is useful when fitting location-scale models and measurement error models. If post-processing functions throw an error such as variable 'x' not found in either 'data' or 'data2', consider using aux_variables.

An integer to set the length of the predictor variable for generating a smooth velocity curve. If NULL, the original values are returned. If an integer (e.g., ipts = 10, default), the predictor is interpolated. Note that these interpolations do not alter the range of the predictor when calculating population averages and/or individual-specific growth curves.

A logical value specifying whether to estimate the velocity curve from the derivative function or by differentiating the distance curve. Set deriv_model = TRUE for functions that require the velocity curve, such as growthparameters() and plot_curves(). Set it to NULL for functions that use the distance curve (i.e., fitted values), such as loo_validation() and plot_ppc().

A numeric value (default 0.95) to compute the confidence interval (CI). Internally, conf is translated into paired probability values as c((1 - conf)/2, 1 - (1 - conf)/2). For conf = 0.95, this computes a 95% CI where the lower and upper limits are named Q.2.5 and Q.97.5, respectively.

An integer to set the predictor range (e.g., age) when executing the interpolation via ipts. By default, NULL sets the individual-specific predictor range. Setting xrange = 1 applies the same range for individuals within the same higher grouping variable (e.g., study). Setting xrange = 2 applies an identical range across the entire sample. Alternatively, a numeric vector (e.g., xrange = c(6, 20)) can be provided to set the range within the specified values.

A vector of length two or a character string 'range' to set the range of the predictor variable (x) within which growth parameters are searched. This is useful when there is more than one peak and the user wants to summarize the peak within a specified range of the x variable. The default value is xrange_search = NULL.

An integer (default 2) to set the decimal places for rounding the results using the base::round() function.

An integer (default 123) that is passed to the estimation method to ensure reproducibility.

A logical value (default FALSE) to specify whether or not to perform parallel computations. If set to TRUE, the future.apply::future_sapply() function is used to summarize the posterior draws in parallel.

A character string specifying the session type when future = TRUE. The 'multisession' (default) option sets the multisession environment, while the 'multicore' option sets up a multicore session. Note that 'multicore' is not supported on Windows systems. For more details, see future.apply::future_sapply().

The number of cores to be used for parallel computations if future = TRUE. On non-Windows systems, this argument can be set globally via the mc.cores option. By default, NULL, the number of cores is automatically determined using future::availableCores(), and it will use the maximum number of cores available minus one (i.e., future::availableCores() - 1).

A logical value to specify whether or not to compute growth parameters on the fly. This is for internal use only and is mainly needed for compatibility across internal functions.

A character string to indicate the interpolation method. The number of interpolation points is set by the ipts argument. Available options for idata_method are method 1 (specified as 'm1') and method 2 (specified as 'm2').

• Method 1 ('m1') is adapted from the iapvbs package and is documented here.

• Method 2 ('m2') is based on the JMbayes package and is documented here. The 'm1' method works by internally constructing the data frame based on the model configuration, while the 'm2' method uses the exact data frame from the model fit, accessible via fit$data. If idata_method = NULL (default), method 'm2' is automatically selected. Note that method 'm1' may fail in certain cases, especially when the model includes covariates (particularly in univariate_by models). In such cases, it is recommended to use method 'm2'.

A character string specifying the method used when evaluating parms_eval. The default method is getPeak, which uses the sitar::getPeak() function from the sitar package. Alternatively, findpeaks uses the findpeaks function from the pracma package. This parameter is for internal use and ensures compatibility across internal functions.

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

A logical value indicating whether to return a fullframe object in which newdata is bound to the summary estimates. Note that fullframe cannot be used with summary = FALSE, and it is only applicable when idata_method = 'm2'. A typical use case is when fitting a univariate_by model. This option is mainly for internal use.

A named list (default NULL) to convert dummy variables into a factor variable. The list must include the following elements:

• factor.dummy: A character vector of dummy variables to be converted to factors.

• factor.name: The name for the newly created factor variable (default is 'factor.var' if NULL).

• factor.level: A vector specifying the factor levels. If NULL, levels are taken from factor.dummy. If factor.level is provided, its length must match factor.dummy.

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.

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.

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.

A list (default NULL) specifying function names. This is rarely needed, as required functions are typically retrieved automatically. A use case for funlist is when sigma_formula, sigma_formula_gr, or sigma_formula_gr_str use an external function (e.g., poly(age)). The funlist should include function names defined in the globalenv(). For functions needing both distance and velocity curves (e.g., plot_curves(..., opt = 'dv')), funlist must include two functions: one for the distance curve and one for the velocity curve.

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.

Additional arguments passed to the brms::fitted.brmsfit() and brms::predict() functions.

An R object

An object of class bgmfit.

A logical flag indicating if the information criteria of the models should be compared using loo::loo_compare().

Optional names of response variables. If specified, predictions are performed only for the specified response variables.

Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned.

A flag indicating whether to compute the full log-likelihood matrix at once or separately for each observation. The latter approach is usually considerably slower but requires much less working memory. Accordingly, if one runs into memory issues, pointwise = TRUE is the way to go.

A logical flag to indicate whether loo::loo_moment_match() should be applied to problematic observations. Defaults to FALSE. For most models, moment matching will only work if save_pars = save_pars(all = TRUE) was set when fitting the model with brms::brm(). See brms::loo_moment_match() for more details.

A logical flag indicating whether brms::reloo() should be applied to problematic observations. Defaults to FALSE.

The Pareto $k$ threshold for which observations loo_moment_match or reloo is applied if argument moment_match or reloo is TRUE. Defaults to 0.7. See pareto_k_ids for more details.

Should the "psis" object created internally be saved in the returned object? For more details see loo.

An optional list of additional arguments passed to loo::loo_moment_match().

An optional list of additional arguments passed to brms::reloo().

If NULL (the default) will use model names derived from deparsing the call. Otherwise will use the passed values as model names.

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

The number of cores to be used for parallel computations if future = TRUE. On non-Windows systems, this argument can be set globally via the mc.cores option. By default, NULL, the number of cores is automatically determined using future::availableCores(), and it will use the maximum number of cores available minus one (i.e., future::availableCores() - 1).

A logical value specifying whether to estimate the velocity curve from the derivative function or by differentiating the distance curve. Set deriv_model = TRUE for functions that require the velocity curve, such as growthparameters() and plot_curves(). Set it to NULL for functions that use the distance curve (i.e., fitted values), such as loo_validation() and plot_ppc().

A logical argument (default FALSE) to specify whether to print information collected during the setup of the object(s).

A named list (default NULL) to convert dummy variables into a factor variable. The list must include the following elements:

• factor.dummy: A character vector of dummy variables to be converted to factors.

• factor.name: The name for the newly created factor variable (default is 'factor.var' if NULL).

• factor.level: A vector specifying the factor levels. If NULL, levels are taken from factor.dummy. If factor.level is provided, its length must match factor.dummy.

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.

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.

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.

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.

Additional arguments passed to the brms::loo() function. Please see brms::loo for details on various options available.

An object of class bgmfit.

A character string (default NULL) to specify the response variable when processing posterior draws for univariate_by and multivariate models. See bsitar() for details on univariate_by and multivariate models.

Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned.

A positive integer indicating the number of posterior draws to use in estimation. If NULL (default), all draws are used.

An integer specifying the specific posterior draw(s) to use in estimation (default NULL).

An optional data frame for estimation. If NULL (default), newdata is retrieved from the model.

A data frame or named list for setting up a custom grid of predictor values to evaluate the quantities of interest. If NULL (default), no custom grid is used. The grid can be constructed using marginaleffects::datagrid(). If datagrid = list(), essential arguments such as model and newdata are inferred automatically from the respective arguments in the model fit.

Option to indicate whether or not to include individual/group-level effects in the estimation. When NA (default), individual-level effects are excluded, and population average growth parameters are computed. When NULL, individual-level effects are included in the computation, and the resulting growth parameters are individual-specific. In both cases (NA or NULL), continuous and factor covariates are appropriately included in the estimation. Continuous covariates are set to their means by default (see numeric_cov_at for details), while factor covariates remain unaltered, allowing for the estimation of covariate-specific population average and individual-specific growth parameters.

A flag indicating if new levels of group-level effects are allowed (defaults to FALSE). Only relevant if newdata is provided.

Indicates how to sample new levels for grouping factors specified in re_formula. This argument is only relevant if newdata is provided and allow_new_levels is set to TRUE. If "uncertainty" (default), each posterior sample for a new level is drawn from the posterior draws of a randomly chosen existing level. Each posterior sample for a new level may be drawn from a different existing level such that the resulting set of new posterior draws represents the variation across existing levels. If "gaussian", sample new levels from the (multivariate) normal distribution implied by the group-level standard deviations and correlations. This options may be useful for conducting Bayesian power analysis or predicting new levels in situations where relatively few levels where observed in the old_data. If "old_levels", directly sample new levels from the existing levels, where a new level is assigned all of the posterior draws of the same (randomly chosen) existing level.

An integer to set the predictor range (e.g., age) when executing the interpolation via ipts. By default, NULL sets the individual-specific predictor range. Setting xrange = 1 applies the same range for individuals within the same higher grouping variable (e.g., study). Setting xrange = 2 applies an identical range across the entire sample. Alternatively, a numeric vector (e.g., xrange = c(6, 20)) can be provided to set the range within the specified values.

An integer (default 2) for rounding the estimates to the specified number of decimal places using base::round().

An optional (named list) argument to specify the value of continuous covariate(s). The default NULL option sets the continuous covariate(s) to their mean. Alternatively, a named list can be supplied to manually set these values. For example, numeric_cov_at = list(xx = 2) will set the continuous covariate variable 'xx' to 2. The argument numeric_cov_at is ignored when no continuous covariates are included in the model.

An optional argument to specify the variable(s) that can be passed to the ipts argument (see below). This is useful when fitting location-scale models and measurement error models. If post-processing functions throw an error such as variable 'x' not found in either 'data' or 'data2', consider using aux_variables.

An optional argument to specify the ids for the hierarchical model (default NULL). It is used only when the model is applied to data with three or more levels of hierarchy. For a two-level model, levels_id is automatically inferred from the model fit. For models with three or more levels, levels_id is inferred from the model fit under the assumption that hierarchy is specified from the lowest to the uppermost level, i.e., id followed by study, where id is nested within study. However, it is not guaranteed that levels_id is sorted correctly, so it is better to set it manually when fitting a model with three or more levels of hierarchy.

An optional argument (default NULL) to calculate (marginal/average) curves and growth parameters, such as APGV and PGV. If specified, it must be a named list indicating the over (typically a level 1 predictor, such as age), feby (fixed effects, typically a factor variable), and reby (typically NULL, indicating that parameters are integrated over the random effects). For example, avg_reffects = list(feby = 'study', reby = NULL, over = 'age').

A character string to indicate the interpolation method. The number of interpolation points is set by the ipts argument. Available options for idata_method are method 1 (specified as 'm1') and method 2 (specified as 'm2').

• Method 1 ('m1') is adapted from the iapvbs package and is documented here.

• Method 2 ('m2') is based on the JMbayes package and is documented here. The 'm1' method works by internally constructing the data frame based on the model configuration, while the 'm2' method uses the exact data frame from the model fit, accessible via fit$data. If idata_method = NULL (default), method 'm2' is automatically selected. Note that method 'm1' may fail in certain cases, especially when the model includes covariates (particularly in univariate_by models). In such cases, it is recommended to use method 'm2'.

An integer to set the length of the predictor variable for generating a smooth velocity curve. If NULL, the original values are returned. If an integer (e.g., ipts = 10, default), the predictor is interpolated. Note that these interpolations do not alter the range of the predictor when calculating population averages and/or individual-specific growth curves.

An integer (default 123) that is passed to the estimation method to ensure reproducibility.

A logical value (default FALSE) to specify whether or not to perform parallel computations. If set to TRUE, the future.apply::future_sapply() function is used to summarize the posterior draws in parallel.

A character string specifying the session type when future = TRUE. The 'multisession' (default) option sets the multisession environment, while the 'multicore' option sets up a multicore session. Note that 'multicore' is not supported on Windows systems. For more details, see future.apply::future_sapply().

A list (default NULL) that can be an unnamed numeric list, a logical value, or a numeric vector of length 1 or 2. It is used to split the processing of posterior draws into smaller subsets for parallel computation.

• If passed as a list (e.g., future_splits = list(1:6, 7:10)), each sequence of numbers is passed to the draw_ids argument.

• If passed as a numeric vector (e.g., future_splits = c(10, 2)), the first element specifies the number of draws (see draw_ids) and the second element indicates the number of splits. The splits are created using parallel::splitIndices().

• If passed as a numeric vector of length 1, the first element is internally set as the number of draws (ndraws or draw_ids) depending on which one is not NULL.

• If TRUE, a numeric vector for future_splits is created based on the number of draws (ndraws) and the number of cores (cores).

• If FALSE, future_splits is ignored. The use case for future_splits is to save memory and improve performance, especially on Linux systems when future::plan() is set to multicore. Note: on Windows systems, R processes may not be freed automatically when using 'multisession'. In such cases, the R processes can be interrupted using installr::kill_all_Rscript_s().

A character string (default 'future') to specify the method for parallel computation. Options include:

• 'future': Uses future::future() along with future.apply::future_lapply() for parallel execution.

• 'foreach': Uses foreach::foreach() with the 'dofuture' function from the doFuture package for parallel execution.

A logical (default NULL) to indicate whether to re-expose Stan functions when future = TRUE. This is especially relevant when future::plan() is set to 'multisession', as already exposed C++ Stan functions cannot be passed across multiple sessions.

• When future_re_expose = NULL (the default), future_re_expose is automatically set to TRUE for the 'multisession' plan.

• It is advised to explicitly set future_re_expose = TRUE for speed gains when using parallel processing with future = TRUE.

A logical (default FALSE) indicating whether to use the dtplyr package for summarizing the draws. This package uses data.table as a back-end. It is useful when the data has a large number of observations. For typical use cases, it does not make a significant performance difference. The usedtplyr argument is evaluated only when method = 'custom'.

A logical (default FALSE) to indicate whether to use the collapse package for summarizing the draws.

The number of cores to be used for parallel computations if future = TRUE. On non-Windows systems, this argument can be set globally via the mc.cores option. By default, NULL, the number of cores is automatically determined using future::availableCores(), and it will use the maximum number of cores available minus one (i.e., future::availableCores() - 1).