splinetrials (version 0.1.1)

ncs_emmeans: Estimate Marginal Means for a Natural Cubic Splines Analysis

Description

This is wrapper around emmeans::emmeans() for a natural cubic splines analysis in which there is a continuous time variable, a study arm, and (optionally) a subgroup variable.

Usage

ncs_emmeans(
  fit,
  data = fit[["data"]],
  observed_time = NULL,
  scheduled_time = NULL,
  arm = NULL,
  subgroup = NULL,
  average_nuisance = TRUE,
  emmeans_args = list(nesting = NULL),
  ...,
  scheduled_time_spec = sort(unique(data[[scheduled_time]])),
  arm_spec = as.character(sort(unique(data[[arm]]))),
  subgroup_spec = as.character(sort(unique(data[[subgroup]]))),
  .__caller_env = rlang::caller_env()
)

Value

An object of class emmGrid: the result of emmeans::emmeans(). Note that for a result result, the elements [e-mail]$nesting and result@misc$display are removed.

Arguments

fit

(mmrm)
an mmrm object whose terms include the variables supplied to observed_time, scheduled_time, arm, and (optionally) subgroup.

data

(data frame)
a data frame on which to estimate marginal means. Defaults to fit[["data"]].

observed_time

(string)
string specifying the observed continuous time variable in both fit and in data.

scheduled_time

(string)
string specifying the scheduled continuous time variable in both fit and in data. Ignored if scheduled_time_spec is provided.

arm

(string)
string specifying the study arm variable in both fit and in data.

subgroup

(string)
string specifying the subgroup variable in both fit and in data.

average_nuisance

(flag)
flag indicating whether the names of the terms in covariates should be supplied as the nuisance argument to emmeans::emmeans(). This results in treating all the covariates as nuisance parameters and averaging over them when calculating the reference grid to estimate marginal means. See emmeans::ref_grid() for details and limitations.

emmeans_args, ...

(named list)
arguments to be passed to emmeans::emmeans(). If any elements have the names object, specs, or at they will be ignored. If average_nuisance = TRUE, any element named nuisance will be ignored. Any elements named params may be ignored. emmeans_args defaults to list(nesting = NULL). Arguments named in emmeans_args supersede any named arguments in ....

scheduled_time_spec

(numeric)
vector of unique, non-missing time points on which to calculate marginal means. Defaults to sort(unique(data[[scheduled_time]])).

arm_spec

(character)
vector of unique study arm values on which to calculate marginal means. Defaults to as.character(sort(unique(data[[arm]]))).

subgroup_spec

vector of unique subgroup values on which to calculate marginal means. Ignored if subgroup is NULL. Defaults to as.character(sort(unique(data[[subgroup]]))).

.__caller_env

(environment)
the environment from which this function was called. Defaults to rlang::caller_env().

Examples

# 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)

fit <-
  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
  )

ncs_emmeans(
  fit = fit,
  observed_time = "time_cont",
  scheduled_time = "VISITN",
  arm = "ARMCD",
  subgroup = "SEX"
)