Introduction to Principal Surrogate Evaluation in R

Michael C Sachs and Erin E Gabriel

January 24, 2019

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. Frangakis and Rubin (2002) 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 (Sachs and Gabriel 2016).

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 (Gilbert and Hudgens 2008); S_i(0) = c for subjects i. This may occur outside the vaccine setting when one considers the AUC of a treament drug as a surrogate; those recieving 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.

Prinicipal Surrogate Criteria

Frangakis and Rubin (2002) 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 Gilbert and Hudgens (2008), Wolfson and Gilbert (2010), Huang, Gilbert, and Wolfson (2013), Gabriel and Gilbert (2014), and E. E. Gabriel and Follmann (2015) 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:

In time-to-event settings one more assumption is needed:

It should be noted that the equal individual risk assumption requires that time-to-event analysis start at time \(\tau\), rather than at randomization.

Wolfson and Gilbert (2010) 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 Follmann (2006), Gilbert and Hudgens (2008), Gabriel and Gilbert (2014), and E. E. Gabriel and Follmann (2015).

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 Wolfson and Gilbert (2010) 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

Gabriel and Gilbert (2014) 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 Gabriel and Gilbert (2014);

  • 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 Pepe and Fleming (1991). 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 prinicipal surrogate evaluation by Gilbert and Hudgens (2008) and Huang and Gilbert (2011).

##Pseudoscore

Huang, Gilbert, and Wolfson (2013) 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 Wolfson (2009) and implemented for several special cases in Huang, Gilbert, and Wolfson (2013). 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").

or it can be installed from CRAN:

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.

First let’s create an example dataset. The package provides the function generate_example_data which takes a single argument: the sample size.

##   Z        BIP       CPV         BSM       S.obs  time.obs event.obs Y.obs
## 1 0  0.3353179 1.4851399  0.45961614  0.35268095 0.3301972         0     0
## 2 0  1.4536863 2.6379400  1.39591042  1.46688905 0.1195136         1     0
## 3 0 -0.7243934        NA -0.62723499 -0.73190763 0.2631222         1     1
## 4 0 -0.1183592 0.9421504  0.07738308 -0.01833409 0.1373458         1     0
## 5 0 -0.2352566        NA -0.14971448 -0.18470242 0.8543703         1     1
## 6 0 -0.7782851 0.1159434 -0.65721609 -0.66313714 0.2200481         1     0
##        S.obs.cat         BIP.cat
## 1 (-0.198,0.503]  (0.0574,0.766]
## 2    (1.36, Inf]    (0.766, Inf]
## 3  (-Inf,-0.198]   (-Inf,-0.678]
## 4 (-0.198,0.503] (-0.678,0.0574]
## 5 (-0.198,0.503] (-0.678,0.0574]
## 6  (-Inf,-0.198]   (-Inf,-0.678]

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.

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##  None present, see ?add_integration for information on integration models.
## 
## Risk models: 
##  None present, see ?add_riskmodel for information on risk models.
##  No estimates present, see ?ps_estimate.
##  No bootstraps present, see ?ps_bootstrap.

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

Now we can create the "psdesign" object, using the entire dataset (including those missing S.obs) and passing the weights to the weights field.

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:

## Warning in psdesign(data = fakedata, Z = Z, Y = Surv(time.obs,
## event.obs), : tau missing in psdesign: assuming that the surrogate S was
## measured at time 0.

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 R Documentation

Integration models

Description

Add integration model to a psdesign object

Usage 

add_integration(psdesign, integration)

Arguments

psdesign

A psdesign object

integration

An integration object

Details

