lmmModel: Linear Mixed Effect Model for Tumor Growth
In SynergyLMM: Statistical Framework for in Vivo Drug Combination Studies
lmmModel R Documentation
Linear Mixed Effect Model for Tumor Growth
Description
lmmModel() fits a 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,
grwth_model = "exp",
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",
start_values = c(0.05, 0.01),
...
)
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).
grwth_model
Tumor growth model to use. Possible options are "exp", for exponential tumor growth model, or "gompertz" for Gompertz tumor growth model.
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.
start_values
Numeric vector of length 2 with initial estimates for the fixed effects of the Gompertz model (r_0, \rho). It can be set
to "selfStart", in which case initial values will be derived from a Gompertz model derived from a call to stats::nls
...
Additional arguments to be passed to nlme::lme or nlme::nlme.
Details
lmmModel() fits a mixed effect model describing the tumor growth. Currently, two growth kinetics models are available: exponential growth, and Gompertz growth.
Exponential
lmmModel() will fit a linear mixed-effect model (LMM) assuming that the 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 LMM following the exponential tumor growth is:
\log RTV_{i}(t) = \beta_{T_i} \cdot t + b_i \cdot t + \varepsilon_{i} (t).
-
\log RTV_{i}(t) denotes the value of the logarithm of the relative tumor volume measured for subject i at time t.
-
\beta_{T_i} represents the fixed effects 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.
-
b_i \cdot t corresponds to the subject-specific random slope that takes into account the longitudinal nature of the data, where b_i \sim \mathcal{N}(0,\sigma^2_b) is the random effect for subject i.
-
\varepsilon_{i}(t) \sim \mathcal{N}(0,\sigma^2) is the residual error term.
Gompertz
lmmModel() will fit a non-linear mixed effect (NLME) model assuming the tumor growth follows a Gompertz growth kinetics. Any departure from this assumption can be tested using the diagnostics functions ranefDiagnostics(),
residDiagnostics(), and ObsvsPred().
The model formula for the non-linear mixed-effect model following the Gompertz tumor growth is:
\log RTV_{i}(t) = \frac{r_{0_{T_i}}+b_{0_i}}{\rho_{T_i}+b_{1_i}}(1-e^{-(\rho_{T_i}+b_{1_i})\cdot t})+\varepsilon_{i}(t).
-
\log RTV_{i}(t) denotes the value of the logarithm of the relative tumor volume measured for subject i at time t.
-
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,
indicates the treatment groupt of individual i.
-
r_{0_{T_i}} is the fixed effect for the initial growth rate for treatment group T_i.
-
\rho_{T_i} is the fixed effect for the constant accounting for the reduction in the tumor growth rate for treatment group T_i.
-
b_{0_i} \sim \mathcal{N}(0,\sigma^2_{{r_0}}) is the random effect on r_0 for individual i.
-
b_{1_i} \sim \mathcal{N}(0,\sigma^2_{{\rho}}) is the random effect on \rho for individual i.
-
\varepsilon_{i}(t) \sim \mathcal{N}(0,\sigma^2) is the residual error term.
The implementation of the linear mixed model in lmmModel() is done using nlme::lme for the exponential model, or nlme::nlme
for the Gompertz model. Both also allow for the
specification of within-group correlations structures and/or unequal variances. These, and additional parameters,
can be passed to the nlme::lme or nlme::nlme functions through the ... argument for fitting the model (see examples below).
Value
An object of class "lme" (see nlme::lme for details) or "nlme" (see nlme::nlme 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
See Also
nlme::lmeControl, nlme::nlmeControl,
nlme::varClasses.
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)
)
# Fit a model using the Gompertz model
lmmModel(
data = grwth_data,
grwth_model = "gompertz", # Selecting Gompertz model
start_values = "selfStart", # Using self-starting values
sample_id = "subject",
time = "Time",
treatment = "Treatment",
tumor_vol = "TumorVolume",
trt_control = "Control",
drug_a = "DrugA",
drug_b = "DrugB",
combination = "Combination"
)
SynergyLMM documentation built on Aug. 22, 2025, 5:11 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| lmmModel | R Documentation |
Linear Mixed Effect Model for Tumor Growth
Description
lmmModel() fits a 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,
grwth_model = "exp",
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",
start_values = c(0.05, 0.01),
...
)
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). |
grwth_model |
Tumor growth model to use. Possible options are "exp", for exponential tumor growth model, or "gompertz" for Gompertz tumor growth model. |
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_end |
Numeric value indicating the last time point to be included in the analysis. If not
specified, the maximum value in the |
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. |
start_values |
Numeric vector of length 2 with initial estimates for the fixed effects of the Gompertz model ( |
... |
Additional arguments to be passed to |
Details
lmmModel() fits a mixed effect model describing the tumor growth. Currently, two growth kinetics models are available: exponential growth, and Gompertz growth.
Exponential
lmmModel() will fit a linear mixed-effect model (LMM) assuming that the 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 LMM following the exponential tumor growth is:
\log RTV_{i}(t) = \beta_{T_i} \cdot t + b_i \cdot t + \varepsilon_{i} (t).
-
\log RTV_{i}(t)denotes the value of the logarithm of the relative tumor volume measured for subjectiat timet. -
\beta_{T_i}represents the fixed effects for each treatmentT_i, whereT_i \in \{Control, DrugA, DrugB, Combination\}in the case of two-drugs combination experiments, orT_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. -
b_i \cdot tcorresponds to the subject-specific random slope that takes into account the longitudinal nature of the data, whereb_i \sim \mathcal{N}(0,\sigma^2_b)is the random effect for subjecti. -
\varepsilon_{i}(t) \sim \mathcal{N}(0,\sigma^2)is the residual error term.
Gompertz
lmmModel() will fit a non-linear mixed effect (NLME) model assuming the tumor growth follows a Gompertz growth kinetics. Any departure from this assumption can be tested using the diagnostics functions ranefDiagnostics(),
residDiagnostics(), and ObsvsPred().
The model formula for the non-linear mixed-effect model following the Gompertz tumor growth is:
\log RTV_{i}(t) = \frac{r_{0_{T_i}}+b_{0_i}}{\rho_{T_i}+b_{1_i}}(1-e^{-(\rho_{T_i}+b_{1_i})\cdot t})+\varepsilon_{i}(t).
-
\log RTV_{i}(t)denotes the value of the logarithm of the relative tumor volume measured for subjectiat timet. -
T_i \in \{Control, DrugA, DrugB, Combination\}in the case of two-drugs combination experiments, orT_i \in \{Control, DrugA, DrugB, DrugC, Combination\}in the case of three-drugs combination experiments, indicates the treatment groupt of individuali. -
r_{0_{T_i}}is the fixed effect for the initial growth rate for treatment groupT_i. -
\rho_{T_i}is the fixed effect for the constant accounting for the reduction in the tumor growth rate for treatment groupT_i. -
b_{0_i} \sim \mathcal{N}(0,\sigma^2_{{r_0}})is the random effect onr_0for individuali. -
b_{1_i} \sim \mathcal{N}(0,\sigma^2_{{\rho}})is the random effect on\rhofor individuali. -
\varepsilon_{i}(t) \sim \mathcal{N}(0,\sigma^2)is the residual error term.
The implementation of the linear mixed model in lmmModel() is done using nlme::lme for the exponential model, or nlme::nlme
for the Gompertz model. Both also allow for the
specification of within-group correlations structures and/or unequal variances. These, and additional parameters,
can be passed to the nlme::lme or nlme::nlme functions through the ... argument for fitting the model (see examples below).
Value
An object of class "lme" (see nlme::lme for details) or "nlme" (see nlme::nlme 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
See Also
nlme::lmeControl, nlme::nlmeControl,
nlme::varClasses.
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)
)
# Fit a model using the Gompertz model
lmmModel(
data = grwth_data,
grwth_model = "gompertz", # Selecting Gompertz model
start_values = "selfStart", # Using self-starting values
sample_id = "subject",
time = "Time",
treatment = "Treatment",
tumor_vol = "TumorVolume",
trt_control = "Control",
drug_a = "DrugA",
drug_b = "DrugB",
combination = "Combination"
)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.