coxed (version 0.3.3)

coxed: Expected durations and marginal changes in expected duration from the Cox proportional hazards model

Description

coxed() returns expected durations for every observation in the data used to fit the model, or in new data, or returns the mean or median of these durations, or differences in duration for two pre-defined covariate profiles. Standard errors and confidence intervals for all quantities produced by coxed() are calculated via bootstrapping.

Usage

coxed(cox.model, newdata = NULL, newdata2 = NULL, bootstrap = FALSE,
  method = "npsf", k = -1, B = 200, confidence = "studentized",
  level = 0.95, id = NULL, ...)

Arguments

cox.model

The output from a Cox proportional hazards model estimated with the coxph function in the survival package or with the cph function in the rms package

newdata

An optional data frame in which to look for variables with which to predict. If omitted, the fitted values are used

newdata2

An optional data frame that can only be specified if newdata is not omitted, and must have the same dimensions as newdata. If specified, marginal changes are calculated by subtracting the expected durations for newdata2 from the expected durations for newdata

bootstrap

Should bootstrapped standard errors and confidence intervals be calculated?

method

If "npsf" (the default), expected durations are calculated using the non-parametric step function approach described in Kropko and Harden (2018). If "gam", expected durations are calculated using the GAM method

k

The number of knots in the GAM smoother. The default is -1, which employs the choose.k function from the mgcv package to choose the number of knots

B

Number of bootstrap simulation iterations

confidence

If "studentized" (the default), bootstrapped CIs are calculated from the tails of a normal distribution where the mean and standard deviation are the point estimate and boostrapped SE of each duration estimate. If "empirical", bootstrapped confidence intervals are calculated empirically. If "bca", bootstrapped confidence intervals are calculated using the bias-correction and acceleration method described by DiCiccio and Efron (1996).

level

The level of the confidence interval to calculate (default is .95 for a 95 percent confidence interval)

id

Cluster variable if bootstrapping is to be done by clusters of observations rather than individual observations. If the data are coded with time-varying covariates (using the time2 argument in the Surv function), this variable must be the ID variable in the data that are used to estimate the Cox PH model, and not the ID variable in new data.

...

Additional arguments to be passed to the bootcov2 function, an adaptation of the bootcov function in the rms package

Value

coxed returns an object of class "coxedExpdur" or "coxedMargin", which is a list containing some of the following components, depending on the implementation of coxed:

exp.dur	A vector of predicted mean durations for the estimation sample if newdata is omitted, or else for the specified new data. If bootstrap is TRUE bootstrapped standard errors are also provided, as well as the confidence interval requested by level.
mean	The mean of the predicted durations. If bootstrap is TRUE bootstrapped standard errors are also provided, as well as the confidence interval requested by level.
median	The median of the predicted durations. If bootstrap is TRUE bootstrapped standard errors are also provided, as well as the confidence interval requested by level.
baseline.functions	The estimated cumulative baseline hazard function and survivor function.
gam.model	Output from the gam function in which the durations are fit against the exponentiated linear predictors from the Cox model.
gam.data	Fitted values and confidence intervals from the GAM model.
exp.dur1	A vector of predicted mean durations for the observations in newdata1 when calculating marginal effects.
exp.dur2	A vector of predicted mean durations for the observations in newdata2 when calculating marginal effects.
mean1	The mean of the predicted mean durations for the observations in newdata1 when calculating marginal effects.
mean2	The mean of the predicted mean durations for the observations in newdata2 when calculating marginal effects.
median1	The median of the predicted mean durations for the observations in newdata1 when calculating marginal effects.
median2	The median of the predicted mean durations for the observations in newdata2 when calculating marginal effects.
diff	A vector of the difference between the predicted mean durations for each observation under the covariate profile in newdata2 and the covariate profile in newdata1.
mean.diff	The mean of the differences in duration across observations.
median.diff	The median of the differences in duration across observations.

Details

