Help for package GrowthCurveME

Title:

Mixed-Effects Modeling for Growth Data

Version:

0.1.11

Description:

Simple and user-friendly wrappers to the 'saemix' package for performing linear and non-linear mixed-effects regression modeling for growth data to account for clustering or longitudinal analysis via repeated measurements. The package allows users to fit a variety of growth models, including linear, exponential, logistic, and 'Gompertz' functions. For non-linear models, starting values are automatically calculated using initial least-squares estimates. The package includes functions for summarizing models, visualizing data and results, calculating doubling time and other key statistics, and generating model diagnostic plots and residual summary statistics. It also provides functions for generating publication-ready summary tables for reports. Additionally, users can fit linear and non-linear least-squares regression models if clustering is not applicable. The mixed-effects modeling methods in this package are based on Comets, Lavenu, and Lavielle (2017) <doi:10.18637/jss.v080.i03> as implemented in the 'saemix' package. Please contact us at models@dfci.harvard.edu with any questions.

License:

GPL (≥ 3)

Depends:

R (≥ 4.0.0)

Imports:

dplyr (≥ 1.1.4), flextable (≥ 0.9.6), ggplot2 (≥ 3.5.1), investr (≥ 1.4.2), knitr (≥ 1.46), magrittr (≥ 2.0.3), minpack.lm (≥ 1.2-4), moments (≥ 0.14.1), patchwork (≥ 1.2.0), rlang (≥ 1.1.3), saemix (≥ 3.3), stringr (≥ 1.5.1), tibble (≥ 3.2.1), tidyr (≥ 1.3.1), viridis (≥ 0.6.5)

Suggests:

rmarkdown (≥ 2.27), testthat (≥ 3.2.1.1)

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

Config/testthat/edition:

URL:

https://github.com/cancermodels-org/GrowthCurveME

BugReports:

https://github.com/cancermodels-org/GrowthCurveME/issues

NeedsCompilation:

Packaged:

2025-04-10 15:00:43 UTC; Anand

Author:

Anand Panigrahy

[aut, cre], Sonam Bhatia

[ctb], Thomas Quinn [dtc], Aniket Shetty [rev], Keith Ligon

[fnd], Center for Patient-Derived Models Dana-Farber Cancer Institute [cph]

Maintainer:

Anand Panigrahy <anand_panigrahy@dfci.harvard.edu>

Repository:

CRAN

Date/Publication:

2025-04-11 08:20:18 UTC

Sample exponential growth dataset

Description

A dataset containing the minimum required variables needed to input data into the GrowthCurveME package functions

Usage

exp_mixed_data

Format

A data frame with 240 rows and 3 variables:

cluster: A character type variable used to specify the clustering of values by a particular metric. Note even when selecting a least-squares, do not leave this variable NA or empty. Instead fill in these values with a single repetitive dummy variable (e.g., '1') for the package to run properly
time: A numeric type variable for any measurement in time such as minutes, hours, or days
growth_metric: A numeric type variable for measuring growth such as confluency or cell count

Source

Created through simulation to serve as an example

Examples

data(exp_mixed_data)

Fit an exponential mixed-effects regression model

Description

This function is utilized within the growth_curve_model_fit function for fitting a mono-exponential mixed-effects regression model to growth data utilizing the saemix package. Starting values are derived from an initial least-squares model using the nlsLM function.

Usage

exponential_mixed_model(
  data_frame,
  model_type = "mixed",
  fixed_rate = TRUE,
  num_chains = 1,
  seed = NULL
)

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 all values of cluster with a single placeholder character string, 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

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.

seed

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

Value

Returns an exponential 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.

Examples


# Load example data (exponential data from GrowthCurveME package)
data(exp_mixed_data)
# Fit an exponential mixed-effects growth model
exp_mixed_model <- growth_curve_model_fit(
  data_frame = exp_mixed_data,
  function_type = "exponential"
)
# Fit an exponential mixed-effected model using exponential_mixed_model()
exp_mixed_model <- exponential_mixed_model(data_frame = exp_mixed_data)

