Modify a psdesign object by adding on new components.

Description

This operator allows you to add objects to a psdesign object, such as integration models and risk models

Usage

## S3 method for class 'ps'
p1 + p2

Arguments

Treatment efficacy contrast functions

Description

Treatment efficacy contrast functions

Usage

TE(R0, R1)

Arguments

Details

These functions take the risk in the two treatment arms, and computes a one-dimensional summary of those risks. Built-in choices are "TE" for treatment efficacy = 1 - risk_1(s)/risk_0(s), "RR" for relative risk = risk_0(s)/risk_1(s), "logRR" for log of the relative risk, and "RD" for the risk difference = risk_0(s) - risk_1(s).

Value

A vector the same length as R0 and R1.

Bootstrap resampling parameters

Description

Bootstrap resampling parameters

Usage

add_bootstrap(psdesign, bootstrap)

Arguments

Examples

## Not run: 
test <- psdesign(generate_example_data(n = 100), Z = Z, Y = Y.obs, S = S.obs, BIP = BIP)
est1 <- test + integrate_parametric(S.1 ~ BIP) + risk_binary() + ps_estimate(method = "BFGS")
est1 + ps_bootstrap(method = "BFGS", start = est1$estimates$par, n.boots = 50)

## End(Not run)

Estimate parameters

Description

Estimate parameters

Usage

add_estimate(psdesign, estimate)

Arguments

Examples

test <- psdesign(generate_example_data(n = 100), Z = Z, Y = Y.obs, S = S.obs, BIP = BIP)
test + integrate_parametric(S.1 ~ BIP) + risk_binary(D = 50) + ps_estimate(method = "BFGS")

Integration models

Description

Add integration model to a psdesign object

Usage

add_integration(psdesign, integration)

Arguments

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

Add risk model to a psdesign object

Description

Add risk model to a psdesign object

Usage

add_riskmodel(psdesign, riskmodel)

Arguments

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

Calculate the Standardized total gain

Description

Computes the standardized total gain for the risk difference. Optionally produces bootstrap standard errors and confidence intervals. The standardized total gain is the area between the risk difference curve and the horizontal line at the marginal risk difference. If the outcome is time to event then the STG is time-dependent, and a time point for evaluation is needed. If one is not provided then the restricted mean survival is estimated from the data and used.

Usage

calc_STG(
  psdesign,
  t,
  sig.level = 0.05,
  n.samps = 5000,
  bootstraps = TRUE,
  permute = TRUE,
  permute.times = 2000,
  progress.bar = TRUE
)

Arguments

Calculate the risk and functions of the risk

Description

Computes the treatment efficacy (TE) and other functions of the risk in each treatment arm over the range of surrogate values observed in the data. TE(s) is defined as 1 - risk(s, z = 1)/risk(s, z = 0), where z is the treatment indicator. If any other variables are present in the risk model, then the risk is computed at their median value.

Usage

calc_risk(
  psdesign,
  contrast = "TE",
  t,
  sig.level = 0.05,
  CI.type = "band",
  n.samps = 5000,
  bootstraps = TRUE,
  newdata = NULL
)

Arguments

Details

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

Value

A data frame containing columns for the S values, the computed contrast function at S, R0, and R1 at those S values, and optionally standard errors and confidence intervals computed using bootstrapped estimates.

Examples

## Not run: 
# same result passing function name or function
calc_risk(binary.boot, contrast = "TE", n.samps = 20)
calc_risk(binary.boot, contrast = function(R0, R1) 1 - R1/R0, n.samps = 20)

## End(Not run)

Compute the empirical Treatment Efficacy

Description

Compute the empirical Treatment Efficacy

Usage

empirical_TE(psdesign, t)

Arguments

Compute the empirical Treatment Efficacy

Description

Included for backwards compatibility

Usage

empirical_VE(psdesign, t)

Arguments

Expand augmented data using the integration function

Description

Expand augmented data using the integration function

Usage

expand_augdata(model, psdesign, D = 500)

Arguments

Generate sample data used for testing

Description

Generate sample data used for testing

Usage

generate_example_data(n)

Arguments

Bivariate normal integration models for the missing S(1)

Description

This model assumes that the pair [S(1), W] is bivariate normal, where W is the BIP. The means, standard deviations, and correlation are estimated or fixed before calling this function. Then the conditional normal formula is applied in order to get the distribution of S(1) | W. That distribution is used to integrate over the missing S(1) values. This method requires a BIP in the design.

Usage

integrate_bivnorm(x = "S.1", mu = c(0, 0), sd = c(1, 1), rho = 0.2)

Arguments

Nonparametric integration model for the missing S(1)

Description

Both S(1) and the BIP or set of BIPs must be categorical. This model integrates over the estimated distribution of S(1) | BIP

Usage

integrate_nonparametric(formula, ...)

Arguments

Parametric integration model for the missing S(1)

Description

Parametric integration model for the missing S(1)

Usage

integrate_parametric(formula, family = gaussian, ...)

Arguments

Semiparametric integration model using the location-scale model

Description

Semiparametric integration model using the location-scale model

Usage

integrate_semiparametric(formula.location, formula.scale, ...)

Arguments

Plot summary statistics for a psdesign object

Description

Plot the treatment efficacy or another contrast of risk versus S.1 for an estimated psdesign object

Usage