The coxed function generates expected durations for individual observations and/or marginal changes in expected duration given a change in a covariate from the Cox proportional hazards model. Specifically, the methods can compute (1) the expected duration for each observation used to fit the Cox model, given the covariates, (2) the expected duration for a "new" observation with a covariate profile set by the analyst, or (3) the first difference, or change, in expected duration given two new data frames.

There are two different methods, described in Kropko and Harden (2018), of generating duration-based quantities in the package. The first method calculates expected durations by using a nonparametric estimate of the baseline hazard and survivor functions (see coxed.npsf for details). The second method employs a generalized additive model (GAM) to map the model's estimated linear predictor values to duration times (see coxed.gam for details). Both methods are also implemented for data structures with time-varying covariates (see coxed.npsf.tvc and coxed.gam.tvc).

References

Kropko, J. and Harden, J. J. (2018). Beyond the Hazard Ratio: Generating Expected Durations from the Cox Proportional Hazards Model. British Journal of Political Science https://doi.org/10.1017/S000712341700045X

DiCiccio, T. J. and B. Efron. (1996). Bootstrap Confidence Intervals. Statistical Science. 11(3): 189<U+2013>212. https://doi.org/10.1214/ss/1032280214

See Also

coxph, cph, bootcov2, coxed.gam, coxed.gam.tvc, coxed.npsf, coxed.npsf.tvc

Examples

# NOT RUN {
mv.surv <- Surv(martinvanberg$formdur, event = rep(1, nrow(martinvanberg)))
mv.cox <- coxph(mv.surv ~ postel + prevdef + cont + ident + rgovm + pgovno +
     tpgovno + minority, method = "breslow", data = martinvanberg)
summary(mv.cox)

# NPSF method
ed1 <- coxed(mv.cox, method="npsf")
ed1$baseline.functions
ed1$exp.dur
summary(ed1, stat="mean")
summary(ed1, stat="median")

# }
# NOT RUN {
ed1 <- coxed(mv.cox, method="npsf", bootstrap = TRUE)
ed1$exp.dur
summary(ed1, stat="mean")
summary(ed1, stat="median")
# }
# NOT RUN {
me <- coxed(mv.cox, method="npsf", bootstrap = FALSE,
            newdata = dplyr::mutate(martinvanberg, pgovno=1),
            newdata2 = dplyr::mutate(martinvanberg, pgovno=6))
summary(me, stat="mean")

# GAM method
ed2 <- coxed(mv.cox, method="gam")
summary(ed2$gam.data)
summary(ed2$gam.model)
ed2$exp.dur
summary(ed2, stat="mean")

# }
# NOT RUN {
me <- coxed(mv.cox, method="gam", bootstrap = TRUE,
            newdata = dplyr::mutate(martinvanberg, pgovno=1),
            newdata2 = dplyr::mutate(martinvanberg, pgovno=6))
summary(me, stat="mean")
summary(me, stat="median")
# }
# NOT RUN {
#Plotting the GAM fit
# }
# NOT RUN {
ggplot(ed2$gam.data, aes(x=rank.xb, y=y)) +
    geom_point() +
    geom_line(aes(x=rank.xb, y=gam_fit)) +
    geom_ribbon(aes(ymin=gam_fit_95lb, ymax=gam_fit_95ub), alpha=.5) +
    xlab("Cox model LP rank (smallest to largest)") +
    ylab("Duration")
# }
# NOT RUN {
#Time-varying covariates
bs.surv <- Surv(time = boxsteffensmeier$start, time2 = boxsteffensmeier$te,
     event = boxsteffensmeier$cut_hi)
bs.cox <- coxph(bs.surv ~ ec + dem + south + iv, data = boxsteffensmeier, method = "breslow")
summary(bs.cox)

ed1 <- coxed(bs.cox, method="npsf", id=boxsteffensmeier$caseid)
ed1$exp.dur
summary(ed1, stat="mean")
# }