This is a list of the available integration models. The fundamental problem in surrogate evaluation is that there are unobserved values of the counterfactual surrogate responses S(1). In the estimated maximum likelihood framework, for subjects missing the S(1) values, we use an auxiliary pre-treatment variable or set of variables W that is observed for every subject to estimate the distribution of S(1) | W. Typically, this W is a BIP. Then for each missing S(1), we integrate likelihood contributions over each non-missing S(1) given their value of W, and average over the contributions.

  • integrate_parametric This is a parametric integration model that fits a linear model for the mean of S(1) | W and assumes a Gaussian distribution.

  • integrate_bivnorm This is another parametric integration model that assumes that S(1) and W are jointly normally distributed. The user must specify their mean, variances and correlation.

  • integrate_nonparametric This is a non-parametric integration model that is only valid for categorical S(1) and W. It uses the observed proportions to estimate the joint distribution of S(1), W.

  • integrate_semiparametric This is a semi-parametric model that uses the semi-parametric location scale model of Heagerty and Pepe (1999). Models are specified for the location of S(1) | W and the scale of S(1) | W. Then integrations are drawn from the empirical distribution of the residuals from that model, which are then transformed to the appropriate location and scale.

Examples 


test <- psdesign(generate_example_data(n = 100), Z = Z, Y = Y.obs, S = S.obs, BIP = BIP)
add_integration(test, integrate_parametric(S.1 ~ BIP))
test + integrate_parametric(S.1 ~ BIP)  # same as above

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.

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##  None present, see ?add_riskmodel for information on risk models.
##  No estimates present, see ?ps_estimate.
##  No bootstraps present, see ?ps_bootstrap.

We can add multiple integration models to a psdesign object, say we want a model for \(S(0) | W\):

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
##   integration model for  S.0 :
##       integrate_parametric(formula = S.0 ~ BIP )
## 
## Risk models: 
##  None present, see ?add_riskmodel for information on risk models.
##  No estimates present, see ?ps_estimate.
##  No bootstraps present, see ?ps_bootstrap.

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:

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 R Documentation

Add risk model to a psdesign object

Description

Add risk model to a psdesign object

Usage 

add_riskmodel(psdesign, riskmodel)

Arguments

psdesign

A psdesign object

riskmodel

A risk model object, from the list above

Details

The risk model component specifies the likelihood for the data. This involves specifying the distribution of the outcome variable, whether it is binary or time-to-event, and specifying how the surrogate S(1) and the treatment Z interact and affect the outcome. We use the formula notation to be consistent with other regression type models in R. Below is a list of available risk models.

  • risk_binary This is a generic risk model for binary outcomes. The user can specify the formula, and link function using either risk.logit for the logistic link, or risk.probit for the probit link. Custom link functions may also be specified, which take a single numeric vector argument, and returns a vector of corresponding probabilities.

  • risk_weibull This is a parameterization of the Weibull model for time-to-event outcomes that is consistent with that of rweibull. The user specifies the formula for the linear predictor of the scale parameter.

  • risk_exponential This is a simple exponential model for a time-to-event outcome.

  • risk_poisson This is a Poisson model for count outcomes. It allows for offsets in the formula.

  • risk_continuous This is a Gaussian model for continuous outcomes. It assumes that larger values of the outcome are harmful (e.g. blood pressure)

Examples 

test <- psdesign(generate_example_data(n = 100), Z = Z, Y = Y.obs, S = S.obs, BIP = BIP) +
     integrate_parametric(S.1 ~ BIP)
add_riskmodel(test, risk_binary())
test + risk_binary() # same as above

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.

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(model = Y ~ S.1 * Z, D = 50, risk = risk.logit )
## 
##  No estimates present, see ?ps_estimate.
##  No bootstraps present, see ?ps_bootstrap.

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.

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(model = Y ~ S.1 * Z, D = 50, risk = risk.logit )
## 
## Estimated parameters:
## (Intercept)         S.1           Z       S.1:Z 
##      -0.920      -0.028      -0.220      -1.133 
##  Convergence:  TRUE 
## 
## Bootstrap replicates:
##             Estimate boot.se lower.CL.2.5. upper.CL.97.5.  p.value
## (Intercept)   -0.920   0.182        -1.286         -0.580 4.02e-07
## S.1           -0.028   0.128        -0.276          0.220 8.27e-01
## Z             -0.220   0.250        -0.697          0.277 3.80e-01
## S.1:Z         -1.133   0.214        -1.581         -0.780 1.29e-07
## 
##   Out of 500 bootstraps,  500 converged ( 100 %)
## 
##   Test for wide effect modification on 1 degree of freedom. 2-sided p value  < .0001

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) (Gabriel, Sachs, and Gilbert 2015). 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.

