growthparameters.bgmfit {bsitar} | R Documentation |
Estimate Growth Parameters from the Model Fit
Description
The growthparameters() function estimates both
population-average and individual-specific growth parameters (e.g., age at
peak growth velocity). It also provides measures of uncertainty, including
standard errors (SE) and credible intervals (CIs). For a more advanced
analysis, consider using the growthparameters_comparison()
function,
which not only estimates adjusted parameters but also enables comparisons
of these parameters across different groups.
Usage
## S3 method for class 'bgmfit'
growthparameters(
model,
newdata = NULL,
resp = NULL,
dpar = NULL,
ndraws = NULL,
draw_ids = NULL,
summary = FALSE,
robust = FALSE,
transform = NULL,
re_formula = NA,
peak = TRUE,
takeoff = FALSE,
trough = FALSE,
acgv = FALSE,
acgv_velocity = 0.1,
estimation_method = "fitted",
allow_new_levels = FALSE,
sample_new_levels = "uncertainty",
incl_autocor = TRUE,
numeric_cov_at = NULL,
levels_id = NULL,
avg_reffects = NULL,
aux_variables = NULL,
ipts = 10,
deriv_model = TRUE,
conf = 0.95,
xrange = NULL,
xrange_search = NULL,
digits = 2,
seed = 123,
future = FALSE,
future_session = "multisession",
cores = NULL,
parms_eval = FALSE,
idata_method = NULL,
parms_method = "getPeak",
verbose = FALSE,
fullframe = NULL,
dummy_to_factor = NULL,
expose_function = FALSE,
usesavedfuns = NULL,
clearenvfuns = NULL,
funlist = NULL,
envir = NULL,
...
)
growthparameters(model, ...)
Arguments
model |
An object of class |
newdata |
An optional data frame for estimation. If |
resp |
A character string (default |
dpar |
Optional name of a predicted distributional parameter. If specified, expected predictions of this parameters are returned. |
ndraws |
A positive integer indicating the number of posterior draws to
use in estimation. If |
draw_ids |
An integer specifying the specific posterior draw(s) to use
in estimation (default |
summary |
A logical value indicating whether only the estimate should be
computed ( |
robust |
A logical value to specify the summary options. If |
transform |
A function applied to individual draws from the posterior
distribution before computing summaries. The argument |
re_formula |
Option to indicate whether or not to include
individual/group-level effects in the estimation. When |
peak |
A logical value (default |
takeoff |
A logical value (default |
trough |
A logical value (default |
acgv |
A logical value (default |
acgv_velocity |
The percentage of the peak growth velocity to use when
estimating |
estimation_method |
A character string specifying the estimation method
when calculating the velocity from the posterior draws. The |
allow_new_levels |
A flag indicating if new levels of group-level
effects are allowed (defaults to |
sample_new_levels |
Indicates how to sample new levels for grouping
factors specified in |
incl_autocor |
A flag indicating if correlation structures originally
specified via |
numeric_cov_at |
An optional (named list) argument to specify the value
of continuous covariate(s). The default |
levels_id |
An optional argument to specify the |
avg_reffects |
An optional argument (default |
aux_variables |
An optional argument to specify the variable(s) that can
be passed to the |
ipts |
An integer to set the length of the predictor variable for
generating a smooth velocity curve. If |
deriv_model |
A logical value specifying whether to estimate the
velocity curve from the derivative function or by differentiating the
distance curve. Set |
conf |
A numeric value (default |
xrange |
An integer to set the predictor range (e.g., age) when
executing the interpolation via |
xrange_search |
A vector of length two or a character string
|
digits |
An integer (default |
seed |
An integer (default |
future |
A logical value (default |
future_session |
A character string specifying the session type when
|
cores |
The number of cores to be used for parallel computations if
|
parms_eval |
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. |
idata_method |
A character string to indicate the interpolation method.
The number of interpolation points is set by the
|
parms_method |
A character string specifying the method used when
evaluating |
verbose |
A logical argument (default |
fullframe |
A logical value indicating whether to return a
|
dummy_to_factor |
A named list (default
|
expose_function |
A logical argument (default |
usesavedfuns |
A logical value (default |
clearenvfuns |
A logical value indicating whether to clear the exposed
Stan functions from the environment ( |
funlist |
A list (default |
envir |
The environment used for function evaluation. The default is
|
... |
Additional arguments passed to the |
Details
The growthparameters() function internally calls either the
fitted_draws()
or the predict_draws()
function to estimate
first-derivative growth parameters for each posterior draw. The estimated
growth parameters include:
Age at Peak Growth Velocity (APGV)
Peak Growth Velocity (PGV)
Age at Takeoff Growth Velocity (ATGV)
Takeoff Growth Velocity (TGV)
Age at Cessation of Growth Velocity (ACGV)
Cessation Growth Velocity (CGV)
APGV and PGV are estimated using the sitar::getPeak()
function, while
ATGV and TGV are estimated using the sitar::getTakeoff()
function. The
sitar::getTrough()
function is employed to estimate ACGV and CGV. The
parameters from each posterior draw are then summarized to provide
estimates along with uncertainty measures (SEs and CIs).
Please note that estimating cessation and takeoff growth parameters may not be possible if there are no distinct pre-peak or post-peak troughs in the data.
Value
A data frame with either five columns (when summary = TRUE
) or
two columns (when summary = FALSE
, assuming re_formual =
NULL
). The first two columns, common to both scenarios, are
'Parameter'
and 'Estimate'
, representing the growth parameter
(e.g., APGV, PGV) and its estimate. When summary = TRUE
, three
additional columns are included: 'Est.Error'
and two columns
representing the lower and upper bounds of the confidence intervals, named
Q.2.5
and Q.97.5
(for the 95% CI). If re_formual =
NULL
, an additional column with individual identifiers (e.g., id
)
is included.
Author(s)
Satpal Sandhu satpal.sandhu@bristol.ac.uk
Examples
# Fit Bayesian SITAR Model
# To avoid mode estimation, which takes time, the Bayesian SITAR model fit
# to the 'berkeley_exdata' has been saved as an example fit ('berkeley_exfit').
# See 'bsitar' function for details on 'berkeley_exdata' and 'berkeley_exfit'.
# Check if the model fit object 'berkeley_exfit' exists and load it
berkeley_exfit <- getNsObject(berkeley_exfit)
model <- berkeley_exfit
# Population average age and velocity during the peak growth spurt
growthparameters(model, re_formula = NA)
# Population average age and velocity during the take-off and peak
# growth spurt (APGV, PGV, ATGV, TGV)
growthparameters(model, re_formula = NA, peak = TRUE, takeoff = TRUE)
# Individual-specific age and velocity during the take-off and peak
# growth spurt (APGV, PGV, ATGV, TGV)
growthparameters(model, re_formula = NULL, peak = TRUE, takeoff = TRUE)