coxed: Expected durations and marginal changes in expected duration...
In coxed: Duration-Based Quantities of Interest for the Cox Proportional Hazards Model

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

1
2
3

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

`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

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

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.

Jonathan Kropko <jkropko@virginia.edu> and Jeffrey J. Harden <jharden2@nd.edu>

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–212. https://doi.org/10.1214/ss/1032280214

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

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

## End(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")

## End(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")

## End(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")