## $obsSTG
## [1] 0.3397774
## 
## $bootstraps
##    STG.boot.se STG.lower.CL.2.5 STG.upper.CL.97.5
## V1   0.1243311        0.1573031         0.6382418

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.

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights    BIP
## 1 0 0  NA  0.3527          1  0.335
## 2 0 0  NA  1.4669          1  1.454
## 3 0 1  NA -0.7319          1 -0.724
## 4 0 0  NA -0.0183          1 -0.118
## 5 0 1  NA -0.1847          1 -0.235
## 6 0 0  NA -0.6631          1 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(model = Y ~ S.1 * Z, D = 50, risk = risk.logit )
## 
## Estimated parameters:
## (Intercept)         S.1           Z       S.1:Z 
##      -0.920      -0.028      -0.220      -1.133 
##  Convergence:  TRUE 
## 
## Bootstrap replicates:
##             Estimate boot.se lower.CL.2.5. upper.CL.97.5.  p.value
## (Intercept)   -0.920   0.182        -1.286         -0.580 4.02e-07
## S.1           -0.028   0.128        -0.276          0.220 8.27e-01
## Z             -0.220   0.250        -0.697          0.277 3.80e-01
## S.1:Z         -1.133   0.214        -1.581         -0.780 1.29e-07
## 
##   Out of 500 bootstraps,  500 converged ( 100 %)
## 
##   Test for wide effect modification on 1 degree of freedom. 2-sided p value  < .0001 
## 
## Treatment Efficacy: 
## empirical  marginal     model 
##     0.526     0.526     0.539 
##  Model-based average TE is 2.3 % different from the empirical and 2.3 % different from the marginal.

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.

##           S.1          Y        R0        R1 Y.boot.se Y.upper.CL.0.95
## V1 -2.2756987 -1.7437221 0.2980453 0.8177536 1.1622104     -0.30455106
## V2 -1.4262708 -1.1360482 0.2930970 0.6260692 0.6957994     -0.05541741
## V3 -0.5973759 -0.3532827 0.2883149 0.3901715 0.3328793      0.29675970
##    Y.lower.CL.0.95 R0.boot.se R0.upper.CL.0.95 R0.lower.CL.0.95 R1.boot.se
## V1       -3.780389 0.08994238        0.4766278        0.1188411 0.06911306
## V2       -2.556452 0.06901664        0.4331237        0.1468385 0.07592515
## V3       -1.275280 0.04941685        0.4007098        0.1734875 0.05079824
##    R1.upper.CL.0.95 R1.lower.CL.0.95
## V1        0.9368827        0.6720409
## V2        0.7762517        0.4768403
## V3        0.5248493        0.2834909
##            S.1           Y        R0        R1 Y.boot.se Y.upper.CL.0.95
## V1 -0.97417991 -0.71327775 0.2904830 0.4976780 0.4840781       0.1395560
## V2 -0.11875337  0.05966359 0.2855748 0.2685364 0.1882398       0.4746753
## V3 -0.09236484  0.08009338 0.2854242 0.2625636 0.1820450       0.4835707
##    Y.lower.CL.0.95 R0.boot.se R0.upper.CL.0.95 R0.lower.CL.0.95 R1.boot.se
## V1      -1.6775172 0.05815888        0.4084405        0.1763127 0.06531273
## V2      -0.4357974 0.03903555        0.3909614        0.2043944 0.03260224
## V3      -0.4036444 0.03849822        0.3904263        0.2053113 0.03176977
##    R1.upper.CL.0.95 R1.lower.CL.0.95
## V1        0.6258814        0.3695242
## V2        0.3454742        0.1923057
## V3        0.3379838        0.1879937

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 showing the estimates using the example data, along with confidence bands (CB), and the true treatment efficacy (TE) curve.

Plot showing the estimates using the example data, along with confidence bands (CB), and the true treatment efficacy (TE) curve.

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.

Plot illustrating ways that different risk contrast functions can be plotted.

Plot illustrating ways that different risk contrast functions can be plotted.

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.

