Builds an mmrm model that includes a study arm,
optionally a subgroup, and natural cubic splines applied to a continuous
time variable. A wrapper around mmrm::mmrm().
Constructs a call to mmrm::mmrm() for ncs analysis. Implements natural
cubic splines for the continuous time variable. Attempts a sequence of
covariance structures in order until one of them successfully converges.
Title
ncs_mmrm_fit(
data,
type = c("basic", "subgroup_full", "subgroup_reduced"),
response,
subject,
cov_structs = c("us", "toeph", "ar1h", "csh", "cs"),
cov_struct_group = NULL,
time_observed_continuous,
df = 2,
spline_basis = NULL,
time_observed_index,
arm = NULL,
control_group = "control",
subgroup = NULL,
subgroup_comparator = NULL,
covariates = ~1,
expand_spline_terms = TRUE,
mmrm_args = list(method = "Satterthwaite"),
...
)An mmrm object created by mmrm::mmrm().
(data frame)
data set supplied to the data argument of
mmrm::mmrm() when fitting models. The supplied expression is
quoted and must evaluate to a data frame. See Tidy
evaluation support.
(string)
one of "basic", "subgroup_full", or
"subgroup_reduced".
(numeric or string)
the response variable. It can be a
string identifying the name of an existing variable; otherwise, the
supplied expression will be quoted and added to the formula
as is (see Tidy evaluation support).
(atomic or string)
the unique subject identifier
forwarded to the subject argument of mmrm::cov_struct(). Ignored if
cov_structs is a list. Can be a string identifying an existing
variable; otherwise the supplied expression will be quoted
and turned into a string with rlang::expr_deparse() (see Tidy
evaluation support).
(character or list)
either a list of unique
cov_struct objects or a character vector of one or
more of the covariance structure abbreviations as described in
mmrm::cov_types(). These covariance structures will be attempted in order
until one of them achieves a converging model fit. Defaults to c("us", "toeph", "ar1h", "csh", "cs").
(atomic or string)
optional grouping variable
to be passed to the group argument of mmrm::cov_struct(). It can be a
string identifying an existing variable name; otherwise the supplied
expression will be quoted and turned into a string with
rlang::expr_deparse() (see Tidy evaluation support). Ignored if
cov_structs is a list. Defaults to NULL, in which case no grouping
variable will be used.
(numeric or string)
the visit's
observed time point. It must either be a string or a name identifying
an existing variable (i.e., it cannot be a call). If a name is provided,
it is quoted and incorporated into the model formula as is
(see Tidy evaluation support).
(scalar integer)
number of degrees of freedom to use to create
the spline basis. Passed to the df argument of time_spline_basis().
Ignored if the spline_basis argument is not NULL.
(basis matrix)
a spline basis: probably a value
returned by time_spline_basis() (which wraps splines::ns()). If NULL
(the default), then the spline basis will be the result of forwarding
time_observed_continuous and df to time_spline_basis(). See
Providing a spline basis.
(ordered or string)
the visit index that
the visit shall be associated with, based on the visit's observed time
point. This will be passed as the visits argument of
mmrm::cov_struct(). It can be a string identifying an existing
variable; otherwise the supplied expression will be quoted
and turned into a string with rlang::expr_deparse() (see Tidy
evaluation support). If it does not evaluate to an ordered factor, it
will be wrapped with as.ordered(). Ignored if cov_structs is a list.
(factor or string)
the study arm. It must be a string or
a name identifying an existing variable (i.e., it cannot be a call). If
a name, it will be quoted before being added to the model
formula (see Tidy evaluation support). If it does not evaluate to a
factor or if control_group is not its first level, the data
argument will be wrapped in a dplyr::mutate() call that forces this to be
the case.
(string)
the value in arm denoting the control
group. If necessary, arm will be preprocessed such that it is a factor
with control_group as its first level.
(factor or string)
the subgroup. It must be a string
or a name identifying an existing variable (i.e., it cannot be a call).
If a name, it will be quoted before being added to the
model formula (see Tidy evaluation support). If it does not evaluate to
a factor or if subgroup_comparator is not its first level,
the data argument will be wrapped in a dplyr::mutate() call that forces
this to be the case.
(string)
the value in subgroup denoting the
"main" subgroup that all other subgroups should be compared to. If
necessary, subgroup will be preprocessed such that it is a factor with
control_group as its first level.
(formula)
formula containing additional terms that
should be added to the mmrm model. Defaults to ~ 1, in which no
additional terms will be added. Must not have a left side. Cannot contain
.. To specify that the model shall not have an intercept, use include + 0 or - 1 in this formula.
(flag)
flag indicating whether or not to
separate the cubic spline matrix into separate terms (one for each degree
of freedom). Defaults to TRUE. See Expanding spline terms.
(named list)
arguments to be passed to mmrm::mmrm().
If any elements have the names formula, data, or covariance they will
be ignored. An element named vcov will also be ignored unless fitting a
model with an unstructured covariance. Defaults to list(method = "Satterthwaite").
additional arguments to be passed to mmrm::mmrm(). If any
elements have the names formula, data, or covariance they will be
ignored. An element named vcov will also be ignored unless fitting a
model with an unstructured covariance. Defaults to list(method = "Satterthwaite"). Arguments named in mmrm_args supersede any named
arguments in ....
This function's spline_basis argument was designed with splines::ns() in
mind, which creates a matrix object with classes basis and matrix as well
as multiple attributes. In theory, spline_basis does not have to be a
matrix; however, it still must have a stats::predict() method wherein
stats::predict(spline_basis, data[[time_observed_continuous]]) produces an
object that can serve as a term in the model.
The user specifies covariance structure candidates via the cov_structs
argument. These structures will be attempted in order until a model converges
successfully.
When any covariance structure other than "us" (heterogeneous unstructured)
is used, "Empirical-Bias-Reduced" is passed to mmrm::mmrm() as the vcov
argument (see mmrm::mmrm_control()).
When fitting models, these analysis functions specify the covariance
structure through the covariance argument of mmrm::mmrm().
These analysis functions automatically build the model formula from its
arguments. The user cannot remove any of these auto-generated terms, but
terms can be added via the covariates argument.
Natural cubic splines will be applied to the time_observed_continuous
variable in data. These splines will be constructed according to the
user-specified spline_basis. A custom spline_fn() is constructed under
the hood that accepts time_observed_continuous and produces a spline matrix
based on the spline_basis. Thus, the model formula includes a time spline
term resembling spline_fn(time_observed_continuous).
arm and subgroup terms
All generated models include an interaction term between the time spline term
and the study arm term, but arm is not included as a main effect by
default. If this is desired, use the covariates argument (e.g., specify
covariates = ~ arm).
Concerning ncs_analysis_subgroup(), the subgroup variable is included as
a main effect, and its interaction with the time spline is also included.
Furthermore, the second-order interaction term between the time spline,
subgroup, and arm is also included for the main analysis model and the
"full" model (when subgroup_interaction_test = TRUE; see Subgroup
interaction test below).
covariates
The user can specify additional terms through the covariates argument,
which must be a formula.
The user cannot specify the covariance structure with this argument. See the Covariance structures section above.
The user can remove the intercept from the model by including 0 as a term
in covariates.
The model formulas that the analysis functions construct will take the form of the formula templates below.
ncs_analysis() (i.e., no subgroup)
response ~
spline_fn(time_observed_continuous) +
spline_fn(time_observed_continuous):arm {+
covariates}
ncs_analysis_subgroup()
Main analysis model and "full" model:
response ~
spline_fn(time_observed_continuous) +
subgroup +
spline_fn(time_observed_continuous):subgroup +
spline_fn(time_observed_continuous):arm +
spline_fn(time_observed_continuous):subgroup:arm {+
covariates}
"reduced" model:
response ~
spline_fn(time_observed_continuous) +
subgroup +
spline_fn(time_observed_continuous):subgroup +
spline_fn(time_observed_continuous):arm {+
covariates}
When expand_spline_terms = TRUE and spline_basis has at least two
dimensions (e.g., if it is a matrix, which is typical), the spline term
will be split into multiple terms: one for each of its columns.
For instance, if the user specifies a spline_basis with 3 degrees of
freedom, the above no-subgroup model formula template would become:
response ~
spline_fn(time_observed_continuous)[, 1] +
spline_fn(time_observed_continuous)[, 2] +
spline_fn(time_observed_continuous)[, 3] +
spline_fn(time_observed_continuous)[, 1]:arm +
spline_fn(time_observed_continuous)[, 2]:arm +
spline_fn(time_observed_continuous)[, 3]:arm {+
covariates}
# Create a usable data set out of mmrm::fev_data
fev_mod <- mmrm::fev_data
fev_mod$VISITN <- fev_mod$VISITN * 10
fev_mod$time_cont <- fev_mod$VISITN + rnorm(nrow(fev_mod))
fev_mod$obs_visit_index <- round(fev_mod$time_cont)
# Example without subgroup:
ncs_mmrm_fit(
data = fev_mod,
type = "basic",
response = FEV1,
subject = USUBJID,
cov_structs = c("ar1", "us"),
time_observed_continuous = time_cont,
df = 2,
time_observed_index = obs_visit_index,
arm = ARMCD,
control_group = "PBO",
covariates = ~ FEV1_BL + RACE
)
# Example with subgroup:
ncs_mmrm_fit(
data = fev_mod,
type = "subgroup_full",
response = FEV1,
subject = USUBJID,
cov_structs = c("ar1", "us"),
time_observed_continuous = time_cont,
df = 2,
time_observed_index = obs_visit_index,
arm = ARMCD,
control_group = "PBO",
subgroup = SEX,
subgroup_comparator = "Male",
covariates = ~ FEV1_BL + RACE
)
Run the code above in your browser using DataLab