Sample Gompertz growth dataset

Description

A dataset containing the minimum required variables needed to input data into the GrowthCurveME package functions

Usage

gomp_mixed_data

Format

A data frame with 210 rows and 3 variables:

cluster: A character type variable used to specify the clustering of values by a particular metric. Note even when selecting a least-squares, do not leave this variable NA or empty. Instead fill in these values with a single repetitive dummy variable (e.g., '1') for the package to run properly
time: A numeric type variable for any measurement in time such as minutes, hours, or days
growth_metric: A numeric type variable for measuring growth such as confluency or cell count

Source

Created through simulation to serve as an example

Examples

data(gomp_mixed_data)

Fit a Gompertz mixed-effects regression model

Description

This function is utilized within the growth_curve_model_fit function for fitting a Gompertz mixed-effects regression model to growth data utilizing the saemix package. Starting values are derived from an initial least-squares model using the nlsLM function.

Usage

gompertz_mixed_model(
  data_frame,
  model_type = "mixed",
  fixed_rate = TRUE,
  num_chains = 1,
  seed = NULL
)

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 all values of cluster with a single placeholder character string, 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

model_type

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

seed

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

Value

Returns a Gompertz model object of class 'SaemixObject' if a mixed-effects model is specified or a model object of class 'nls' if a least-squares model is specified.

Examples


# Load example data (Gompertz data from GrowthCurveME package)
data(gomp_mixed_data)
# Fit a Gompertz mixed-effects growth model
gomp_mixed_model <- growth_curve_model_fit(
  data_frame = gomp_mixed_data,
  function_type = "gompertz"
)
# Fit a Gompertz mixed-effected model using gompertz_mixed_model()
gomp_mixed_model <- gompertz_mixed_model(data_frame = gomp_mixed_data)

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
)

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

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

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.

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.

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)

Create residual diagnostic plots for growth model

Description

This function provides a wrapper to ggplot2 for generating residual diagnostic plots and summary statistics for a growth model summary list object produced by growth_curve_model_fit.

Usage

growth_model_residual_plots(
  growth_model_summary_list,
  residual_type = "cluster",
  weighted = TRUE
)

Arguments

growth_model_summary_list

A list object created by the growth_curve_model_fit function.

residual_type

A character string specifying the type of residuals to be displayed in the plot. Options include "population" for the fixed-effects residuals for mixed-effects and least-squares models and "cluster" for fixed and random-effects residuals for mixed-effects regression models. Defaults to "cluster".

weighted

A logical value, when TRUE displays weighted residuals for mixed-effects models or standardized residuals for least-squares models, when FALSE displays the raw residuals for mixed-effects and least-squares models. Defaults to "TRUE".

Value

Returns a patchwork collage of ggplot2 model diagnostic plots with the following plots displayed:

Residual vs Fitted Values - a model diagnostic plot for assessing the distribution of the residuals vs the model fitted values, useful in detecting improper function specification, homogeneity of variance, and outlier detection.
Q-Q Plot - a model diagnostic plot (quantile-quantile) plot for comparing the residuals vs their theoretical quantiles, useful in assessing normality assumptions and outlier detection.
Residual Density Plot - a model diagnostic showing the distribution of the residuals (histogram) with a normal distribution curve overlaid based on the residuals mean and standard deviation, useful in assessing normality assumptions and skewness.
Residual Summary Statistics - a list of descriptive statistics of the the residuals including: mean, median, minimum, maximum, skewness, and kurtosis.

Examples


# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data and produce summary list
exp_mixed_model_summary <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
verbose = FALSE)
# Check residuals and model assumptions
residual_diag_plot <- growth_model_residual_plots(
  growth_model_summary_list = exp_mixed_model_summary)
print(residual_diag_plot)