##          S.1         Y        R0        R1 Y.boot.se Y.lower.CL.2.5
## V1 -2.328509 -1.770899 0.2983546 0.8267105 1.1943792      -4.768551
## V2 -2.275699 -1.743722 0.2980453 0.8177536 1.1622104      -4.671015
## V3 -1.694556 -1.360959 0.2946547 0.6956675 0.8334835      -3.456249
##    Y.upper.CL.97.5 R0.boot.se R0.lower.CL.2.5 R0.upper.CL.97.5 R1.boot.se
## V1      -0.6276106 0.09125321       0.1460172        0.4890998 0.06786962
## V2      -0.6184582 0.08994238       0.1475266        0.4856823 0.06911306
## V3      -0.4524787 0.07557692       0.1648504        0.4513863 0.07721039
##    R1.lower.CL.2.5 R1.upper.CL.97.5
## V1       0.6663453        0.9237321
## V2       0.6556765        0.9183559
## V3       0.5287710        0.8307616

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 (Elst et al. 2016).

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 (Wickham 2009). 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

Case-control design

## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1    S.0 cdfweights    BIP
## 1 0 0  NA     NA        0.2  0.335
## 2 0 0  NA     NA        0.2  1.454
## 3 0 1  NA -0.732        1.0 -0.724
## 4 0 0  NA     NA        0.2 -0.118
## 5 0 1  NA -0.185        1.0 -0.235
## 6 0 0  NA     NA        0.2 -0.778
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP 
##   weights  ->  weights 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_parametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(D = 10 )
## 
## Estimated parameters:
## (Intercept)         S.1           Z       S.1:Z 
##     -0.9189     -0.0284     -0.1867     -1.1684 
##  Convergence:  TRUE 
## 
##  No bootstraps present, see ?ps_bootstrap.

Survival outcome

## Warning in psdesign(fakedata, Z = Z, Y = Surv(time.obs, event.obs), S
## = S.obs, : tau missing in psdesign: assuming that the surrogate S was
## measured at time 0.
## Bootstrapping 20 replicates:
## ===========================================================================
## Augmented data frame:  800  obs. by  7  variables. 
##   Z          Y  S.1     S.0 cdfweights    BIP   CPV
## 1 0 0.3301972+ 1.49  0.3527          1  0.335 1.485
## 2 0  0.1195136   NA  1.4669          1  1.454 2.638
## 3 0  0.2631222   NA -0.7319          1 -0.724    NA
## 4 0  0.1373458   NA -0.0183          1 -0.118 0.942
## 5 0  0.8543703   NA -0.1847          1 -0.235    NA
## 6 0  0.2200481   NA -0.6631          1 -0.778 0.116
## 
## Empirical TE:  -0.296 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Surv(time.obs, event.obs) 
##   S  ->  S.obs 
##   BIP  ->  BIP 
##   CPV  ->  CPV 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1 )
## 
## Risk models: 
##   risk_exponential(D = 10 )
## 
## Estimated parameters:
## (Intercept)         S.1           Z       S.1:Z 
##     -0.7113     -0.0569      0.0410     -1.2249 
##  Convergence:  TRUE 
## 
## Bootstrap replicates:
##             Estimate boot.se lower.CL.2.5. upper.CL.97.5.  p.value
## (Intercept)  -0.7113  0.0734        -0.833         -0.585 3.38e-22
## S.1          -0.0569  0.0645        -0.159          0.052 3.77e-01
## Z             0.0410  0.0890        -0.112          0.186 6.45e-01
## S.1:Z        -1.2249  0.0704        -1.364         -1.117 1.01e-67
## 
##   Out of 20 bootstraps,  20 converged ( 100 %)
## 
##   Test for wide effect modification on 1 degree of freedom. 2-sided p value  < .0001
## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y,
## psdesign$estimates$par, : No time given for time to event outcome, using
## restricted mean survival: 0.4
## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

## Warning in riskcalc(psdesign$risk.function, psdesign$augdata$Y, thispar, :
## No time given for time to event outcome, using restricted mean survival:
## 0.4

Continuous outcome

