lmmModel: Linear Mixed Effect Model for Tumor Growth

View source: R/lmmModel.R

lmmModelR Documentation

Linear Mixed Effect Model for Tumor Growth

Description

lmmModel() fits a linear mixed effect model from a tumor growth dataset. The input data frame must be in long format and include at least the following columns: column with the sample ids, column with the time at which each measurement has been done, a column indicating the treatment group, and a column with the tumor measurement (e.g. tumor volume).

Usage

lmmModel(
  data,
  sample_id = "SampleID",
  time = "Time",
  treatment = "Treatment",
  tumor_vol = "TV",
  trt_control = "Control",
  drug_a = "Drug_A",
  drug_b = "Drug_B",
  drug_c = NA,
  combination = "Combination",
  time_start = NULL,
  time_end = NULL,
  min_observations = 1,
  show_plot = TRUE,
  tum_vol_0 = "ignore",
  ...
)

Arguments

data

A data frame with the tumor growth data, in long format. It must contain at least the following columns: mice IDs, time of follow-up (numeric number), treatment and tumor volume (numeric number).

sample_id

String indicating the name of the column with the mice IDs.

time

String indicating the name of the column with the time of follow-up.

treatment

String indicating the name of the column with the treatment corresponding to each sample.

tumor_vol

String indicating the name of the column with the tumor volume (or any other measurement representing the tumor growth).

trt_control

String indicating the name assigned to the 'Control' group.

drug_a

String indicating the name assigned to the 'Drug A' group.

drug_b

String indicating the name assigned to the 'Drug B' group.

drug_c

String indicating the name assigned to the 'Drug C' group (if present).

combination

String indicating the name assigned to the Combination ('Drug A' + 'Drug B', or 'Drug A' + 'Drug B' + 'Drug C') group.

time_start

Numeric value indicating the time point at which the treatment started. If not specified, the minimum value in the time column is used as the starting time point.

time_end

Numeric value indicating the last time point to be included in the analysis. If not specified, the maximum value in the time column is used as the final time point.

min_observations

Minimum number of observation for each sample to be included in the analysis.

show_plot

Logical indicating if a plot for the log of the relative tumor volume (RTV) vs Time for each sample, and the model calculated marginal slope for each treatment, should be produced.

tum_vol_0

Select the behavior of the function regarding measurements in which the tumor measurement is 0, and therefore the logarithmic transformation is not possible. Possible options are 'ignore' (default), to ignore these measurements, or 'transform', to add 1 unit to all measurements before the log transformation.

...

Additional arguments to be passed to nlme::lme.

Details

lmmModel() relies in the assumption that tumor growth follows an exponential kinetics. Any departure from this assumption can be tested using the diagnostics functions ranefDiagnostics(), residDiagnostics(), and ObsvsPred().

The model formula for the linear mixed-effect fitted model is:

\log RTV_{i}(t) = \beta_{T_i} \cdot t + b_i \cdot t + \varepsilon_{i} (t).

where \log RTV_{i}(t) denotes the value of the logarithm of the relative tumor volume measured for subject i at time t. The coefficient \beta_{T_i} represents the fixed effectsat time t for each treatment T_i, where T_i \in \{Control, DrugA, DrugB, Combination\} in the case of two-drugs combination experiments, or T_i \in \{Control, DrugA, DrugB, DrugC, Combination\} in the case of three-drugs combination experiments, and indicates the tumor-specific growth rate for each treatment group.

Term b_i \cdot t corresponds to the subject-specific random slope that takes into account the longitudinal nature of the data, where b_i is the random effect for subject i. \varepsilon_{i}(t) is the residual random term for subject i at time t.

The implementation of the linear mixed model in lmmModel() is done using nlme::lme, which also allows for the specification of within-group correlations structures and/or unequal variances. These, and additional parameters, can be passed to the nlme::lme function through the ... argument for fitting the model (see examples below).

Value

An object of class "lme" (see nlme::lme for details) representing the linear mixed-effects model fit. If show_plot = TRUE, the plot of the tumor growth data obtained with plot_lmmModel() is also shown.

References

  • Pinheiro JC, Bates DM (2000). Mixed-Effects Models in S and S-PLUS. Springer, New York. doi:10.1007/b98882 \Sexpr[results=rd]{tools:::Rd_expr_doi("doi:10.1007/b98882")}.

  • Pinheiro J, Bates D, R Core Team (2024). nlme: Linear and Nonlinear Mixed Effects Models. R package version 3.1-166, https://CRAN.R-project.org/package=nlme.

  • Andrzej Galecki & Tomasz Burzykowski (2013) Linear Mixed-Effects Models Using R: A Step-by-Step Approach First Edition. Springer, New York. ISBN 978-1-4614-3899-1

Examples

data("grwth_data")
# Most simple model
lmmModel(
 data = grwth_data,
 sample_id = "subject",
 time = "Time",
 treatment = "Treatment",
 tumor_vol = "TumorVolume",
 trt_control = "Control",
 drug_a = "DrugA",
 drug_b = "DrugB",
 combination = "Combination"
 )
# Changing the last time point of follow-up
lmmModel(
 data = grwth_data,
 sample_id = "subject",
 time = "Time",
 treatment = "Treatment",
 tumor_vol = "TumorVolume",
 trt_control = "Control",
 drug_a = "DrugA",
 drug_b = "DrugB",
 combination = "Combination",
 time_end = 21
 )
# Adding additional parameters for model fitting
lmmModel(
 data = grwth_data,
 sample_id = "subject",
 time = "Time",
 treatment = "Treatment",
 tumor_vol = "TumorVolume",
 trt_control = "Control",
 drug_a = "DrugA",
 drug_b = "DrugB",
 combination = "Combination",
 # Adding variance function to represent a different variance per subject
 weights = nlme::varIdent(form = ~1|SampleID),
 # Specifiying control values for lme Fit (useful when convergence problems appear)
 control = nlme::lmeControl(maxIter = 1000, msMaxIter = 1000, niterEM = 100, msMaxEval = 1000)
 )

# Fit a model specifying a different variance per Time
lmmModel(
 data = grwth_data,
 sample_id = "subject",
 time = "Time",
 treatment = "Treatment",
 tumor_vol = "TumorVolume",
 trt_control = "Control",
 drug_a = "DrugA",
 drug_b = "DrugB",
 combination = "Combination",
 # Adding variance function to represent a different variance per Time
 weights = nlme::varIdent(form = ~1|Time)
 )




SynergyLMM documentation built on April 4, 2025, 4:13 a.m.