Create a printable table of the summarized growth model result reporting

Description

This function creates a flextable object that can be used for documentation or Rmarkdown reports from the list object created by growth_curve_model_fit. The 'model_summary_long' data frame from the list object is used to generate the table.

Usage

growth_model_summary_table(
  growth_model_summary_list,
  font_name = "Albany AMT",
  font_size_header = 14,
  font_size_body = 12,
  use_knit_print = FALSE
)

Arguments

growth_model_summary_list

A list object created by the growth_curve_model_fit function.

font_name

A character string specifying the name of the font to use when rendering the table. Defaults to "Albany AMT". See font.

font_size_header

A numeric value specifying the size of the font for the header of the table. Defaults to 14. See fontsize.

font_size_body

A numeric value specifying the size of the font for the body of the table. Defaults to 12. See fontsize.

use_knit_print

A logical value to specify whether the flextable should be printed using knit_print function instead of the flextable object being returned. Defaults to FALSE.

Value

A flextable object of the 'model_summary_long' data frame.

Examples


# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data
exp_mixed_model_summary <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
verbose = FALSE)
# Create flextable object of the growth model results
exp_model_table <- growth_model_summary_table(
growth_model_summary_list = exp_mixed_model_summary)
# Print the table in the view pane
exp_model_table

Generate growth vs time plots

Description

This function provides a wrapper to ggplot2 in order to generate different plots from a growth curve model summary list object generated by the growth_curve_model_fit function. Please refer to the documentation for the 'plot_type' parameter for the different plot options.

Usage

growth_vs_time_plot(
  growth_model_summary_list,
  plot_type = 2,
  growth_metric_name = "growth_metric",
  time_name = "time",
  cluster_name = "cluster",
  plot_title = "Growth vs Time",
  x_axis_breaks = ggplot2::waiver(),
  x_limits = c(NA, NA),
  n_x_axis_breaks = NULL,
  y_axis_breaks = ggplot2::waiver(),
  y_limits = c(NA, NA),
  n_y_axis_breaks = NULL,
  x_axis_text_size = 8,
  y_axis_text_size = 12,
  x_axis_title_size = 14,
  y_axis_title_size = 14,
  plot_title_size = 20,
  geom_point_size = 2,
  geom_line_width = 0.5,
  pred_plot_annotate_value = "double_time",
  annotate_value_text_size = 5
)

Arguments

growth_model_summary_list

A list object created by the growth_curve_model_fit function.

plot_type

A numeric value used to specify the plot type to graph. Values include 1, 2, 3, 4 with descriptions of each below (defaults to 2):

1 - A scatterplot of the growth_metric vs time data where each point is colored by cluster if applicable.
2 - A scatterplot of the growth_metric vs time data where each point is colored by cluster if applicable and the model predicted values are overlayed as line. When a mixed-effect model summary list is input, the predicted values are the ind_fit_value which accounts for both fixed and random-effects. When a least-squares model summary list is input the predicted values are the fitted values accounting for fixed-effects only (pop_fit_value).
3 - A scatterplot version of plot_type = 2 where each cluster is separated into their own plot forming a matrix of growth_metric vs time plots by cluster.
4 - A plot of the estimates and prediction intervals of the model. When a mixed-effects model summary list is input, the prediction intervals are calculated from the median and the 2.5th and 97.5th percentiles of the saemix model simulations to assist in showing the variability of both the population trends and variation among the cluster-level predictions (see compute.sres). When a least-squares model summary list is input, the prediction intervals are calculated through Taylor-series approximations of the nls model (see predFit). By default will also add an annotation of the doubling time with 95% confidence intervals calculated directly from the original model estimates.

growth_metric_name

A character string for specifying the name of the growth metric (y-axis title) to be displayed on the plot. Defaults to "growth_metric".

time_name

A character string for specifying the name of the time variable (x-axis title) to be displayed on the plot. Defaults to "time".

