plot_curves.bgmfit {bsitar} | R Documentation |
Plot Growth Curves
Description
The plot_curves() function visualizes six different
types of growth curves using the ggplot2 package. Additionally, it
allows users to create customized plots from the data returned as a
data.frame
. For an alternative approach, the marginal_draws()
function can be used, which not only estimates adjusted curves but also
enables comparison across groups using the hypotheses
argument.
Usage
## S3 method for class 'bgmfit'
plot_curves(
model,
opt = "dv",
apv = FALSE,
bands = NULL,
conf = 0.95,
resp = NULL,
dpar = NULL,
ndraws = NULL,
draw_ids = NULL,
newdata = NULL,
summary = FALSE,
digits = 2,
re_formula = NULL,
numeric_cov_at = NULL,
aux_variables = NULL,
levels_id = NULL,
avg_reffects = NULL,
ipts = 10,
deriv_model = TRUE,
xrange = NULL,
xrange_search = NULL,
takeoff = FALSE,
trough = FALSE,
acgv = FALSE,
acgv_velocity = 0.1,
seed = 123,
estimation_method = "fitted",
allow_new_levels = FALSE,
sample_new_levels = "uncertainty",
incl_autocor = TRUE,
robust = FALSE,
transform = NULL,
future = FALSE,
future_session = "multisession",
cores = NULL,
trim = 0,
layout = "single",
linecolor = NULL,
linecolor1 = NULL,
linecolor2 = NULL,
label.x = NULL,
label.y = NULL,
legendpos = NULL,
linetype.apv = NULL,
linewidth.main = NULL,
linewidth.apv = NULL,
linetype.groupby = NA,
color.groupby = NA,
band.alpha = NULL,
show_age_takeoff = TRUE,
show_age_peak = TRUE,
show_age_cessation = TRUE,
show_vel_takeoff = FALSE,
show_vel_peak = FALSE,
show_vel_cessation = FALSE,
returndata = FALSE,
returndata_add_parms = FALSE,
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,
...
)
plot_curves(model, ...)
Arguments
model |
An object of class |
opt |
A character string containing one or more of the following plotting options:
Note that 'd' and 'D' cannot be specified simultaneously, nor can 'v' and 'V'. Other combinations are allowed, e.g., 'dvau', 'Dvau', 'dVau', etc. |
apv |
A logical value (default |
bands |
A character string containing one or more of the following
options, or
The |
conf |
A numeric value (default |
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 |
newdata |
An optional data frame for estimation. If |
summary |
A logical value indicating whether only the estimate should be
computed ( |
digits |
An integer (default |
re_formula |
Option to indicate whether or not to include
individual/group-level effects in the estimation. When |
numeric_cov_at |
An optional (named list) argument to specify the value
of continuous covariate(s). The default |
aux_variables |
An optional argument to specify variables passed to the
|
levels_id |
An optional argument to specify the |
avg_reffects |
An optional argument (default |
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 |
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
|
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 |
seed |
An integer (default |
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 |
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 |
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
|
trim |
A numeric value (default |
layout |
A character string defining the plot layout. The default
|
linecolor |
The color of the lines when the layout is |
linecolor1 |
The color of the first line when the layout is
|
linecolor2 |
The color of the second line when the layout is
|
label.x |
An optional character string to label the x-axis. If
|
label.y |
An optional character string to label the y-axis. If
|
legendpos |
A character string to specify the position of the legend. If
|
linetype.apv |
A character string to specify the type of the vertical
line marking the APGV. Default |
linewidth.main |
A numeric value to specify the line width for distance
and velocity curves. The default |
linewidth.apv |
A numeric value to specify the width of the vertical
line marking the APGV. The default |
linetype.groupby |
A character string specifying the line type for
distance and velocity curves when drawing plots for a model with factor
covariates or individual-specific curves. The default is |
color.groupby |
A character string specifying the line color for
distance and velocity curves when drawing plots for a model with factor
covariates or individual-specific curves. The default is |
band.alpha |
A numeric value to specify the transparency of the CI bands
around the curves. The default |
show_age_takeoff |
A logical value (default |
show_age_peak |
A logical value (default |
show_age_cessation |
A logical value (default |
show_vel_takeoff |
A logical value (default |
show_vel_peak |
A logical value (default |
show_vel_cessation |
A logical value (default |
returndata |
A logical value (default |
returndata_add_parms |
A logical value (default |
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 plot_curves() function is a generic tool for visualizing the following six curves:
Population average distance curve
Population average velocity curve
Individual-specific distance curves
Individual-specific velocity curves
Unadjusted individual growth curves (i.e., observed growth curves)
Adjusted individual growth curves (adjusted for the model-estimated random effects)
Internally, plot_curves() calls the growthparameters()
function
to estimate and summarize the distance and velocity curves, as well as to
compute growth parameters such as the age at peak growth velocity (APGV).
The function also calls fitted_draws()
or predict_draws()
to make
inferences based on posterior draws. As a result, plot_curves()
can plot either fitted or predicted curves. For more details, see
fitted_draws()
and predict_draws()
to understand the difference between
fitted and predicted values.
Value
A plot object (default) or a data.frame
when returndata
= TRUE
.
Author(s)
Satpal Sandhu satpal.sandhu@bristol.ac.uk
See Also
growthparameters()
fitted_draws()
predict_draws()
Examples
# Fit Bayesian SITAR model
# To avoid mode estimation which takes time, the Bayesian SITAR model is fit to
# the 'berkeley_exdata' and saved as an example fit ('berkeley_exfit').
# See 'bsitar' function for details on 'berkeley_exdata' and 'berkeley_exfit'.
# Check and confirm whether the model fit object 'berkeley_exfit' exists
berkeley_exfit <- getNsObject(berkeley_exfit)
model <- berkeley_exfit
# Population average distance and velocity curves with default options
plot_curves(model, opt = 'dv')
# Individual-specific distance and velocity curves with default options
# Note that \code{legendpos = 'none'} will suppress the legend positions.
# This suppression is useful when plotting individual-specific curves
plot_curves(model, opt = 'DV')
# Population average distance and velocity curves with APGV
plot_curves(model, opt = 'dv', apv = TRUE)
# Individual-specific distance and velocity curves with APGV
plot_curves(model, opt = 'DV', apv = TRUE)
# Population average distance curve, velocity curve, and APGV with CI bands
# To construct CI bands, growth parameters are first calculated for each
# posterior draw and then summarized across draws. Therefore,summary
# option must be set to FALSE
plot_curves(model, opt = 'dv', apv = TRUE, bands = 'dvp', summary = FALSE)
# Adjusted and unadjusted individual curves
# Note ipts = NULL (i.e., no interpolation of predictor (i.e., age) to plot a
# smooth curve). This is because it does not a make sense to interploate data
# when estimating adjusted curves. Also, layout = 'facet' (and not default
# layout = 'single') is used for the ease of visualizing the plotted
# adjusted and unadjusted individual curves. However, these lines can be
# superimposed on each other by setting the set layout = 'single'.
# For other plots shown above, layout can be set as 'single' or 'facet'
# Separate plots for adjusted and unadjusted curves (layout = 'facet')
plot_curves(model, opt = 'au', ipts = NULL, layout = 'facet')
# Superimposed adjusted and unadjusted curves (layout = 'single')
plot_curves(model, opt = 'au', ipts = NULL, layout = 'single')