## S3 method for class 'psdesign'
plot(
  x,
  t,
  contrast = "TE",
  sig.level = 0.05,
  CI.type = "band",
  n.samps = 500,
  xlab = "S.1",
  ylab = contrast,
  col = 1,
  lty = 1,
  lwd = 1,
  ...
)

Arguments

Concisely print information about a psdesign object

Description

Concisely print information about a psdesign object

Usage

## S3 method for class 'psdesign'
print(x, digits = 3, sig.level = 0.05, ...)

Arguments

Estimate parameters from a specified model using bootstrap resampling and estimated maximum likelihood

Description

Estimate parameters from a specified model using bootstrap resampling and estimated maximum likelihood

Usage

ps_bootstrap(
  n.boots = 200,
  progress.bar = TRUE,
  start = NULL,
  method = "BFGS",
  control = list(),
  ...
)

Arguments

Estimate parameters from a specified model using estimated maximum likelihood

Description

Estimate parameters from a specified model using estimated maximum likelihood

Usage

ps_estimate(start = NULL, method = "BFGS", control = list(), ...)

Arguments

Specify a design for a principal surrogate evaluation

Description

Generate mappings that describe how variables in the data are mapped to components of the principal surrogate analysis. Other than data, this is a list of key-value pairs describing the common elements of a ps analysis. The required keys are Z, Y, and S. Optional keys are BIP, CPV, BSM, and weights. These elements are described in details below. Additional keys-value pairs can be included in .... This function generates an augmented dataset and additional information for subsequent steps in the analysis. In the subsequent steps, refer to the variables by the keys. See add_integration and add_riskmodel for information on how to proceed in the analysis.

Usage

psdesign(
  data,
  Z,
  Y,
  S,
  BIP = NULL,
  CPV = NULL,
  BSM = NULL,
  weights = NULL,
  tau,
  ...
)

Arguments

Estimate parameters from a specified model using pseudo-score

Description

Estimate parameters from a specified model using pseudo-score

Usage

pseudo_score(psdesign, start = NULL, epsilon = 1e-05, maxit = 50)

Arguments

Logit link function

Description

Logit link function

Usage

risk.logit(x)

Arguments

Value

A vector of probabilities

Probit link function

Description

Probit link function

Usage

risk.probit(x)

Arguments

Value

A vector of probabilities

Risk model for binary outcome

Description

Risk model for binary outcome

Usage

risk_binary(model = Y ~ S.1 * Z, D = 5000, risk = risk.logit)

Arguments

Risk model for continuous outcome

Description

This model assumes that the outcome Y is normally distributed conditional on S.1 and Z, with mean determined by the model formula. It also assumes that larger values of Y are more indicative of poor outcomes, e.g., blood pressure.

Usage

risk_continuous(model = Y ~ S.1 * Z, D = 5000)

Arguments

Exponential risk model for time to event outcome

Description

Exponential risk model for time to event outcome

Usage

risk_exponential(model = Y ~ S.1 * Z, D = 5000)

Arguments

Poisson risk model for count outcomes

Description

Poisson risk model for count outcomes

Usage

risk_poisson(model = Y ~ S.1 * Z, D = 5000)

Arguments

Weibull risk model for time to event outcome

Description

Weibull risk model for time to event outcome

Usage

risk_weibull(model = Y ~ S.1 * Z, D = 5000)

Arguments

Calculate risks with handlers for survival data

Description

Calculate risks with handlers for survival data

Usage

riskcalc(risk.function, Y, par, t, dat0, dat1)

Arguments

Fit the semi-parametric location-scale model

Description

This estimates the location-scale model as described in Heagerty and Pepe (1999) using the Newton-Raphson method. The location and scale formulas must have the same outcome, but they may have different predictors.

Usage

sp_locscale(
  formula.location,
  formula.scale,
  data,
  weights,
  tol = 1e-06,
  maxit = 100
)

Arguments

Value

A list containing the parameter estimates, the convergence indicator, and residuals

Compute the standardized total gain

Description

Compute the standardized total gain

Usage

stg(R1, R0, stand = TRUE)

Arguments

Summarize bootstrap samples

Description

Summarize bootstrap samples

Usage

summarize_bs(bootdf, estdf = NULL, sig.level = 0.05, CI.type = "band")

Arguments

Summary method for psdesign objects

Description

Summary method for psdesign objects

Usage

## S3 method for class 'psdesign'
summary(object, digits = 3, sig.level = 0.05, ...)

Arguments

Value

Invisibly returns the printed table, along with the three estimates of vaccine efficacy. The empirical TE is 1 minus the relative risk comparing the treatment arm to the control arm. The risk is estimated as the proportion in the binary outcome case, or with the Kaplan-Meier estimate at the restricted mean survival in the time-to-event case. The marginal TE estimate is the TE estimate under the specified parametric risk model, ignoring the effect of S.1. The model based average TE is the TE estimate from the specified risk model, averaged over the distribution of S.1. The point of displaying these three is to assess the validity of the parametric model, and to assess the validity of the model estimation. Wild differences among these estimates may indicate problems with the model or convergence.

Check that a variable is suitable for using as binary treatment indicator

Description

Checks for two classes and gives a warning message indicating which level is assumed to be 0/1

Usage

verify_trt(D)

Arguments

Test for wide effect modification

Description

This runs a multivariate Wald test on the interaction terms of the model, using the bootstrap covariance

Usage

wem_test(x)

Arguments