cluster_name

A character string for specifying the name of the cluster variable (legend title) to be displayed on the plot. Defaults to "cluster".

plot_title

A character string for specifying the title to be displayed over the plot. Defaults to "Growth vs Time".

x_axis_breaks

A numeric vector specifying manual numeric breaks. Defaults to ggplot2::waiver(). See scale_x_continuous.

x_limits

A numeric vector of length two providing limits for the x-axis. Use NA to refer to the existing minimum or maximum. Defaults to c(NA, NA). See scale_x_continuous.

n_x_axis_breaks

An integer specifying the number of major breaks for the x-axis. Defaults to NULL. See scale_x_continuous.

y_axis_breaks

A numeric vector specifying manual numeric breaks. Defaults to ggplot2::waiver(). See scale_y_continuous.

y_limits

A numeric vector of length two providing limits for the y-axis. Use NA to refer to the existing minimum or maximum. Defaults to c(NA, NA). See scale_y_continuous.

n_y_axis_breaks

An integer specifying the number of major breaks for the x-axis. Defaults to NULL. See scale_y_continuous.

x_axis_text_size

A numeric value specifying the size of the x-axis text. Defaults to 8. See element_text.

y_axis_text_size

A numeric value specifying the size of the y-axis text. Defaults to 12. See element_text.

x_axis_title_size

A numeric value specifying the size of the x-axis title. Defaults to 14. See element_text.

y_axis_title_size

A numeric value specifying the size of the y-axis title. Defaults to 14. See element_text.

plot_title_size

A numeric value specifying the size of the plot title. Defaults to 20. See element_text.

geom_point_size

A numeric value specifying the size of the points on the graph. Defaults to 2. See geom_point.

geom_line_width

A numeric value specifying the width of the line (applicable only for plot_type = 2, 3, or 4). Defaults to 0.5.

pred_plot_annotate_value

A character string specifying whether to add the doubling time or rate estimates from the model to plot 4. Options include "double_time" for the doubling time with 95% CI, "rate" for the rate estimate with 95% CI, or "none" for no annotation. Defaults to "double_time"

annotate_value_text_size

A numeric value specifying the size of the annotation text. Defaults to 5. See geom_text.

Value

Returns a ggplot2 plot

Examples


# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data
exp_mixed_model_summary <- growth_curve_model_fit(
  data_frame = exp_mixed_data,
  function_type = "exponential",
  verbose = FALSE
)
# Create growth vs time plot of data with fitted values (plot_type = 2)
exp_growth_plot <- growth_vs_time_plot(
  growth_model_summary_list = exp_mixed_model_summary,
  plot_type = 2
)
print(exp_growth_plot)

Sample linear growth dataset

Description

A dataset containing the minimum required variables needed to input data into the GrowthCurveME package functions

Usage

lin_mixed_data

Format

A data frame with 110 rows and 3 variables:

cluster: A character type variable used to specify the clustering of values by a particular metric. Note even when selecting a least-squares, do not leave this variable NA or empty. Instead fill in these values with a single repetitive dummy variable (e.g., '1') for the package to run properly
time: A numeric type variable for any measurement in time such as minutes, hours, or days
growth_metric: A numeric type variable for measuring growth such as confluency or cell count

Source

Created through simulation to serve as an example

Examples

data(lin_mixed_data)

Fit a linear mixed-effects regression model

Description

This function is utilized within the growth_curve_model_fit function for fitting a linear mixed-effects regression model to growth data utilizing the saemix package. Starting values are derived from an initial least-squares model using the nlsLM function.

Usage

linear_mixed_model(
  data_frame,
  model_type = "mixed",
  fixed_rate = TRUE,
  num_chains = 1,
  seed = NULL
)

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 all values of cluster with a single placeholder character string, 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

model_type

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

seed

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

Value

Returns a linear 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.

Examples