## Bootstrapping 20 replicates:
## ===========================================================================
## Augmented data frame:  800  obs. by  7  variables. 
##   Z      Y S.1     S.0 cdfweights    BIP   CPV
## 1 0 -1.078  NA  0.3527          1  0.335 1.485
## 2 0 -2.044  NA  1.4669          1  1.454 2.638
## 3 0 -1.298  NA -0.7319          1 -0.724    NA
## 4 0 -1.915  NA -0.0183          1 -0.118 0.942
## 5 0 -0.146  NA -0.1847          1 -0.235    NA
## 6 0 -1.469  NA -0.6631          1 -0.778 0.116
## 
## Empirical TE:  -0.688 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.cont 
##   S  ->  S.obs 
##   BIP  ->  BIP 
##   CPV  ->  CPV 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_semiparametric(formula.location = S.1 ~ BIP, formula.scale = S.1 ~ 1 )
## 
## Risk models: 
##   risk_continuous(D = 10 )
## 
## Estimated parameters:
##       sigma (Intercept)         S.1           Z       S.1:Z 
##      0.0430     -1.4116     -0.0536     -0.1005     -0.8851 
##  Convergence:  TRUE 
## 
## Bootstrap replicates:
##             Estimate boot.se lower.CL.2.5. upper.CL.97.5.  p.value
## sigma         0.0430  0.0266      -0.00735         0.0816 1.06e-01
## (Intercept)  -1.4116  0.0687      -1.47648        -1.2561 7.86e-94
## S.1          -0.0536  0.0493      -0.15174         0.0189 2.77e-01
## Z            -0.1005  0.1007      -0.32506        -0.0130 3.18e-01
## S.1:Z        -0.8851  0.0670      -0.97179        -0.7716 7.37e-40
## 
##   Out of 20 bootstraps,  20 converged ( 100 %)
## 
##   Test for wide effect modification on 1 degree of freedom. 2-sided p value  < .0001

Categorical S

S.obs.cat and BIP.cat are factors:

S.obs.cat/BIP.cat (-Inf,-0.678] (-0.678,0.0574] (0.0574,0.766] (0.766, Inf]
(-Inf,-0.198] 135 65 0 0
(-0.198,0.503] 64 63 73 0
(0.503,1.36] 1 72 72 55
(1.36, Inf] 0 0 55 145 
## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y  S.1            S.0 cdfweights             BIP
## 1 0 0 <NA> (-0.198,0.503]          1  (0.0574,0.766]
## 2 0 0 <NA>    (1.36, Inf]          1    (0.766, Inf]
## 3 0 1 <NA>  (-Inf,-0.198]          1   (-Inf,-0.678]
## 4 0 0 <NA> (-0.198,0.503]          1 (-0.678,0.0574]
## 5 0 1 <NA> (-0.198,0.503]          1 (-0.678,0.0574]
## 6 0 0 <NA>  (-Inf,-0.198]          1   (-Inf,-0.678]
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs.cat 
##   BIP  ->  BIP.cat 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_nonparametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(model = Y ~ S.1 * Z, D = 10, risk = risk.probit )
## 
## Estimated parameters:
##         (Intercept)   S.1(-0.198,0.503]     S.1(0.503,1.36] 
##            -0.21777            -0.68989            -0.61467 
##      S.1(1.36, Inf]                   Z S.1(-0.198,0.503]:Z 
##            -0.31588             0.00732             0.03542 
##   S.1(0.503,1.36]:Z    S.1(1.36, Inf]:Z 
##            -0.37651            -1.35797 
##  Convergence:  TRUE 
## 
##  No bootstraps present, see ?ps_bootstrap.

Pseudo-score

Categorical W allows for estimation of the model using the pseudo-score method for binary outcomes. \(S\) may be continuous or categorical:

