GrowthCurveME (version 0.1.0)

growth_curve_model_fit: Fit a growth function using mixed-effects regression modeling

Description

This function fits a mixed-effects model to a data frame based on a user-defined function to account for clustering.

Usage

growth_curve_model_fit(
  data_frame,
  function_type = "exponential",
  model_type = "mixed",
  fixed_rate = TRUE,
  num_chains = 1,
  time_unit = "hours",
  return_summary = TRUE,
  seed = NULL,
  verbose = TRUE
)

Value

A list object with the following data frames within the list:

• model_summary_wide - a data frame with 1 row containing key model estimates, doubling-time, and model metrics depending on the model_type and function_type specified

• model_summary_long - a data frame that is a long dataset version of 'model_summary_wide' that can be used to generate a table of the model results (see function growth_model_summary_table)

• model_residual_data - a data frame containing the original data frame values as well as predicted values, residuals, and theoretical quantiles of the residuals depending on the model_type selected (see functions growth_model_residual_plots and growth_vs_time_plot)

• simulated_data - a data frame with the 95% prediction intervals calculated using the median for the estimate and the 2.5th and 97.5th percentiles of the simulated data at each time point (not to be confused with the 95% confidence intervals calculated from the model estimates). See summarize_growth_model.

Note when return_summary is FALSE, will return a model object of class 'SaemixObject' when a mixed-effects model is specified or a model object of class 'nls' if a least-squares model is specified.

Arguments

data_frame

A data frame object that at minimum contains three variables:

• cluster - a character type variable used to specify how observations are nested or grouped by a particular cluster. Note if using a least-squares model, please fill in cluster values with a single repetitive dummy variable (e.g., '1'), do not leave blank.

• time - a numeric type variable used for measuring time such as minutes, hours, or days

• growth_metric - a numeric type variable used for measuring growth over time such as cell count or confluency

function_type

A character string specifying the function for modeling the shape of the growth. Options include "exponential", "linear", "logistic", or "gompertz".

model_type

A character string specifying the type of regression model to be used. If 'mixed', a mixed-effects regression model will be used with fixed and random-effects to account for clustering. For 'least-squares', a least-squares regression model with only fixed-effects is applied. Defaults to "mixed".

fixed_rate

A logical value specifying whether the rate constant of the function should be treated as a fixed effect (TRUE) or random effect (FALSE). Defaults to TRUE

num_chains

A numeric value specifying the number of chains to run in parallel in the MCMC algorithm of saemix. Increasing the number of chains may improve convergence but may also increase the computational time. Defaults to 1.

time_unit

A character string specifying the units in which time is measured in. Defaults to "hours"

return_summary

A logical value specifying whether to return the growth_model_summary_list when TRUE (list object containing summarized data) or the object model object when FALSE. Defaults to TRUE.

seed

A numeric value specifying a seed number to reproduce the random starting values sampled within the function. Defaults to NULL.

verbose

A logical value specifying whether print statements will print in the console. Defaults to TRUE.

Examples

# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data and return summary
exp_mixed_model_summary <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
verbose = FALSE)
# Create flextable object from the summary list object for documentation
exp_model_table <- growth_model_summary_table(
growth_model_summary_list = exp_mixed_model_summary)
exp_model_table
# Create growth vs time plot of data with fitted values (plot_type = 2),
# adjust aesthetics and parameters as desired
exp_growth_plot <- growth_vs_time_plot(
growth_model_summary_list = exp_mixed_model_summary,
plot_type = 2)
print(exp_growth_plot)
# Check residuals and model assumptions
residual_diag_plot <- growth_model_residual_plots(
growth_model_summary_list = exp_mixed_model_summary)
print(residual_diag_plot)