# Load example data (linear data from GrowthCurveME package)
data(lin_mixed_data)
# Fit a linear mixed-effects growth model
lin_mixed_model <- growth_curve_model_fit(
data_frame = lin_mixed_data,
function_type = "linear")
# Fit a linear mixed-effects model using linear_mixed_model()
lin_mixed_model <- linear_mixed_model(data_frame = lin_mixed_data)

Sample logistic growth dataset

Description

A dataset containing the minimum required variables needed to input data into the GrowthCurveME package functions

Usage

log_mixed_data

Format

A data frame with 800 rows and 3 variables:

cluster: A character type variable used to specify the clustering of values by a particular metric. Note even when selecting a least-squares, do not leave this variable NA or empty. Instead fill in these values with a single repetitive dummy variable (e.g., '1') for the package to run properly
time: A numeric type variable for any measurement in time such as minutes, hours, or days
growth_metric: A numeric type variable for measuring growth such as confluency or cell count

Source

Created through simulation to serve as an example

Examples

data(log_mixed_data)

Fit a logistic mixed-effects regression model

Description

This function is utilized within the growth_curve_model_fit function for fitting a logistic mixed-effects regression model to growth data utilizing the saemix package. Starting values are derived from an initial least-squares model using the nlsLM function.

Usage

logistic_mixed_model(
  data_frame,
  model_type = "mixed",
  fixed_rate = TRUE,
  num_chains = 1,
  seed = NULL
)

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 all values of cluster with a single placeholder character string, 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

model_type

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

seed

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

Value

Returns a logistic 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.

Examples


# Load example data (logistic data from GrowthCurveME package)
data(log_mixed_data)
# Fit a logistic mixed-effects growth model to the data
log_mixed_model <- growth_curve_model_fit(data_frame = log_mixed_data,
function_type = "logistic")
# Fit a logistic mixed-effects model using logistic_mixed_model()
log_mixed_model <- logistic_mixed_model(data_frame = log_mixed_data)

Summarize growth model object and data

Description

This function is used to create a list object of data frames based on a user's input data and output growth model object from growth_curve_model_fit. The list object (referred to in this package as 'growth_model_summary_list') can be used to extract model predicted values, residuals, and can be inputted into supporting functions from GrowthCurveME to generate plots and perform model diagnostics.

Usage

summarize_growth_model(
  data_frame,
  growth_model_object,
  model_type = "mixed",
  function_type = "exponential",
  fixed_rate = TRUE,
  time_unit = "hours"
)

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

growth_model_object

The model object that is created using the growth_curve_model_fit

model_type

A character string specifying the model_type that was fit using the growth_curve_model_fit function. Options include either "mixed" or "least-squares". Defaults to "mixed".

function_type

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

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

time_unit

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

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)
model_sim_pred_data - a data frame with estimates and 95% prediction intervals (not to be confused with the 95% confidence intervals calculated from the model estimates), for mixed-effects models, values are calculated as the median estimate and the 2.5th and 97.5th percentiles of the simulated data from the saemix model at each time point (see compute.sres and plot with plot.type = "vpc"). For least-squares models, prediction intervals are calculated through Taylor-series approximations using the predFit function.

Examples


# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data
exp_mixed_model <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
return_summary = FALSE)
# Summarize the data by creating a summary list object
exp_mixed_model_summary <- summarize_growth_model(
data_frame = exp_mixed_data,
growth_model_object = exp_mixed_model,
model_type = "mixed",
function_type = "exponential",
time_unit = "hours")
# Extracting a data frame from the list object
model_summary_wide <- exp_mixed_model_summary[["model_summary_wide"]]

Summarize least-squares growth model object and data

Description

This function is used within the summarize_growth_model function to create a list object of data frames based on a user's input data frame and output least-squares growth model object from growth_curve_model_fit. The list object (referred to in this package as 'growth_model_summary_list') can be used to extract model predicted values, residuals, and can be inputted into supporting functions from GrowthCurveME to generate plots and perform model diagnostics.

