Type: | Package |
Title: | Mixed Effect Model with the Box-Cox Transformation |
Version: | 0.1.5 |
Description: | Inference on the marginal model of the mixed effect model with the Box-Cox transformation and on the model median differences between treatment groups for longitudinal randomized clinical trials. These statistical methods are proposed by Maruo et al. (2017) <doi:10.1002/sim.7279>. |
Depends: | R (≥ 3.3.3) |
Imports: | MASS (≥ 7.3-45), nlme (≥ 3.1-131) |
Suggests: | testthat (≥ 1.0.2) |
License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
Encoding: | UTF-8 |
LazyData: | true |
RoxygenNote: | 7.3.2 |
NeedsCompilation: | no |
Packaged: | 2025-04-11 23:20:36 UTC; kazus |
Author: | Kazushi Maruo [aut, cre], Ryota Ishii [aut], Yusuke Yamaguchi [ctb], Masahiko Gosho [ctb] |
Maintainer: | Kazushi Maruo <kazushi.maruo@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2025-04-11 23:40:02 UTC |
bcmixed: Mixed Effect Model with the Box-Cox Transformation
Description
Inference on the marginal model of the mixed effect model with the Box-Cox transformation and on the model median differences between treatment groups for longitudinal randomized clinical trials. These statistical methods are proposed by Maruo et al. (2017) doi:10.1002/sim.7279.
Author(s)
Maintainer: Kazushi Maruo kazushi.maruo@gmail.com
Authors:
Ryota Ishii
Other contributors:
Yusuke Yamaguchi [contributor]
Masahiko Gosho [contributor]
CD4 Cells Count Data in Aids Randomized Controlled Clinical Trial.
Description
The data are from a randomized, double-blind study of acquired immune deficiency syndrome (AIDS) patients with advanced immune suppression (cluster of differentiation 4 (CD4) cells count of less than or equal to 50 cells/mm3) (Henry et al., 1998; Fitzmaurice et al., 2011). Patients in the AIDS Clinical Trial Group Study 193A were randomized to dual or triple combinations of human immunodeficiency virus-1 reverse transcriptase inhibitors. Specifically, patients were randomized to one of four daily regimens.
Format
A data frame with 4708 observations on the following 7 variables:
id
patient identifier; in total there are 1177 patients.
weekc
nominal visit variable (weeks 8, 16, 24, 32).
treatment
allocated treatment regimens; 1 = zidovudine alternating monthly with 400mg didanosine, 2 = zidovudine plus 2.25mg of zalcitabine, 3 = zidovudine plus 400mg of didanosine, and 4 = zidovudine plus 400mg of didanosine plus 400mg of nevirapine.
age
patients' age (years).
sex
patients' sex (1 = male, 0 = female)
cd4.bl
baseline value of CD4 cells count + 1.
cd4
CD4 cells count + 1.
Source
https://content.sph.harvard.edu/fitzmaur/ala2e/
References
Henry, K., Erice, A., Tierney, C., Balfour, H.H. Jr., Fischl, M.A., Kmack, A., Liou, S.H., Kenton, A., Hirsch, M.S., Phair, J., Martinez, A., Kahn, J.O., for the AIDS Clinical Trial Group 193A Study Team. (1998). A randomized, controlled, double-blind study comparing the survival benefit of four different reverse transcriptase inhibitor therapies (three-drug, two-drug, and alternating drug) for the treatment of advanced AIDS. Journal of Acquired Immune Deficiency Syndromes and Human Retrovirology, 19, 339-349, doi:10.1097/00042560-199812010-00004.
Fitzmaurice, G.M., Laird, N.M., and Ware, J.H. (2011). Applied Longitudinal Analysis 2nd ed., Wiley, New York, doi:10.1002/9781119513469.
Examples
data(aidscd4)
Marginal Model of the Mixed Effect Model with the Box-Cox Transformation.
Description
bcmarg
returns the inference results the parameters of
the marginal model of the linear mixed effect model with the Box-Cox
transformation proposed by Maruo et al. (2017). If time and id are not
specified, inference results reduce to the results for the context of
linear regression model provided by Maruo et al. (2015).
Usage
bcmarg(
formula,
data,
time = NULL,
id = NULL,
structure = "UN",
lmdint = c(-3, 3)
)
Arguments
formula |
a two-sided linear formula object describing the model, with the response on the left of a ~ operator and the terms, separated by + operators, on the right. |
data |
a data frame containing the variables used in the model. |
time |
time variable name for repeated measurements. The default is NULL. |
id |
subject id variable name for repeated measurements. The default is NULL. |
structure |
specify the covariance structure from c("UN", "CS", "AR(1)"). The default is "UN". |
lmdint |
a vector containing the end-points of the interval to be searched for a transformation parameter. The default is c(-3, 3). |
Value
an object of class "bcmarg
". Objects of this class have
methods for the generic functions coef
, logLik
,
print
, and summary
. The object includes following components
for the marginal model parameter inference:
lambda
a numeric value of the estimate of the transformation parameter.
beta
a vector with the estimates of the regression parameters.
alpha
a vector with the estimates of the covariance parameters.
V
variance-covariance matrix for any subject with no missing values.
betainf
a matrix containing the inference results for
beta
under the assumption that lambda is known. Note that standard errors might be underestimated although statistical tests would be asymptotically valid.Vtheta.mod
model-based variance-covariance matrix for MLE of the vector of all parameters:
c(lambda, beta, alpha)
.Vtheta.rob
robust variance-covariance matrix for MLE of the vector of all parameters.
logLik
a numeric value of the maximized likelihood.
adj.prm
a vector with parameters used for the empirical small sample adjustment in
bcmmrm
: c(number of subjects, number of completed subjects, number of outcome observations, number of missing observations).glsObject
an object of "
gls
" (or "lm
" whentime
andid
are not specified) containing results ofgls
(orlm
) function on the transformed scale.
References
Maruo, K., Isogawa, N., Gosho, M. (2015). Inference of median difference based on the Box-Cox model in randomized clinical trials. Statistics in Medicine, 34, 1634-1644, doi:10.1002/sim.6408.
Maruo, K., Yamaguchi, Y., Noma, H., Gosho, M. (2017). Interpretable inference on the mixed effect model with the Box-Cox transformation. Statistics in Medicine, 36, 2420-2434, doi:10.1002/sim.7279.
See Also
Examples
data(aidscd4)
bcmarg(cd4 ~ as.factor(treatment) * as.factor(weekc) + age,
data = aidscd4, time = weekc, id = id, structure = "AR(1)")
Model Median Inference for Longitudinal Data in Randomized Clinical Trials.
Description
bcmmrm
provides inference results for the model median differences
between treatment groups proposed by Maruo et al. (2017), which focuses on
continuous and positive longitudinally observed outcomes and a situation
where the efficacy of some treatments is compared based on a randomized,
parallel group clinical trial. If time
and id
are not
specified, inference results reduce to the results for the context of
linear regression model provided by Maruo et al. (2015).
Usage
bcmmrm(
outcome,
group,
data,
time = NULL,
id = NULL,
covv = NULL,
cfactor = NULL,
structure = "UN",
conf.level = 0.95,
lmdint = c(-3, 3),
glabel = NULL,
tlabel = NULL
)
Arguments
outcome |
a name of positive outcome (dependent) variable included in
|
group |
a name of treatment group variable included in |
data |
a data frame that may include |
time |
a name of time variable for repeated measurements included
in |
id |
a name of subject id variable for repeated measurements included
in |
covv |
a character vector with names of covariate variables included
in |
cfactor |
an integer vector including nominal variable indicators for
covariate variables. Nominal variable: |
structure |
specify the covariance structure from |
conf.level |
a numeric value of the confidence level for the confidence intervals. The default is 0.95. |
lmdint |
a vector containing the end-points of the interval to be
searched for a transformation parameter. The default is |
glabel |
a vector of length number of treatment groups containing
the labels of |
tlabel |
a vector of length number of repeated measures containing
the labels of |
Value
an object of class "bcmmrm
" representing the results of model
median inference based on the Box-Cox transformed MMRM model.
Generic functions such as print
, plot
, and summary
have methods to show the results of the fit. See bcmmrmObject
for the components of the fit.
Note
If baseline observation for the outcome variable is available, Box-Cox
transformed baseline should be included as a covariate for accuracy of
estimation.
Although this function can be applied to non-randomized
trial data, performances of the above approach have not evaluated in
context of non-randomized trials.
References
Maruo, K., Isogawa, N., Gosho, M. (2015). Inference of median difference based on the Box-Cox model in randomized clinical trials. Statistics in Medicine, 34, 1634-1644, doi:10.1002/sim.6408.
Maruo, K., Yamaguchi, Y., Noma, H., Gosho, M. (2017). Interpretable inference on the mixed effect model with the Box-Cox transformation. Statistics in Medicine, 36, 2420-2434, doi:10.1002/sim.7279.
See Also
Examples
data(aidscd4)
# covariate: Box-Cox transformed baseline (continuous) and sex (nominal),
# covariance structure: AR(1) structure
# *Note: The UN structure is preferred although the AR(1)
# structure is used in this example to reduce calculation time
# Box-Cox transformation for the baseline
aidscd4$cd4.bl.tr <- bct.v(aidscd4$cd4.bl)$transformed
# Median inference for each group and week
bcmmrm(outcome = cd4, group = treatment, data = aidscd4, time = weekc,
id = id, covv = c("cd4.bl.tr", "sex"), cfactor = c(0, 1),
structure = "AR(1)", glabel = c("Zid/Did", "Zid+Zal", "Zid+Did",
"Zid+Did+Nev"))
Fitted bcmmrm Object
Description
An object returned by the bcmmrm
function, inheriting from
class "bcmmrm" and representing the Box-Cox transformed MMRM analysis.
Objects of this class have methods for the generic functions boxplot
,
coef
, logLik
, plot
, print
, and summary
.
Value
The following components must be included in a legitimate "bcmmrm" object.
call
a list containing an image of the
bcmmrm
call that produced the object.median.mod
,median.rob
,median.mod.adj
,median.rob.adj
lists including inference results for the model medians for all groups. Levels of the list are time points, where correspondence table is given as
time.tbl$code
. mod: model-based inference, rob: robust inference, adj: with empirical small sample adjustment.meddif.mod
,meddif.rob
,meddif.mod.adj
,meddif.rob.adj
lists including inference results for the for the model median differences between all pairs of groups (group1 - group0). Levels of the list are time points, where correspondence table is given as
time.tbl$code
. mod: model-based inference, rob: robust inference, adj: with empirical small sample adjustment.lambda
a numeric value of estimates of the transformation parameter.
R
a correlation matrix for transformed outcomes.
betainf
inference results for beta under the assumption that lambda is known. Note that standard errors might be underestimated although statistical tests would be asymptotically valid.
time.tbl
a data frame of a correspondence table for the timepoints.
group.tbl
a data frame of a correspondence table for treatment groups.
inf.marg
a list with results of
bcmarg
function.outdata
a data frame where the transformed outcome (
ytr
), the fitted values on the transformed scale (ytr.fitted
), and the residuals on the transformed scale (res.tr
) are added to input data.conf.level
a numeric value of the specified confidence level.
See Also
Linear regression model with the Box-Cox Transformation.
Description
bcreg
returns the maximum likelihood estimates for parameters of
the linear regression models with the Box-Cox transformation (Box and Cox,
1964).
Usage
bcreg(formula, data, lmdint = c(-3, 3))
Arguments
formula |
a two-sided linear formula object describing the model, with the response on the left of a ~ operator and the terms, separated by + operators, on the right. |
data |
a data frame in which to interpret the variables named in the formula. |
lmdint |
a vector containing the end-points of the interval to be searched for a transformation parameter. Default is c(-3, 3). |
Value
bcreg returns a list including following components:
lambda
a numeric value with the estimate of the transformation parameter.
beta
a vector with the estimates of the regression parameters.
sigma
a numeric value with the estimate of the scale parameter.
betainf
a data frame with inference results for
beta
under the assumption thatlambda
is known.lik
a numeric value with the maximized likelihood.
lmObject
an object of "
lm
" containing the results oflm
function on the transformed scale
References
Box, G.E.P. and Cox, D.R. (1964). An analysis of transformations (with discussion). Journals of the Royal Statistical Society, Series B, 26, 211-246, doi:10.1111/j.2517-6161.1964.tb00553.x.
See Also
Examples
data(aidscd4)
#Transformation of baseline observation for aid.cd4 data
bcreg(cd4.bl ~ 1, aidscd4[aidscd4$weekc == 8, ])
Applying the Box-Cox Transformation.
Description
bct
returns the Box-Cox transformed numeric vector (Box and Cox,
1964).
Usage
bct(y, lambda)
Arguments
y |
a positive real number vector. |
lambda |
a scalar transformation parameter. |
Value
bct returns the Box-Cox transformed numeric vector,
z = log(y)
for lambda = 0
,
z = (y ^ lambda - 1) / lambda
for lambda ne 1
.
References
Box, G.E.P. and Cox, D.R. (1964). An analysis of transformations (with discussion). Journals of the Royal Statistical Society, Series B, 26, 211-246, doi:10.1111/j.2517-6161.1964.tb00553.x.
Examples
y <- exp(rnorm(10))
z <- bct(y, 0) #log transformation
Applying the Box-Cox Transformation to a numeric vector.
Description
bct.v
returns the Box-Cox transformed numeric vector (Box and Cox,
1964).
Usage
bct.v(y, lmdint = c(-3, 3))
Arguments
y |
a positive real number vector. |
lmdint |
a vector containing the end-points of the interval to be searched for a transformation parameter. Default is c(-3, 3). |
Value
bct.v
returns the Box-Cox transformed numeric vector and
estimated transformation parameter.
transformed
The Box-Cox transformed numeric vector.
lambda
a numeric value of the estimate of the transformation parameter.
References
Box, G.E.P. and Cox, D.R. (1964). An analysis of transformations (with discussion). Journals of the Royal Statistical Society, Series B, 26, 211-246, doi:10.1111/j.2517-6161.1964.tb00553.x.
Examples
y <- exp(rnorm(50))
bct.v(y)
Box-whisker plot for a bcmmrm Object.
Description
Box-whisker plot for the transformed residuals of each treatment groups
at a specified time point with error bar plot (mean +- SD) using
bcmmrmObject
.
Usage
## S3 method for class 'bcmmrm'
boxplot(
x,
timepoint = NULL,
xlab = NULL,
ylab = NULL,
main = TRUE,
sub = NULL,
verbose = FALSE,
...
)
Arguments
x |
an object inheriting from class " |
timepoint |
an numeric value of a specified level of |
xlab |
a title for the x axis. The default is |
ylab |
a title for the y axis. The default is |
main |
a main title for the plot. The default is |
sub |
a sub title for the plot. The default is |
verbose |
a logical optional value specifying to print the detailed
plot information in the console. The default is |
... |
some methods for this generic require additional arguments. |
Value
a box-whisker plot for transformed residual.
See Also
Examples
data(aidscd4)
lmd.bl <- bcreg(cd4.bl ~ 1, data = aidscd4[aidscd4$weekc == 8, ])$lambda
aidscd4$cd4.bl.tr <- (aidscd4$cd4.bl ^ lmd.bl - 1) / lmd.bl
resar <- bcmmrm(outcome = cd4, group = treatment, data = aidscd4,
time = weekc, id = id, covv = c("cd4.bl.tr", "sex"),
cfactor = c(0, 1), structure = "AR(1)", glabel =
c("Zid/Did", "Zid+Zal", "Zid+Did", "Zid+Did+Nev"))
boxplot(resar, xlab = "Treatment", col = 1:4)
Plot a bcmmrm Object.
Description
Plot for the model medians of each treatment groups with the 95 percent
confidence intervals stored in bcmmrmObject
.
Usage
## S3 method for class 'bcmmrm'
plot(
x,
robust = TRUE,
ssadjust = TRUE,
dt = 1,
timepoint = NULL,
tnom = TRUE,
xlab = NULL,
ylab = NULL,
xlim = NULL,
ylim = NULL,
lwd = 2,
col = NULL,
lty = NULL,
main = TRUE,
sub = NULL,
legend = TRUE,
loc = "topright",
verbose = FALSE,
...
)
Arguments
x |
an object inheriting from class " |
robust |
an optional logical value used to specify whether to apply
the robust inference. The default is |
ssadjust |
an optional logical value used to specify whether to apply
the empirical small sample adjustment. The default is |
dt |
an numeric value indicating shift length between groups
in the longitudinal median plot. A multiplying factor for the default
settings specified (e.g. if |
timepoint |
an numeric value of a specified level of |
tnom |
a optional logical value indicating the scale of x axis
of the longitudinal median plot. When |
xlab |
a title for the x axis. The default is |
ylab |
a title for the y axis. The default is |
xlim |
a numeric vector with length of 2 indicating limits of x
axis. The default is |
ylim |
a numeric vector with length of 2 indicating limits of y
axis. The default is |
lwd |
an optional positive numeric value indicating line width.
The default is |
col |
an integer or a character vector with length of the number of
groups indicating colors of lines for each treatment group. The default is
|
lty |
an optional integer or a character vector with length of the
number of groups indicating line types of lines for each treatment group.
The default is |
main |
a main title for the plot. The default is |
sub |
a sub title for the plot. The default is |
legend |
a logical optional value specifying to add legends to
plots. When |
loc |
a character value indicating the location of the legends.
The location can be specified by setting |
verbose |
a logical optional value specifying to print the detailed
analysis information in the console. The default is |
... |
some methods for this generic require additional arguments. |
Value
a median plot.
See Also
Examples
data(aidscd4)
resar <- bcmmrm(outcome = cd4, group = treatment, data = aidscd4,
time = weekc, id = id, structure = "AR(1)", glabel =
c("Zid/Did", "Zid+Zal", "Zid+Did", "Zid+Did+Nev"))
plot(resar, xlab = "Week", ylab = "CD4+1", col = 1:4, main = NULL)
plot(resar, timepoint = 32, xlab = "Treatment", ylab = "CD4+1")
Summarize a bcmmrm Object.
Description
Additional information about the Box-Cox transformed MMRM analysis
represented by object
is extracted and included as components
of object
.
Usage
## S3 method for class 'bcmmrm'
summary(object, robust = TRUE, ssadjust = TRUE, ...)
Arguments
object |
an object inheriting from class " |
robust |
an optional logical value used to specify whether to apply
the robust inference. The default is |
ssadjust |
an optional logical value used to specify whether to apply
the empirical small sample adjustment. The default is |
... |
some methods for this generic require additional arguments. None are used in this method. |
Value
an object inheriting from class summary.bcmmrm
with all
components included in object
(see glsObject
for
a full description of the components) plus the following components:
median
a list including inference results of the model median for specified values of
robust
andssadjust
.meddif
a list including inference results of the model median difference for specified values of
robust
andssadjust
.robust
a specified value of
robust
.ssadjust
a specified value of
ssadjust
.
See Also
Examples
data(aidscd4)
resar <- bcmmrm(outcome = cd4, group = treatment, data = aidscd4,
time = weekc, id = id, structure = "AR(1)",
glabel = c("Zid/Did", "Zid+Zal", "Zid+Did", "Zid+Did+Nev"))
summary(resar)