In sachsmc/pseval: Methods for Evaluating Principal Surrogates of Treatment Response
library(knitr)
require(printr, quietly = TRUE)
set.seed(225452)
Methods
Introduction
A valid principal surrogate endpoint can be used as a primary endpoint for evaluating treatments in phase II clinical trials and for predicting individual treatment effects post licensure. A surrogate is considered to be valid if it provides reliable predictions of treatment effects on the clinical endpoint of interest. @Frangakis02 introduced the concept of principal stratification and the definition of a principal surrogate (PS). Informally, a post-treatment intermediate response variable is a principal surrogate if causal effects of the treatment on the clinical outcome only exist when causal effects of the treatment on the intermediate variable exist. The criteria for a PS have been modified and extended in more recent works, with most current literature focusing on wide effect modification as the primary criterion of interest; tests for wide effect modification are implemented in the package.
The goal of PS evaluation is estimation and testing of how treatment efficacy on the clinical outcome of interest varies over subgroups defined by possible treatment and surrogate combinations of interest; this is an effect modification objective. The combinations of interest are called the principal strata and they include a set of unobservable counterfactual responses: responses that would have occurred under a set of conditions counter to the observed conditions. To finesse this problem of unobservable responses, a variety of clever trial designs and estimation approaches have been proposed. Several of these have been implemented in the pseval package [@pseval].
Notation
Let $Z_i$ be the treatment indicator for subject $i$, where 0 indicates the control or standard treatment, and 1 indicates the experimental treatment. We currently only allow for two levels of treatment and assume that the treatment assignments are randomized. Let $S_i$ be the observed value of the intermediate response for subject $i$. Since $S_i$ can be affected by treatment, there are two naturally occurring counterfactual values of $S_i$: $S_i(1)$ under treatment, and $S_i(0)$ under control. Let $s_z$ be the realization of the random variable $S(z)$, for $z \in {0, 1}$. The outcome of interest is denoted $Y_i$. We consider the counterfactual values of $Y_i(0)$ and $Y_i(1)$. We allow for binary, count, and time-to-event outcomes, thus $Y_i$ may be a vector containing a time variable and an event/censoring indicator, i.e. $Y_i = (T_i, \Delta_i)$ where $\Delta_i = 1$ if $T_i$ is an event time, and $\Delta_i = 0$ if $T_i$ is a censoring time. For all of the methods, $S_i(z)$ is only defined if the clinical outcome $Y_i(z)$ does not occur before the potential surrogate $S_i(z)$ is measured at a fixed time $\tau$ after entry into the study. The data analyses only include participants who have not experienced the clinical outcome by time $\tau$. For interpretability all of the methods assume no individual-level treatment effects on $Y$ before $\tau$, which we refer to as the "Equal early individual risk" assumption below.
Estimands
Criteria for $S$ to be a good surrogate are based on risk estimands that condition on the potential intermediate responses. The risk is defined as a mapping $g$ of the cumulative distribution function of $Y(z)$ conditional on the intermediate responses. The joint risk estimands conditions on the candidate surrogate under both level of treatment, $(S(1), S(0))$.
$$
risk_1(s_1, s_0) = g\left{F_{s_1}\left[Y(1) | S(0) = s_0, S(1) = s_1\right]\right}, \
risk_0(s_1, s_0) = g\left{F_{s_1}\left[Y(0) | S(0) = s_0, S(1) = s_1\right]\right}.
$$
For instance, for a binary outcome, the risk function may simply be the probability $risk_z(s_1, s_0) = P(Y(z) = 1 | S(0) = s_0, S(1) = s_1)$, or for a time-to-event outcome the risk function may be the cumulative distribution function $risk_z(s_1, s_0) = P(Y(z) \leq t | S(0) = s_0, S(1) = s_1)$.
Currently we focus only on marginal risk estimands which condition only on $S(1)$, the intermediate response or biomarker under active treatment:
$$
risk_1(s_1) = g\left{F_{s_1}\left[Y(1) | S(1) = s_1\right]\right}, \
risk_0(s_1) = g\left{F_{s_1}\left[Y(0) | S(1) = s_1\right]\right}.
$$
Neither of the joint risk estimands are indentifiable in a standard randomized trial, as either S(0) or S(1) or both will be missing for each subject. In the special case where $S(0)$ is constant, such as the immune response to HIV antigens or Hep B in the placebo arm of a vaccine trial, the joint and marginal risk estimands are equivalent. This special case is referred to as case constant biomarker (CB) in much of the literature [@Gilbert08]; S_i(0) = c for subjects i. This may occur outside the vaccine setting when one considers the AUC of a treatment drug as a surrogate; those receiving placebo will have no drug and therefore all placebo AUC will be 0. Under assumptions given below, and in the case CB setting, the marginal risk estimand is indentifiable in the treatment arm.
As well, as will be outlined below, there are specific trial augmentations that allow for the measurement or imputation of the missing counterfactual Ss. Under one of these augmentations, case CB can sometimes be induced by considering a function of the a candidate surrogate for evaluation. Greater detail on this point given below.
Specification of the distributions of $Y(z) | S(1)$ determines the likelihood, we will denote this as $f(y | \beta, s_1, z)$. If $S(1)$ were fully observed, simple maximum likelihood estimation could be used. The key challenge in estimating these risk estimands is solving the problem of conditioning on counterfactual values that are not observable for at least a subset of subjects in a randomized trial. This involves integrating out missing values based on some models and/or set of assumptions.
Principal Surrogate Criteria
@Frangakis02 gave a single criterion for a biomarker S to be a PS: causal effects of the treatment on the clinical outcome only exist when causal effects of the treatment on the intermediate variable exist. In general this can only be evaluated using the joint risk estimands, which consider not only the counterfactual values of the biomarker under treatment, but also under control $S(0)$. However, in the special case where all $S(0)$ values are constant, say at level $C$, such as an immune response to HIV in a HIV negative population pre-vaccination this criteria, often referred to as average causal necessity (ACN), can by written in terms of the marginal risk estimands as:
$$
risk_1(C)=risk_0(C)
$$
More recently, other works @Gilbert08, @Wolfson10, @Huang12, @Gabriel14, and @Gabriel15b have suggested that this criterion is both too restrictive and in some cases can be vacuously true. Instead most current works suggest that the wide effect modification (WEM) criterion is of primary importance, ACN being of secondary importance. WEM is given formally in terms of the risk estimands and a known contrast function $h$ satisfying $h(x, y) = 0$ if and only if $x = y$ by:
$$
|h(risk_1(s_1),risk_0(s_1)) - h(risk_1(s{_1}^),risk_0(s{_1}^))|>\delta
$$
for at least some $s_1 \neq s_{1}^*$ and $\delta>0$, with the larger the $\delta$ the better. To evaluate WEM and ACN we need to identify the risk estimands.
Augmentation and Assumptions
We first make three standard assumptions used in much of the literature for absorbing events outcomes:
- Stable Unit Treatment Value Assumption (SUTVA): Observations on the independent units in the trial should be unaffected by the treatment assignment of other units.
- Ignorable Treatment Assignment: The observed treatment assignment does not change the counterfactual clinical outcome.
- Equal individual risk up to the time of candidate surrogate measurement $\tau$.
In time-to-event settings one more assumption is needed:
- Non-informative censoring.
It should be noted that the equal individual risk assumption requires that time-to-event analysis start at time $\tau$, rather than at randomization.
@Wolfson10 outlines how these assumptions are needed for identification of the risk estimands. Now to deal with the missing $S(1)$ values among those with $Z = 0$, we next focus on three trial augmentations: Baseline immunogenicity predictor (BIP), closeout placebo vaccination (CPV), and baseline surrogate measurement (BSM). For further details on these augmentations, we refer you to @Follmann06, @Gilbert08, @Gabriel14, and @Gabriel15b.
BIP
Briefly, a BIP $W$ is any baseline measurement or set of measurements that is highly correlated with $S$. It is particularly useful if $W$ is unlikely to be associated with the clinical outcome after conditioning on $S$, i.e. $Y \perp W | S(1)$; some of the methods leverage this assumption. The BIP $W$ is used to integrate out the missing $S(1)$ among those with $Z = 0$ based on a model for $S(1) | W$ that is estimated among those with $Z = 1$. We describe how this model is used in the next section.
The assumptions needed for a BIP to be useful depend on the risk model used. If the BIP is included in the risk model, only the assumption of no interaction with treatment and the candidate surrogate are needed. However, if the BIP is not included in the risk model, the assumption that that clinical outcome is independent of the BIP given the candidate surrogate is needed. Although not a requirement for identification of the risk estimands, it has been found in most simulations studies that a correlation between the BIP and $S(1)$ of greater than 0.7 is needed for unbiased estimation in finite samples.
CPV
Under a CPV augmented design, control recipients that do not have events at the end of the follow-up period are given the experimental treatment. Then their intermediate response is measured at some time post treatment. This measurement is then used as a direct imputation for the missing $S(1)$. This augmentation was developed in the setting of vaccine trials, where the surrogate is an immune response and the outcome is infection. One set of conservative assumptions to use CPV as a direct imputation for $S(1)$ are given in @Wolfson10 are:
- Time constancy of the true intermediate response under active treatment, $S(1)=S_{CPV}$ almost surely, for placebo recipients that are crossed over at the end of the trial, where $S_{CPV}$ is the measurement of the candidate surrogate after crossover treatment of the placebo subjects.
- No events (infections) during the close-out period
BSM
@Gabriel14 suggested the baseline augmentation BSM, which is a pre-treatment measurement of the candidate PS, denoted $S_B$. The BSM may be a good predictor of $S(1)$ without any further assumptions. It can be used in the same way as a BIP. Alternatively you can transform $S(1) - S_B$ and use this as the candidate surrogate, further increasing the association with the BSM/BIP. Under the BSM assumption outlined in @Gabriel14;
- Time constancy of the true intermediate response under control,
then $S(0)=S_{BSM}$ almost surely. You do not need this assumption to use a BSM, but if it holds then it induces the CB case, thus the joint and marginal risk estimands are equivalent.
Estimated Maximum Likelihood
Let $f(y | \beta, s_1, z)$ denote the density of $Y | S(1), Z$ with parameters $\beta$. Further let $R_i$ denote the indicator for missingness in $S_i(1)$. We proceed to estimate $\beta$ by maximizing
$$
\prod_{i = 1}^n \left{f(Y_i | \beta, S_i(1), Z_i)\right}^R_i \left{\int f(Y_i | \beta, s, Z_i) \, d \hat{F}_{S(1) | W}(s | W_i)\right}^{1 - R_i}
$$
with respect to $\beta$.
This procedure is called estimated maximum likelihood (EML) and was developed in @Pepe91. The key idea is that we are averaging the likelihood contributions for subjects missing $S(1)$ with respect to the estimated distribution of $S(1) | W$. A BIP $W$ that is strongly associated with $S(1)$ is needed for adequate performance.
Closed-form inference is not available for EML estimates, thus we recommend use of the bootstrap for estimation of standard errors. It was suggested as an approach to principal surrogate evaluation by @Gilbert08 and @Huang11.
Pseudoscore
@Huang12 suggest a different estimation procedure that does have a closed form variance estimator. Instead of numerically optimizing the estimated likelihood, the pseudoscore approach iteratively finds the solution to weighted versions of the score equations. Pseudoscore estimates were also suggested in @WolfsonDiss and implemented for several special cases in @Huang12. We have implemented here only one of the special cases: categorical $BIP$ and binary $Y$ ($S$ may be continuous or categorical). In addition to having closed form variance estimators, it has been argued that the pseudo-score estimators are more efficient than the EML estimators. The closed form variance estimates are not yet implemented.
Package features
Typically, users would have to code up the likelihood, integration models, and perform the optimization themselves. This is beyond the reach of many researchers who desire to use these methods. The goal of pseval is to correctly implement these methods with a flexible and user-friendly interface, enabling researchers to implement and interpret a wide variety of models.
The pseval package allows users to specify the type of augmented design that is used in their study, specify the form of the risk model along with the distribution of $Y | S(1)$, and specify different integration models to estimate the distribution of $S(1) | W$. Then the likelihood can be maximized and bootstraps run. Post-estimation summaries are available to display and analyze the treatment efficacy as a function of $S(1)$. All of this is implemented with a flexible and familiar interface.
Package information
Installation
pseval is an R package aimed at implementing existing methods for surrogate evaluation using a flexible and common interface. Development will take place on the Github page, and the current version of the package can be installed as shown below. First you must install the devtools package, if you haven't already install.packages("devtools").
devtools::install_github("sachsmc/pseval")
or it can be installed from CRAN:
install.packages("pseval")
Usage
Here we will walk through some basic analyses from the point of view of a new R user. Along the way we will highlight the main features of pseval. pseval supports both binary outcomes and time-to-event, thus we will also need to load the survival package.
library(pseval)
library(survival)
First let's create an example dataset. The \pkg{pseval} package provides the function generate_example_data which takes a single argument: the sample size.
set.seed(1492)
fakedata <- generate_example_data(n = 800)
head(fakedata)
The example data includes both a time-to-event outcome, a binary outcome, a surrogate, a BIP, CPV, and BSM, and a categorical version of the surrogate. The true model for the time is exponential, with parameters (intercept) = -1, S(1) = 0.0, Z = 0.0, S(1):Z = -0.75. The true model for binary is logistic, with the same parameter values.
In the above table S.obs.cat and BIP.cat are formed as S.obs.cat <- factor(S.obs,levels=c(-Inf, quantile(c(S.0, S.1), c(.25, .5, .75), na.rm = TRUE), Inf)) and similarly for BIP.cat. Alternatively a user could input arbitrary numeric values to represent different discrete subgroups (e.g., 0s and 1s to denote 2 subgroups).
The "psdesign" object
We begin by creating a "psdesign" object with the synonymous function. This is the object that combines the raw dataset with information about the study design and the structure of the data. Subsequent analysis will operate on this psdesign object. It is designed to be analogous to the svydesign function in the survey package (https://CRAN.R-project.org/package=survey). The first argument is the data frame where the data are stored. All subsequent arguments describe the mappings from the variable names in the data frame to important variables in the PS analysis, using the same notation as above. An optional weights argument describes the sampling weights, if present. Our first analysis will use the binary version of the outcome, with continuous $S.1$ and the BIP labeled $BIP$. The object has a print method, so we can inspect the result.
binary.ps <- psdesign(data = fakedata, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP)
binary.ps
The printout displays a brief description of the data, including the empirical treatment efficacy estimate, the variables used in the analysis and their corresponding variables in the original dataset. Finally the printout invites the user to see the help page for add_integration, in order to add an integration model to the psdesign object, the next step in the analysis.
Missing values in the $S$ variable are allowed. Note that any cases where $S(1)$ is missing will be integrated over in the likelihood or score equations. Thus any cases that experienced an event prior to the time $\tau$ when the surrogate was measured should be excluded from the dataset. The equal individual risk assumption allows us to make causal inferences even after excluding such cases.
psdesign easily accommodates case-control or case-cohort sampling. In this case, the surrogate $S$ is only measured on a subset of the data, inducing missingness in $S$ by design. Let's modify the fake dataset to see how it works. We're going to sample all of the cases, and 20% of the controls for measurement of $S$.
fakedata.cc <- fakedata
missdex <- sample((1:nrow(fakedata.cc))[fakedata.cc$Y.obs == 0],
size = floor(sum(fakedata.cc$Y.obs == 0) * .8))
fakedata.cc[missdex, ]$S.obs <- NA
fakedata.cc$weights <- ifelse(fakedata.cc$Y.obs == 1, 1, .2)
Now we can create the "psdesign" object, using the entire dataset (including those missing S.obs) and passing the weights to the weights field.
binary.cc <- psdesign(data = fakedata.cc, Z = Z, Y = Y.obs, S = S.obs,
BIP = BIP, weights = weights)
The other augmentation types can be defined by mapping variables to the names BIP, CPV, and/or BSM. The augmentations are handled as described in the previous section: CPV is used as a direct imputation for $S(1)$, and BSM is used as a direct imputation for $S(0)$. BIPs and BSMs are made available in the augmented dataset for use in the integration models which we describe in the next subsection.
For survival outcomes, a key assumption is that the potential surrogate is measured at a fixed time $\tau$ after entry into the study. Any subjects who have a clinical outcome prior to $\tau$ will be removed from the analysis, with a warning. If tau is not specified in the psdesign object, then it is assumed to be 0. Survival outcomes are specified by mapping Y to a Surv object, which requires the survival package:
surv.ps <- psdesign(data = fakedata, Z = Z, Y = Surv(time.obs, event.obs), S = S.obs,
BIP = BIP, CPV = CPV, BSM = BSM)
Integration models
The EML procedure requires an estimate of $F_{S(1) | W}$, and we refer to this as the integration model. Details are available in the help page for add_integration, shown below. Several integration models are implemented, including a parametric model that uses a formula interface to define a regression model, a semiparametric model that specifies a location and a scale model is robust to the specification of the distribution, and a non-parametric model that uses empirical conditional probability estimates for discrete $W$ and $S(1)$.
?add_integration
For this first example, let's use the parametric integration model. We specify the mean model for $S(1) | W$ as a formula. The predictor is generally a function of the BIP and the BSM, if available. We can add the integration model directly to the psdesign object and inspect the results. Note that in the formula, we refer to the variable names in the augmented dataset.
binary.ps <- binary.ps + integrate_parametric(S.1 ~ BIP)
binary.ps
We can add multiple integration models to a psdesign object, say we want a model for $S(0) | W$:
binary.ps + integrate_parametric(S.0 ~ BIP)
In a future version of the package, we will allow for estimation of the joint risk estimands that depend on both $S(0)$ and $S(1)$. We can also use splines, other transformations, and other variables in the formula:
library(splines)
binary.ps + integrate_parametric(S.1 ~ BIP^2)
binary.ps + integrate_parametric(S.1 ~ bs(BIP, df = 3))
binary.ps + integrate_parametric(S.1 ~ BIP + BSM + BSM^2)
These are shown as examples, we will proceed with the simple linear model for integration. The other integration models are called integrate_bivnorm, integrate_nonparametric, and integrate_semiparametric. See their help files for details on the models and their specification.
The next step is to define the risk model. We will proceed with the simple parametric integration model.
Risk models and likelihoods
The risk model is the specification of the distribution for the outcome $Y$ given $S(1)$ and $Z$. We accommodate a variety of flexible specifications for this model, for binary, time-to-event, and count outcomes. We have implemented exponential and weibull survival models, and a flexible specification for binary models, allowing for standard or custom link functions. See the help file for add_riskmodel for more details.
?add_riskmodel
Let's add a simple binary risk model using the logit link. The argument D specifies the number of samples to use for the simulated annealing, also known as empirical integration, in the EML procedure. In general, D should be set to something reasonably large, like 2 or 3 times the sample size.
binary.ps <- binary.ps + risk_binary(model = Y ~ S.1 * Z, D = 5, risk = risk.logit)
binary.ps
Estimation and Bootstrap
We estimate the parameters and bootstrap using the same type of syntax. We can add a "ps_estimate" object, which takes optional arguments start for starting values, and other arguments that are passed to the optim function. The method argument determines the optimization method, we have found that "BFGS" works well in these types of problems and it is the default. Use "pseudo-score" as the method argument for pseudo-score estimation for binary risk models with categorical BIPs.
The ps_bootstrap function takes the additional arguments n.boots for the number of bootstrap replicates, and progress.bar which is a logical that displays a progress bar in the R console if true. It is helpful to pass the estimates as starting values in the bootstrap resampling. With estimates and bootstrap replicates present, printing the psdesign object displays additional information. In real examples you should use more than 10 bootstrap replicates.
binary.est <- binary.ps + ps_estimate(method = "BFGS")
binary.boot <- binary.est + ps_bootstrap(n.boots = 10, progress.bar = FALSE,
start = binary.est$estimates$par, method = "BFGS")
binary.boot
Do it all at once
The next code chunk shows how the model can be defined and estimated all at once.
binary.est <- psdesign(data = fakedata, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP) +
integrate_parametric(S.1 ~ BIP) +
risk_binary(model = Y ~ S.1 * Z, D = 50, risk = risk.logit) +
ps_estimate(method = "BFGS")
Plots and summaries
We provide summary and plotting methods for the psdesign object. If bootstrap replicates are present, the summary method does a test for wide effect modification. Under the parametric risk models implemented in this package, the test for wide effect modification is equivalent to a test that the $S(1):Z$ coefficient is different from 0. This is implemented using a Wald test using the bootstrap estimate of the variance.
Another way to assess wide effect modification is to compute the standardized total gain (STG) [@Gabriel15]. This is implemented in the calc_STG function. The standardized total gain can be interpreted as the area sandwiched between the risk difference curve and the horizontal line at the marginal risk difference. It is a measure of the spread of the distribution of the risk difference, and is a less parametric way to test for wide effect modification. The calc_STG function computes the STG at the estimated parameters, at the bootstrap samples, if present. The function prints the results and invisibly returns a list containing the observed STG, and the bootstrapped STGS.
calc_STG(binary.boot, progress.bar = FALSE)
The summary method also computes the marginal treatment efficacy marginalized over $S(1)$ and compares it to the average treatment efficacy conditional on $S(1)$. This is an assessment of model fit. A warning will be given if the two estimates are dramatically different. These estimates are presented in the summary along with the empirical marginal treatment efficacy.
smary <- summary(binary.boot)
The calc_risk function computes the risk in each treatment arm, and contrasts of the risks. By default it computes the treatment efficacy, but there are other contrast functions available. The contrast function is a function that takes 2 inputs, the $risk_0$ and $risk_1$, and returns some one dimensional function of those two inputs. It must be vectorized. Some built-in functions are "TE" for treatment efficacy $= 1 - risk_1(s)/risk_0(s)$, "RR" for relative risk $= risk_1(s)/risk_0(s)$, "logRR" for log of the relative risk, and "RD" for the risk difference $= risk_1(s) -risk_0(s)$. You can pass the name of the function, or the function itself to calc_risk. See ?calc_risk for more information about contrast functions.
Other arguments of the calc_risk function include t, the time at which to calculate the risk for time-to-event outcomes, n.samps which is the number of samples over the range of S.1 at which the risk will be calculated, and CI.type, which can be set to "pointwise" for pointwise confidence intervals or "band" for a simultaneous confidence band. sig.level is the significance level for the bootstrap confidence intervals. If the outcome is time-to-event and $t$ is not present, then it will use the restricted mean survival time.
head(calc_risk(binary.boot, contrast = "TE", n.samps = 20), 3)
head(calc_risk(binary.boot, contrast = function(R0, R1) 1 - R1/R0, n.samps = 20), 3)
It is easy to plot the risk estimates. By default, the plot method displays the TE contrast, but this can be changed using the same syntax as in calc_risk.
plot(binary.boot, contrast = "TE", lwd = 2)
abline(h = smary$TE.estimates[2], lty = 3)
expit <- function(x) exp(x)/(1 + exp(x))
trueTE <- function(s){
r0 <- expit(-1 - 0 * s)
r1 <- expit(-1 - .75 * s)
1 - r1/r0
}
rug(binary.boot$augdata$S.1)
curve(trueTE(x), add = TRUE, col = "red")
legend("bottomright", legend = c("estimated TE", "95\\% CB", "marginal TE", "true TE"),
col = c("black", "black", "black", "red"), lty = c(1, 2, 3, 1), lwd = c(2, 2, 1, 1))
By default, plots of psdesign objects with bootstrap samples will display simultaneous confidence bands for the curve. These bands $L\alpha$ satisfy
$$
P\left{\sup_{s \in B} | \hat{VE}(s) - VE(s) | \leq L_\alpha \right} \leq 1 - \alpha,
$$
for confidence level $\alpha$. The alternative is to use pointwise confidence intervals, with the option CI.type = "pointwise". These intervals satisfy
$$
P\left{\hat{L}\alpha \leq VE(s) \leq \hat{U}\alpha\right} \leq 1 - \alpha, \mbox{ for all } s.
$$
Different summary measures are available for plotting. The options are "TE" for treatment efficacy = $1 - risk_1(s)/risk_0(s)$, "RR" for relative risk = $risk_1(s)/risk_0(s)$, "logRR" for log of the relative risk, "risk" for the risk in each treatment arm, and "RD" for the risk difference = $risk_1(s) - risk_0(s)$. We can also transform using the log option of plot.
par(mfrow = c(2, 2), mar = c(4, 4, 1, .5))
plot(binary.boot, contrast = "logRR", lwd = 2, col = c("black", "grey75", "grey75"))
plot(binary.boot, contrast = "RR", log = "y", lwd = 2, col = c("black", "grey75", "grey75"))
plot(binary.boot, contrast = "RD", lwd = 2, col = c("black", "grey75", "grey75"))
plot(binary.boot, contrast = "risk", lwd = 2, lty = c(1, 0, 0, 2, 0, 0))
legend("topright", legend = c("R0", "R1"), lty = c(1, 2), lwd = 2)
The calc_risk function is the workhorse that creates the plots. You can call this function directly to obtain estimates, standard errors, and confidence intervals for the estimated risk in each treatment arm and transformations of the risk like TE. The parameter n.samps determines the number of points at which to calculate the risk. The points are evenly spaced over the range of S.1. Use this function to compute other summaries, make plots using ggplot2 or lattice and more.
te.est <- calc_risk(binary.boot, CI.type = "pointwise", n.samps = 200)
head(te.est, 3)
Summary and Conclusion
We have implemented the core methods for principal surrogate evaluation in our pseval package. Our aim was to create a flexible and consistent user interface that allows for the estimation of a wide variety of statistical models in this framework. There has been some other work in this area. The Surrogate package implements the core methods for the evaluation of trial-level surrogates using a meta-analytic framework. It also has a wide variety of models, each implemented in a different function each with a long list of parameters [@surrogate].
Our package uses the + sign to combine function calls into a single object. This is called "overloading the + operator" and is most famously known from the ggplot2 package [@ggplot2]. Conceptually, this was appealing to us because it allows users to build up analysis objects starting from the design, and ending with the estimation. The distinct analysis concepts of the design, risk model specification, integration model, and estimation/bootstrap approaches are separated into distinct function calls, each with a limited number of parameters. This makes it easier for users to keep track of their models, makes it easier to understand the methods involved, and allows for the specification of a wide variety of models by mixing and matching the function calls. This framework will also make it easier to maintain the codebase, and to extend it in the future as the methods evolve. Our package is useful for novice and expert R users alike, and implements an important set of statistical methods for the first time.
Appendix
Additional examples
Plot both types of CI
plot(binary.boot, contrast = "TE", lwd = 2, CI.type = "band")
sbs <- calc_risk(binary.boot, CI.type = "pointwise", n.samps = 200)
lines(Y.lower.CL.2.5 ~ S.1, data = sbs, lty = 3, lwd = 2)
lines(Y.upper.CL.97.5 ~ S.1, data = sbs, lty = 3, lwd = 2)
legend("bottomright", lwd = 2, lty = 1:3,
legend = c("estimate", "simultaneous CI", "pointwise CI"))
Plot with ggplot2
library(ggplot2)
TE.est <- calc_risk(binary.boot, n.samps = 200)
ggplot(TE.est,
aes(x = S.1, y = Y, ymin = Y.lower.CL.0.95, ymax = Y.upper.CL.0.95)) +
geom_line() + geom_ribbon(alpha = .2) + ylab(attr(TE.est, "Y.function"))
Case-control design
cc.fit <- binary.cc + integrate_parametric(S.1 ~ BIP) +
risk_binary(D = 10) + ps_estimate()
cc.fit
Survival outcome
surv.fit <- psdesign(fakedata, Z = Z, Y = Surv(time.obs, event.obs),
S = S.obs, BIP = BIP, CPV = CPV) +
integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1) +
risk_exponential(D = 10) + ps_estimate(method = "BFGS") + ps_bootstrap(n.boots = 20)
surv.fit
plot(surv.fit)
Continuous outcome
fakedata$Y.cont <- log(fakedata$time.obs + 0.01)
cont.fit <- psdesign(fakedata, Z = Z, Y = Y.cont,
S = S.obs, BIP = BIP, CPV = CPV) +
integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1) +
risk_continuous(D = 10) + ps_estimate(method = "BFGS") #+ ps_bootstrap(n.boots = 20)
cont.fit
plot(cont.fit, contrast = "risk")
Categorical S
S.obs.cat and BIP.cat are factors:
with(fakedata, table(S.obs.cat, BIP.cat))
cat.fit <- psdesign(fakedata, Z = Z, Y = Y.obs,
S = S.obs.cat, BIP = BIP.cat) +
integrate_nonparametric(formula = S.1 ~ BIP) +
risk_binary(Y ~ S.1 * Z, D = 10, risk = risk.probit) + ps_estimate(method = "BFGS")
cat.fit
plot(cat.fit)
Pseudo-score
Categorical W allows for estimation of the model using the pseudo-score method for binary outcomes. $S$ may be continuous or categorical:
cat.fit.ps <- psdesign(fakedata, Z = Z, Y = Y.obs,
S = S.obs, BIP = BIP.cat) +
integrate_nonparametric(formula = S.1 ~ BIP) +
risk_binary(Y ~ S.1 * Z, D = 10, risk = risk.logit) + ps_estimate(method = "pseudo-score") +
ps_bootstrap(n.boots = 20, method = "pseudo-score")
summary(cat.fit.ps)
plot(cat.fit.ps)
Bug reports
- Please file bugs and suggestions here as a github issue: https://github.com/sachsmc/pseval/issues.
References
sachsmc/pseval documentation built on May 29, 2019, 12:55 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
library(knitr) require(printr, quietly = TRUE) set.seed(225452)
Methods
Introduction
A valid principal surrogate endpoint can be used as a primary endpoint for evaluating treatments in phase II clinical trials and for predicting individual treatment effects post licensure. A surrogate is considered to be valid if it provides reliable predictions of treatment effects on the clinical endpoint of interest. @Frangakis02 introduced the concept of principal stratification and the definition of a principal surrogate (PS). Informally, a post-treatment intermediate response variable is a principal surrogate if causal effects of the treatment on the clinical outcome only exist when causal effects of the treatment on the intermediate variable exist. The criteria for a PS have been modified and extended in more recent works, with most current literature focusing on wide effect modification as the primary criterion of interest; tests for wide effect modification are implemented in the package.
The goal of PS evaluation is estimation and testing of how treatment efficacy on the clinical outcome of interest varies over subgroups defined by possible treatment and surrogate combinations of interest; this is an effect modification objective. The combinations of interest are called the principal strata and they include a set of unobservable counterfactual responses: responses that would have occurred under a set of conditions counter to the observed conditions. To finesse this problem of unobservable responses, a variety of clever trial designs and estimation approaches have been proposed. Several of these have been implemented in the pseval package [@pseval].
Notation
Let $Z_i$ be the treatment indicator for subject $i$, where 0 indicates the control or standard treatment, and 1 indicates the experimental treatment. We currently only allow for two levels of treatment and assume that the treatment assignments are randomized. Let $S_i$ be the observed value of the intermediate response for subject $i$. Since $S_i$ can be affected by treatment, there are two naturally occurring counterfactual values of $S_i$: $S_i(1)$ under treatment, and $S_i(0)$ under control. Let $s_z$ be the realization of the random variable $S(z)$, for $z \in {0, 1}$. The outcome of interest is denoted $Y_i$. We consider the counterfactual values of $Y_i(0)$ and $Y_i(1)$. We allow for binary, count, and time-to-event outcomes, thus $Y_i$ may be a vector containing a time variable and an event/censoring indicator, i.e. $Y_i = (T_i, \Delta_i)$ where $\Delta_i = 1$ if $T_i$ is an event time, and $\Delta_i = 0$ if $T_i$ is a censoring time. For all of the methods, $S_i(z)$ is only defined if the clinical outcome $Y_i(z)$ does not occur before the potential surrogate $S_i(z)$ is measured at a fixed time $\tau$ after entry into the study. The data analyses only include participants who have not experienced the clinical outcome by time $\tau$. For interpretability all of the methods assume no individual-level treatment effects on $Y$ before $\tau$, which we refer to as the "Equal early individual risk" assumption below.
Estimands
Criteria for $S$ to be a good surrogate are based on risk estimands that condition on the potential intermediate responses. The risk is defined as a mapping $g$ of the cumulative distribution function of $Y(z)$ conditional on the intermediate responses. The joint risk estimands conditions on the candidate surrogate under both level of treatment, $(S(1), S(0))$. $$ risk_1(s_1, s_0) = g\left{F_{s_1}\left[Y(1) | S(0) = s_0, S(1) = s_1\right]\right}, \ risk_0(s_1, s_0) = g\left{F_{s_1}\left[Y(0) | S(0) = s_0, S(1) = s_1\right]\right}. $$ For instance, for a binary outcome, the risk function may simply be the probability $risk_z(s_1, s_0) = P(Y(z) = 1 | S(0) = s_0, S(1) = s_1)$, or for a time-to-event outcome the risk function may be the cumulative distribution function $risk_z(s_1, s_0) = P(Y(z) \leq t | S(0) = s_0, S(1) = s_1)$.
Currently we focus only on marginal risk estimands which condition only on $S(1)$, the intermediate response or biomarker under active treatment:
$$ risk_1(s_1) = g\left{F_{s_1}\left[Y(1) | S(1) = s_1\right]\right}, \ risk_0(s_1) = g\left{F_{s_1}\left[Y(0) | S(1) = s_1\right]\right}. $$
Neither of the joint risk estimands are indentifiable in a standard randomized trial, as either S(0) or S(1) or both will be missing for each subject. In the special case where $S(0)$ is constant, such as the immune response to HIV antigens or Hep B in the placebo arm of a vaccine trial, the joint and marginal risk estimands are equivalent. This special case is referred to as case constant biomarker (CB) in much of the literature [@Gilbert08]; S_i(0) = c for subjects i. This may occur outside the vaccine setting when one considers the AUC of a treatment drug as a surrogate; those receiving placebo will have no drug and therefore all placebo AUC will be 0. Under assumptions given below, and in the case CB setting, the marginal risk estimand is indentifiable in the treatment arm.
As well, as will be outlined below, there are specific trial augmentations that allow for the measurement or imputation of the missing counterfactual Ss. Under one of these augmentations, case CB can sometimes be induced by considering a function of the a candidate surrogate for evaluation. Greater detail on this point given below.
Specification of the distributions of $Y(z) | S(1)$ determines the likelihood, we will denote this as $f(y | \beta, s_1, z)$. If $S(1)$ were fully observed, simple maximum likelihood estimation could be used. The key challenge in estimating these risk estimands is solving the problem of conditioning on counterfactual values that are not observable for at least a subset of subjects in a randomized trial. This involves integrating out missing values based on some models and/or set of assumptions.
Principal Surrogate Criteria
@Frangakis02 gave a single criterion for a biomarker S to be a PS: causal effects of the treatment on the clinical outcome only exist when causal effects of the treatment on the intermediate variable exist. In general this can only be evaluated using the joint risk estimands, which consider not only the counterfactual values of the biomarker under treatment, but also under control $S(0)$. However, in the special case where all $S(0)$ values are constant, say at level $C$, such as an immune response to HIV in a HIV negative population pre-vaccination this criteria, often referred to as average causal necessity (ACN), can by written in terms of the marginal risk estimands as:
$$ risk_1(C)=risk_0(C) $$
More recently, other works @Gilbert08, @Wolfson10, @Huang12, @Gabriel14, and @Gabriel15b have suggested that this criterion is both too restrictive and in some cases can be vacuously true. Instead most current works suggest that the wide effect modification (WEM) criterion is of primary importance, ACN being of secondary importance. WEM is given formally in terms of the risk estimands and a known contrast function $h$ satisfying $h(x, y) = 0$ if and only if $x = y$ by:
$$ |h(risk_1(s_1),risk_0(s_1)) - h(risk_1(s{_1}^),risk_0(s{_1}^))|>\delta $$
for at least some $s_1 \neq s_{1}^*$ and $\delta>0$, with the larger the $\delta$ the better. To evaluate WEM and ACN we need to identify the risk estimands.
Augmentation and Assumptions
We first make three standard assumptions used in much of the literature for absorbing events outcomes:
- Stable Unit Treatment Value Assumption (SUTVA): Observations on the independent units in the trial should be unaffected by the treatment assignment of other units.
- Ignorable Treatment Assignment: The observed treatment assignment does not change the counterfactual clinical outcome.
- Equal individual risk up to the time of candidate surrogate measurement $\tau$.
In time-to-event settings one more assumption is needed:
- Non-informative censoring.
It should be noted that the equal individual risk assumption requires that time-to-event analysis start at time $\tau$, rather than at randomization.
@Wolfson10 outlines how these assumptions are needed for identification of the risk estimands. Now to deal with the missing $S(1)$ values among those with $Z = 0$, we next focus on three trial augmentations: Baseline immunogenicity predictor (BIP), closeout placebo vaccination (CPV), and baseline surrogate measurement (BSM). For further details on these augmentations, we refer you to @Follmann06, @Gilbert08, @Gabriel14, and @Gabriel15b.
BIP
Briefly, a BIP $W$ is any baseline measurement or set of measurements that is highly correlated with $S$. It is particularly useful if $W$ is unlikely to be associated with the clinical outcome after conditioning on $S$, i.e. $Y \perp W | S(1)$; some of the methods leverage this assumption. The BIP $W$ is used to integrate out the missing $S(1)$ among those with $Z = 0$ based on a model for $S(1) | W$ that is estimated among those with $Z = 1$. We describe how this model is used in the next section.
The assumptions needed for a BIP to be useful depend on the risk model used. If the BIP is included in the risk model, only the assumption of no interaction with treatment and the candidate surrogate are needed. However, if the BIP is not included in the risk model, the assumption that that clinical outcome is independent of the BIP given the candidate surrogate is needed. Although not a requirement for identification of the risk estimands, it has been found in most simulations studies that a correlation between the BIP and $S(1)$ of greater than 0.7 is needed for unbiased estimation in finite samples.
CPV
Under a CPV augmented design, control recipients that do not have events at the end of the follow-up period are given the experimental treatment. Then their intermediate response is measured at some time post treatment. This measurement is then used as a direct imputation for the missing $S(1)$. This augmentation was developed in the setting of vaccine trials, where the surrogate is an immune response and the outcome is infection. One set of conservative assumptions to use CPV as a direct imputation for $S(1)$ are given in @Wolfson10 are:
- Time constancy of the true intermediate response under active treatment, $S(1)=S_{CPV}$ almost surely, for placebo recipients that are crossed over at the end of the trial, where $S_{CPV}$ is the measurement of the candidate surrogate after crossover treatment of the placebo subjects.
- No events (infections) during the close-out period
BSM
@Gabriel14 suggested the baseline augmentation BSM, which is a pre-treatment measurement of the candidate PS, denoted $S_B$. The BSM may be a good predictor of $S(1)$ without any further assumptions. It can be used in the same way as a BIP. Alternatively you can transform $S(1) - S_B$ and use this as the candidate surrogate, further increasing the association with the BSM/BIP. Under the BSM assumption outlined in @Gabriel14;
- Time constancy of the true intermediate response under control,
then $S(0)=S_{BSM}$ almost surely. You do not need this assumption to use a BSM, but if it holds then it induces the CB case, thus the joint and marginal risk estimands are equivalent.
Estimated Maximum Likelihood
Let $f(y | \beta, s_1, z)$ denote the density of $Y | S(1), Z$ with parameters $\beta$. Further let $R_i$ denote the indicator for missingness in $S_i(1)$. We proceed to estimate $\beta$ by maximizing
$$ \prod_{i = 1}^n \left{f(Y_i | \beta, S_i(1), Z_i)\right}^R_i \left{\int f(Y_i | \beta, s, Z_i) \, d \hat{F}_{S(1) | W}(s | W_i)\right}^{1 - R_i} $$
with respect to $\beta$.
This procedure is called estimated maximum likelihood (EML) and was developed in @Pepe91. The key idea is that we are averaging the likelihood contributions for subjects missing $S(1)$ with respect to the estimated distribution of $S(1) | W$. A BIP $W$ that is strongly associated with $S(1)$ is needed for adequate performance.
Closed-form inference is not available for EML estimates, thus we recommend use of the bootstrap for estimation of standard errors. It was suggested as an approach to principal surrogate evaluation by @Gilbert08 and @Huang11.
Pseudoscore
@Huang12 suggest a different estimation procedure that does have a closed form variance estimator. Instead of numerically optimizing the estimated likelihood, the pseudoscore approach iteratively finds the solution to weighted versions of the score equations. Pseudoscore estimates were also suggested in @WolfsonDiss and implemented for several special cases in @Huang12. We have implemented here only one of the special cases: categorical $BIP$ and binary $Y$ ($S$ may be continuous or categorical). In addition to having closed form variance estimators, it has been argued that the pseudo-score estimators are more efficient than the EML estimators. The closed form variance estimates are not yet implemented.
Package features
Typically, users would have to code up the likelihood, integration models, and perform the optimization themselves. This is beyond the reach of many researchers who desire to use these methods. The goal of pseval is to correctly implement these methods with a flexible and user-friendly interface, enabling researchers to implement and interpret a wide variety of models.
The pseval package allows users to specify the type of augmented design that is used in their study, specify the form of the risk model along with the distribution of $Y | S(1)$, and specify different integration models to estimate the distribution of $S(1) | W$. Then the likelihood can be maximized and bootstraps run. Post-estimation summaries are available to display and analyze the treatment efficacy as a function of $S(1)$. All of this is implemented with a flexible and familiar interface.
Package information
Installation
pseval is an R package aimed at implementing existing methods for surrogate evaluation using a flexible and common interface. Development will take place on the Github page, and the current version of the package can be installed as shown below. First you must install the devtools package, if you haven't already install.packages("devtools").
devtools::install_github("sachsmc/pseval")
or it can be installed from CRAN:
install.packages("pseval")
Usage
Here we will walk through some basic analyses from the point of view of a new R user. Along the way we will highlight the main features of pseval. pseval supports both binary outcomes and time-to-event, thus we will also need to load the survival package.
library(pseval) library(survival)
First let's create an example dataset. The \pkg{pseval} package provides the function generate_example_data which takes a single argument: the sample size.
set.seed(1492) fakedata <- generate_example_data(n = 800) head(fakedata)
The example data includes both a time-to-event outcome, a binary outcome, a surrogate, a BIP, CPV, and BSM, and a categorical version of the surrogate. The true model for the time is exponential, with parameters (intercept) = -1, S(1) = 0.0, Z = 0.0, S(1):Z = -0.75. The true model for binary is logistic, with the same parameter values.
In the above table S.obs.cat and BIP.cat are formed as S.obs.cat <- factor(S.obs,levels=c(-Inf, quantile(c(S.0, S.1), c(.25, .5, .75), na.rm = TRUE), Inf)) and similarly for BIP.cat. Alternatively a user could input arbitrary numeric values to represent different discrete subgroups (e.g., 0s and 1s to denote 2 subgroups).
The "psdesign" object
We begin by creating a "psdesign" object with the synonymous function. This is the object that combines the raw dataset with information about the study design and the structure of the data. Subsequent analysis will operate on this psdesign object. It is designed to be analogous to the svydesign function in the survey package (https://CRAN.R-project.org/package=survey). The first argument is the data frame where the data are stored. All subsequent arguments describe the mappings from the variable names in the data frame to important variables in the PS analysis, using the same notation as above. An optional weights argument describes the sampling weights, if present. Our first analysis will use the binary version of the outcome, with continuous $S.1$ and the BIP labeled $BIP$. The object has a print method, so we can inspect the result.
binary.ps <- psdesign(data = fakedata, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP) binary.ps
The printout displays a brief description of the data, including the empirical treatment efficacy estimate, the variables used in the analysis and their corresponding variables in the original dataset. Finally the printout invites the user to see the help page for add_integration, in order to add an integration model to the psdesign object, the next step in the analysis.
Missing values in the $S$ variable are allowed. Note that any cases where $S(1)$ is missing will be integrated over in the likelihood or score equations. Thus any cases that experienced an event prior to the time $\tau$ when the surrogate was measured should be excluded from the dataset. The equal individual risk assumption allows us to make causal inferences even after excluding such cases.
psdesign easily accommodates case-control or case-cohort sampling. In this case, the surrogate $S$ is only measured on a subset of the data, inducing missingness in $S$ by design. Let's modify the fake dataset to see how it works. We're going to sample all of the cases, and 20% of the controls for measurement of $S$.
fakedata.cc <- fakedata missdex <- sample((1:nrow(fakedata.cc))[fakedata.cc$Y.obs == 0], size = floor(sum(fakedata.cc$Y.obs == 0) * .8)) fakedata.cc[missdex, ]$S.obs <- NA fakedata.cc$weights <- ifelse(fakedata.cc$Y.obs == 1, 1, .2)
Now we can create the "psdesign" object, using the entire dataset (including those missing S.obs) and passing the weights to the weights field.
binary.cc <- psdesign(data = fakedata.cc, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP, weights = weights)
The other augmentation types can be defined by mapping variables to the names BIP, CPV, and/or BSM. The augmentations are handled as described in the previous section: CPV is used as a direct imputation for $S(1)$, and BSM is used as a direct imputation for $S(0)$. BIPs and BSMs are made available in the augmented dataset for use in the integration models which we describe in the next subsection.
For survival outcomes, a key assumption is that the potential surrogate is measured at a fixed time $\tau$ after entry into the study. Any subjects who have a clinical outcome prior to $\tau$ will be removed from the analysis, with a warning. If tau is not specified in the psdesign object, then it is assumed to be 0. Survival outcomes are specified by mapping Y to a Surv object, which requires the survival package:
surv.ps <- psdesign(data = fakedata, Z = Z, Y = Surv(time.obs, event.obs), S = S.obs, BIP = BIP, CPV = CPV, BSM = BSM)
Integration models
The EML procedure requires an estimate of $F_{S(1) | W}$, and we refer to this as the integration model. Details are available in the help page for add_integration, shown below. Several integration models are implemented, including a parametric model that uses a formula interface to define a regression model, a semiparametric model that specifies a location and a scale model is robust to the specification of the distribution, and a non-parametric model that uses empirical conditional probability estimates for discrete $W$ and $S(1)$.
?add_integration
For this first example, let's use the parametric integration model. We specify the mean model for $S(1) | W$ as a formula. The predictor is generally a function of the BIP and the BSM, if available. We can add the integration model directly to the psdesign object and inspect the results. Note that in the formula, we refer to the variable names in the augmented dataset.
binary.ps <- binary.ps + integrate_parametric(S.1 ~ BIP) binary.ps
We can add multiple integration models to a psdesign object, say we want a model for $S(0) | W$:
binary.ps + integrate_parametric(S.0 ~ BIP)
In a future version of the package, we will allow for estimation of the joint risk estimands that depend on both $S(0)$ and $S(1)$. We can also use splines, other transformations, and other variables in the formula:
library(splines) binary.ps + integrate_parametric(S.1 ~ BIP^2) binary.ps + integrate_parametric(S.1 ~ bs(BIP, df = 3)) binary.ps + integrate_parametric(S.1 ~ BIP + BSM + BSM^2)
These are shown as examples, we will proceed with the simple linear model for integration. The other integration models are called integrate_bivnorm, integrate_nonparametric, and integrate_semiparametric. See their help files for details on the models and their specification.
The next step is to define the risk model. We will proceed with the simple parametric integration model.
Risk models and likelihoods
The risk model is the specification of the distribution for the outcome $Y$ given $S(1)$ and $Z$. We accommodate a variety of flexible specifications for this model, for binary, time-to-event, and count outcomes. We have implemented exponential and weibull survival models, and a flexible specification for binary models, allowing for standard or custom link functions. See the help file for add_riskmodel for more details.
?add_riskmodel
Let's add a simple binary risk model using the logit link. The argument D specifies the number of samples to use for the simulated annealing, also known as empirical integration, in the EML procedure. In general, D should be set to something reasonably large, like 2 or 3 times the sample size.
binary.ps <- binary.ps + risk_binary(model = Y ~ S.1 * Z, D = 5, risk = risk.logit) binary.ps
Estimation and Bootstrap
We estimate the parameters and bootstrap using the same type of syntax. We can add a "ps_estimate" object, which takes optional arguments start for starting values, and other arguments that are passed to the optim function. The method argument determines the optimization method, we have found that "BFGS" works well in these types of problems and it is the default. Use "pseudo-score" as the method argument for pseudo-score estimation for binary risk models with categorical BIPs.
The ps_bootstrap function takes the additional arguments n.boots for the number of bootstrap replicates, and progress.bar which is a logical that displays a progress bar in the R console if true. It is helpful to pass the estimates as starting values in the bootstrap resampling. With estimates and bootstrap replicates present, printing the psdesign object displays additional information. In real examples you should use more than 10 bootstrap replicates.
binary.est <- binary.ps + ps_estimate(method = "BFGS") binary.boot <- binary.est + ps_bootstrap(n.boots = 10, progress.bar = FALSE, start = binary.est$estimates$par, method = "BFGS") binary.boot
Do it all at once
The next code chunk shows how the model can be defined and estimated all at once.
binary.est <- psdesign(data = fakedata, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP) + integrate_parametric(S.1 ~ BIP) + risk_binary(model = Y ~ S.1 * Z, D = 50, risk = risk.logit) + ps_estimate(method = "BFGS")
Plots and summaries
We provide summary and plotting methods for the psdesign object. If bootstrap replicates are present, the summary method does a test for wide effect modification. Under the parametric risk models implemented in this package, the test for wide effect modification is equivalent to a test that the $S(1):Z$ coefficient is different from 0. This is implemented using a Wald test using the bootstrap estimate of the variance.
Another way to assess wide effect modification is to compute the standardized total gain (STG) [@Gabriel15]. This is implemented in the calc_STG function. The standardized total gain can be interpreted as the area sandwiched between the risk difference curve and the horizontal line at the marginal risk difference. It is a measure of the spread of the distribution of the risk difference, and is a less parametric way to test for wide effect modification. The calc_STG function computes the STG at the estimated parameters, at the bootstrap samples, if present. The function prints the results and invisibly returns a list containing the observed STG, and the bootstrapped STGS.
calc_STG(binary.boot, progress.bar = FALSE)
The summary method also computes the marginal treatment efficacy marginalized over $S(1)$ and compares it to the average treatment efficacy conditional on $S(1)$. This is an assessment of model fit. A warning will be given if the two estimates are dramatically different. These estimates are presented in the summary along with the empirical marginal treatment efficacy.
smary <- summary(binary.boot)
The calc_risk function computes the risk in each treatment arm, and contrasts of the risks. By default it computes the treatment efficacy, but there are other contrast functions available. The contrast function is a function that takes 2 inputs, the $risk_0$ and $risk_1$, and returns some one dimensional function of those two inputs. It must be vectorized. Some built-in functions are "TE" for treatment efficacy $= 1 - risk_1(s)/risk_0(s)$, "RR" for relative risk $= risk_1(s)/risk_0(s)$, "logRR" for log of the relative risk, and "RD" for the risk difference $= risk_1(s) -risk_0(s)$. You can pass the name of the function, or the function itself to calc_risk. See ?calc_risk for more information about contrast functions.
Other arguments of the calc_risk function include t, the time at which to calculate the risk for time-to-event outcomes, n.samps which is the number of samples over the range of S.1 at which the risk will be calculated, and CI.type, which can be set to "pointwise" for pointwise confidence intervals or "band" for a simultaneous confidence band. sig.level is the significance level for the bootstrap confidence intervals. If the outcome is time-to-event and $t$ is not present, then it will use the restricted mean survival time.
head(calc_risk(binary.boot, contrast = "TE", n.samps = 20), 3) head(calc_risk(binary.boot, contrast = function(R0, R1) 1 - R1/R0, n.samps = 20), 3)
It is easy to plot the risk estimates. By default, the plot method displays the TE contrast, but this can be changed using the same syntax as in calc_risk.
plot(binary.boot, contrast = "TE", lwd = 2) abline(h = smary$TE.estimates[2], lty = 3) expit <- function(x) exp(x)/(1 + exp(x)) trueTE <- function(s){ r0 <- expit(-1 - 0 * s) r1 <- expit(-1 - .75 * s) 1 - r1/r0 } rug(binary.boot$augdata$S.1) curve(trueTE(x), add = TRUE, col = "red") legend("bottomright", legend = c("estimated TE", "95\\% CB", "marginal TE", "true TE"), col = c("black", "black", "black", "red"), lty = c(1, 2, 3, 1), lwd = c(2, 2, 1, 1))
By default, plots of psdesign objects with bootstrap samples will display simultaneous confidence bands for the curve. These bands $L\alpha$ satisfy
$$ P\left{\sup_{s \in B} | \hat{VE}(s) - VE(s) | \leq L_\alpha \right} \leq 1 - \alpha, $$
for confidence level $\alpha$. The alternative is to use pointwise confidence intervals, with the option CI.type = "pointwise". These intervals satisfy
$$ P\left{\hat{L}\alpha \leq VE(s) \leq \hat{U}\alpha\right} \leq 1 - \alpha, \mbox{ for all } s. $$
Different summary measures are available for plotting. The options are "TE" for treatment efficacy = $1 - risk_1(s)/risk_0(s)$, "RR" for relative risk = $risk_1(s)/risk_0(s)$, "logRR" for log of the relative risk, "risk" for the risk in each treatment arm, and "RD" for the risk difference = $risk_1(s) - risk_0(s)$. We can also transform using the log option of plot.
par(mfrow = c(2, 2), mar = c(4, 4, 1, .5)) plot(binary.boot, contrast = "logRR", lwd = 2, col = c("black", "grey75", "grey75")) plot(binary.boot, contrast = "RR", log = "y", lwd = 2, col = c("black", "grey75", "grey75")) plot(binary.boot, contrast = "RD", lwd = 2, col = c("black", "grey75", "grey75")) plot(binary.boot, contrast = "risk", lwd = 2, lty = c(1, 0, 0, 2, 0, 0)) legend("topright", legend = c("R0", "R1"), lty = c(1, 2), lwd = 2)
The calc_risk function is the workhorse that creates the plots. You can call this function directly to obtain estimates, standard errors, and confidence intervals for the estimated risk in each treatment arm and transformations of the risk like TE. The parameter n.samps determines the number of points at which to calculate the risk. The points are evenly spaced over the range of S.1. Use this function to compute other summaries, make plots using ggplot2 or lattice and more.
te.est <- calc_risk(binary.boot, CI.type = "pointwise", n.samps = 200) head(te.est, 3)
Summary and Conclusion
We have implemented the core methods for principal surrogate evaluation in our pseval package. Our aim was to create a flexible and consistent user interface that allows for the estimation of a wide variety of statistical models in this framework. There has been some other work in this area. The Surrogate package implements the core methods for the evaluation of trial-level surrogates using a meta-analytic framework. It also has a wide variety of models, each implemented in a different function each with a long list of parameters [@surrogate].
Our package uses the + sign to combine function calls into a single object. This is called "overloading the + operator" and is most famously known from the ggplot2 package [@ggplot2]. Conceptually, this was appealing to us because it allows users to build up analysis objects starting from the design, and ending with the estimation. The distinct analysis concepts of the design, risk model specification, integration model, and estimation/bootstrap approaches are separated into distinct function calls, each with a limited number of parameters. This makes it easier for users to keep track of their models, makes it easier to understand the methods involved, and allows for the specification of a wide variety of models by mixing and matching the function calls. This framework will also make it easier to maintain the codebase, and to extend it in the future as the methods evolve. Our package is useful for novice and expert R users alike, and implements an important set of statistical methods for the first time.
Appendix
Additional examples
Plot both types of CI
plot(binary.boot, contrast = "TE", lwd = 2, CI.type = "band") sbs <- calc_risk(binary.boot, CI.type = "pointwise", n.samps = 200) lines(Y.lower.CL.2.5 ~ S.1, data = sbs, lty = 3, lwd = 2) lines(Y.upper.CL.97.5 ~ S.1, data = sbs, lty = 3, lwd = 2) legend("bottomright", lwd = 2, lty = 1:3, legend = c("estimate", "simultaneous CI", "pointwise CI"))
Plot with ggplot2
library(ggplot2) TE.est <- calc_risk(binary.boot, n.samps = 200) ggplot(TE.est, aes(x = S.1, y = Y, ymin = Y.lower.CL.0.95, ymax = Y.upper.CL.0.95)) + geom_line() + geom_ribbon(alpha = .2) + ylab(attr(TE.est, "Y.function"))
Case-control design
cc.fit <- binary.cc + integrate_parametric(S.1 ~ BIP) + risk_binary(D = 10) + ps_estimate() cc.fit
Survival outcome
surv.fit <- psdesign(fakedata, Z = Z, Y = Surv(time.obs, event.obs), S = S.obs, BIP = BIP, CPV = CPV) + integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1) + risk_exponential(D = 10) + ps_estimate(method = "BFGS") + ps_bootstrap(n.boots = 20) surv.fit plot(surv.fit)
Continuous outcome
fakedata$Y.cont <- log(fakedata$time.obs + 0.01) cont.fit <- psdesign(fakedata, Z = Z, Y = Y.cont, S = S.obs, BIP = BIP, CPV = CPV) + integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1) + risk_continuous(D = 10) + ps_estimate(method = "BFGS") #+ ps_bootstrap(n.boots = 20) cont.fit plot(cont.fit, contrast = "risk")
Categorical S
S.obs.cat and BIP.cat are factors:
with(fakedata, table(S.obs.cat, BIP.cat))
cat.fit <- psdesign(fakedata, Z = Z, Y = Y.obs, S = S.obs.cat, BIP = BIP.cat) + integrate_nonparametric(formula = S.1 ~ BIP) + risk_binary(Y ~ S.1 * Z, D = 10, risk = risk.probit) + ps_estimate(method = "BFGS") cat.fit plot(cat.fit)
Pseudo-score
Categorical W allows for estimation of the model using the pseudo-score method for binary outcomes. $S$ may be continuous or categorical:
cat.fit.ps <- psdesign(fakedata, Z = Z, Y = Y.obs, S = S.obs, BIP = BIP.cat) + integrate_nonparametric(formula = S.1 ~ BIP) + risk_binary(Y ~ S.1 * Z, D = 10, risk = risk.logit) + ps_estimate(method = "pseudo-score") + ps_bootstrap(n.boots = 20, method = "pseudo-score") summary(cat.fit.ps) plot(cat.fit.ps)
Bug reports
- Please file bugs and suggestions here as a github issue: https://github.com/sachsmc/pseval/issues.
References
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.