Usage

summarize_growth_model_ls(
  data_frame,
  ls_model,
  function_type = "exponential",
  time_unit = "hours"
)

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

ls_model

The least-squares model object that is created using the growth_curve_model_fit

function_type

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

time_unit

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

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)
model_sim_pred_data - a data frame with estimates and 95% prediction intervals (not to be confused with the 95% confidence intervals calculated from the model estimates), for mixed-effects models, values are calculated as the median estimate and the 2.5th and 97.5th percentiles of the simulated data from the saemix model at each time point (see compute.sres and plot with plot.type = "vpc"). For least-squares models, prediction intervals are calculated through Taylor-series approximations using the predFit function.

Examples

# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data
exp_ls_model <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
model_type = "least-squares",
return_summary = FALSE)
# Summarize the data by creating a summary list object
exp_ls_model_summary <- summarize_growth_model_ls(
data_frame = exp_mixed_data,
ls_model = exp_ls_model,
function_type = "exponential",
time_unit = "hours")

Summarize mixed-effects growth model object and data

Description

This function is used within the summarize_growth_model function to create a list object of data frames based on a user's input data frame and output mixed-effects growth model object from growth_curve_model_fit. The list object (referred to in this package as 'growth_model_summary_list') can be used to extract model predicted values, residuals, and can be inputted into supporting functions from GrowthCurveME to generate plots and perform model diagnostics.

Usage

summarize_growth_model_mixed(
  data_frame,
  mixed_growth_model,
  function_type = "exponential",
  fixed_rate = TRUE,
  time_unit = "hours"
)

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

mixed_growth_model

The mixed-effects model object that is created using the growth_curve_model_fit

function_type

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

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

time_unit

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

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)
model_sim_pred_data - a data frame with estimates and 95% prediction intervals (not to be confused with the 95% confidence intervals calculated from the model estimates), for mixed-effects models, values are calculated as the median estimate and the 2.5th and 97.5th percentiles of the simulated data from the saemix model at each time point (see compute.sres and plot with plot.type = "vpc"). For least-squares models, prediction intervals are calculated through Taylor-series approximations using the predFit function.

Examples


# Load example data (exponential data)
data(exp_mixed_data)
# Fit an mixed-effects growth model to the data
exp_mixed_model <- growth_curve_model_fit(
data_frame = exp_mixed_data,
function_type = "exponential",
return_summary = FALSE)
# Summarize the data by creating a summary list object
exp_mixed_model_summary <- summarize_growth_model_mixed(
data_frame = exp_mixed_data,
mixed_growth_model = exp_mixed_model,
fixed_rate = TRUE,
function_type = "exponential",
time_unit = "hours")
model_summary_wide <- exp_mixed_model_summary[["model_summary_wide"]]

Sample exponential growth dataset

Description

Usage

Format

Source

Examples

Fit an exponential mixed-effects regression model

Description

Usage

Arguments

Value

See Also

Examples

Sample Gompertz growth dataset

Description

Usage

Format

Source

Examples

Fit a Gompertz mixed-effects regression model

Description

Usage

Arguments

Value

See Also

Examples

Fit a growth function using mixed-effects regression modeling

Description

Usage

Arguments

Value

Examples

Create residual diagnostic plots for growth model

Description

Usage

Arguments

Value

See Also

Examples

Create a printable table of the summarized growth model result reporting

Description

Usage

Arguments

Value

See Also

Examples

Generate growth vs time plots

Description

Usage

Arguments

Value

See Also

Examples

Sample linear growth dataset

Description

Usage

Format

Source

Examples

Fit a linear mixed-effects regression model

Description

Usage

Arguments

Value

See Also

Examples

Sample logistic growth dataset

Description

Usage

Format

Source

Examples

Fit a logistic mixed-effects regression model

Description

Usage

Arguments

Value

See Also

Examples

Summarize growth model object and data