## Bootstrapping 20 replicates:
## ===========================================================================
## Augmented data frame:  800  obs. by  6  variables. 
##   Z Y S.1     S.0 cdfweights             BIP
## 1 0 0  NA  0.3527          1  (0.0574,0.766]
## 2 0 0  NA  1.4669          1    (0.766, Inf]
## 3 0 1  NA -0.7319          1   (-Inf,-0.678]
## 4 0 0  NA -0.0183          1 (-0.678,0.0574]
## 5 0 1  NA -0.1847          1 (-0.678,0.0574]
## 6 0 0  NA -0.6631          1   (-Inf,-0.678]
## 
## Empirical TE:  0.526 
## 
## Mapped variables: 
##   Z  ->  Z 
##   Y  ->  Y.obs 
##   S  ->  S.obs 
##   BIP  ->  BIP.cat 
## 
## Integration models: 
##   integration model for  S.1 :
##       integrate_nonparametric(formula = S.1 ~ BIP )
## 
## Risk models: 
##   risk_binary(model = Y ~ S.1 * Z, D = 10, risk = risk.logit )
## 
## Estimated parameters:
## (Intercept)         S.1           Z       S.1:Z 
##     -0.9341     -0.0143     -0.2058     -1.1462 
##  Convergence:  TRUE 
## 
## Bootstrap replicates:
##             Estimate boot.se lower.CL.2.5. upper.CL.97.5.  p.value
## (Intercept)  -0.9341   0.142        -1.070        -0.6390 4.58e-11
## S.1          -0.0143   0.138        -0.258         0.1657 9.17e-01
## Z            -0.2058   0.224        -0.733        -0.0148 3.57e-01
## S.1:Z        -1.1462   0.296        -1.710        -0.7311 1.10e-04
## 
##   Out of 20 bootstraps,  20 converged ( 100 %)
## 
##   Test for wide effect modification on 1 degree of freedom. 2-sided p value  = 1e-04 
## 
## Treatment Efficacy: 
## empirical  marginal     model 
##     0.526     0.526     0.532 
##  Model-based average TE is 1.1 % different from the empirical and 1.1 % different from the marginal.

Bug reports

References

Elst, Wim Van der, Paul Meyvisch, Ariel Alonso, Hannah M. Ensor, and Christopher J. Weir & Geert Molenberghs. 2016. Surrogate: Evaluation of Surrogate Endpoints in Clinical Trials. https://CRAN.R-project.org/package=Surrogate.

Follmann, D. 2006. “Augmented Designs to Assess Immune Response in Vaccine Trials.” Biometrics 62 (4):1161–9.

Frangakis, CE, and DB Rubin. 2002. “Principal Stratification in Causal Inference.” Biometrics 58 (1):21–29.

Gabriel, Erin E, and Dean Follmann. 2015. “Augmented Trial Designs for Evaluation of Principal Surrogates.” Biostatistics 0 (0):1–25.

Gabriel, Erin E., and Peter B. Gilbert. 2014. “Evaluating Principal Surrogate Endpoints with Time-to-Event Data Accounting for Time-Varying Treatment Efficacy.” Biostatistics 15 (2):251–65.

Gabriel, Erin E., Michael C. Sachs, and Peter B. Gilbert. 2015. “Comparing and Combining Biomarkers as Principle Surrogates for Time-to-Event Clinical Endpoints.” Statistics in Medicine 34 (3):381–95. https://doi.org/10.1002/sim.6349.

Gilbert, PB, and MG Hudgens. 2008. “Evaluating Candidate Principal Surrogate Endpoints.” Biometrics 64 (4):1146–54.

Huang, Y, and PB Gilbert. 2011. “Comparing Biomarkers as Principal Surrogate Endpoints.” Biometrics.

Huang, Ying, Peter B Gilbert, and Julian Wolfson. 2013. “Design and Estimation for Evaluating Principal Surrogate Markers in Vaccine Trials.” Biometrics 69 (2):301–9.

Pepe, MS, and TR Fleming. 1991. “A Nonparametric Method for Dealing with Mismeasured Covariate Data.” Journal of the American Statistical Association 86 (413):108–13.

Sachs, Michael C., and Erin E. Gabriel. 2016. Pseval: Methods for Evaluating Principal Surrogates of Treatment Response.

Wickham, Hadley. 2009. Ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York.

Wolfson, J. 2009. “Statistical Methods for Identifying Surrogate Endpoints in Vaccine Trials.” Doctor of Philosophy Dissertation, Chair: Gilbert, Peter: University of Washington; Department of Biostatistics.

Wolfson, J, and PB Gilbert. 2010. “Statistical Identifiability and the Surrogate Endpoint Problem, with Application to Vaccine Trials.” Biometrics 66 (4):1153–61.