Type: Package
Title: Efficient Testing Using Surrogate Information
Version: 1.0
Date: 2025-11-03
Description: Provides functions for treatment effect estimation, hypothesis testing, and future study design for settings where the surrogate is used in place of the primary outcome for individuals for whom the surrogate is valid, and the primary outcome is purposefully measured in the remaining patients. More details are available in: Knowlton, R., Parast, L. (2024) “Efficient Testing Using Surrogate Information," Biometrical Journal, 67(6): e70086, <doi:10.1002/bimj.70086>. A tutorial for this package can be found at https://www.laylaparast.com/etsi.
License: GPL-2 | GPL-3 [expanded from: GPL]
Imports: hetsurr, stats
NeedsCompilation: no
Packaged: 2025-11-03 17:15:47 UTC; parastlm
Author: Rebecca Knowlton [aut], Layla Parast [aut, cre]
Maintainer: Layla Parast <parast@austin.utexas.edu>
Repository: CRAN
Date/Publication: 2025-11-06 10:50:02 UTC

Estimates the standard error of the pooled treatment effect quantity.

Description

Estimates the standard error of the pooled treatment effect quantity.

Usage

calculate.se(y1.weak, y0.weak, y1.strong, y0.strong)

Arguments

y1.weak

y1.weak, the primary outcome in the treatment group with weak surrogacy

y0.weak

y0.weak, the primary outcome in the control group with weak surrogacy

y1.strong

y1.strong, the predicted primary outcome given the surrogate in the treatment group with strong surrogacy

y0.strong

y0.strong, the predicted primary outcome given the surrogate in the control group with strong surrogacy

Value

Returns the estimated standard error.

Calculates whether each individual has a strong surrogate, based on PTE results from Study A and a desired threshold.

Description

Calculates whether each individual has a strong surrogate, based on PTE results from Study A and a desired threshold.

Usage

check.strong.surr(df, k, PTE.results)

Arguments

df

The dataframe to determine strong surrogacy.

k

k, the threshold at which PTE > k qualifies as a strong surrogate

PTE.results

The PTE results (from the hetsurr::hetsurr.fun function) that should be used to determine strong surrogacy.

Value

Returns a vector the same length as df, indicating for each row of df whether the surrogate is strong (1) or weak (0).

Calculates the estimated power for a future Study B or the required sample size to achieve a desired level of power.

Description

Function to help design a future Study B given data from Study A. Depending on the inputs, either calculates the estimated power in Study B, or calculates the required sample size in each treatment groupto achieve a desired level of power in Study B.

Usage

etsi.design(Study.A, n.b0 = NULL, n.b1 = NULL, psi = NULL, w.range = NULL, 
            kappa = NULL, desired.power = NULL, iterations = 100)

Arguments

Study.A

Study.A, a dataframe representing Study A containing the required columns A (treatment assignment), Y (primary outcome), S (surrogate outcome), and W (baseline covariate of interest). Optionally contains a column delta, which is an indicator for strong surrogacy.

n.b0

n.b0, sample size in Study B control group

n.b1

n.b1, sample size in Study B treatment group

psi

psi, the overall treatment effect you want to detect in Study B

w.range

w.range, a vector containing the lower and upper limits of the covariate W you plan to have in Study B

kappa

kappa, the threshold to determine strong surrogacy when the delta columns is not provided in Study.A. Surrogacy is considered sufficiently strong when the estimated PTE with respect to W is greater than kappa.

desired.power

The desired power in Study B, when you want to calculate required sample size

iterations

The number of iterations used for generalized cross-validation.

Value

A list is returned:

power

The estimated power in Study B; only given if desired.power = NULL.

sample.size

The required sample size in each treatment group in Study B; only given if desired.power is not NULL.

Author(s)

Rebecca Knowlton

References

Knowlton, R., Parast, L. (2025) "Efficient Testing Using Surrogate Information." Biometrical Journal, 67(6): e70086.

Examples

  data(exampledataA)
  data(exampledataB)
  names(exampledataA)
  names(exampledataB)
  etsi.design(Study.A = exampledataA,
            n.b0 = 400, 
            n.b1 = 500, 
            iterations = 10)

Estimates the pooled treatment effect quantity, standard error, and corresponding p-value.

Description

Estimates the pooled treatment effect quantity in Study B, using the surrogate information learned from Study A. Provides the corresponding estimated standard error and p-value for testing the null hypothesis of a treatment effect equal to 0.

Usage

etsi.main(Study.A, Study.B, kappa = NULL)

Arguments

Study.A

Study.A, a dataframe representing Study A containing the required columns A (treatment assignment), Y (primary outcome), S (surrogate outcome), and W (baseline covariate of interest). Optionally contains a column delta, which is an indicator for strong surrogacy.

Study.B

Study.B, a dataframe representing Study B containing the required columns A (treatment assignment), Y (primary outcome), S (surrogate outcome), and W (baseline covariate of interest). Optionally contains a column delta, which is an indicator for strong surrogacy.

kappa

kappa, the threshold to determine strong surrogacy when the delta columns are not provided in Study.A and Study.B. Surrogacy is considered sufficiently strong when the estimated PTE with respect to W is greater than kappa.

Value

A list is returned:

delta.P

The pooled treatment effect quantity for Study B

se.delta.P

Standard error of delta.P

p.value

p-value for testing the null hypothesis that delta.P = 0

Author(s)

Rebecca Knowlton

References

Knowlton, R., Parast, L. (2025) "Efficient Testing Using Surrogate Information." Biometrical Journal, 67(6): e70086.

Examples

  data(exampledataA)
  data(exampledataB)
  names(exampledataA)
  names(exampledataB)
  etsi.main(Study.A = exampledataA,
            Study.B = exampledataB)

Example Data (Study A)

Description

Example Data (Study A)

Usage

data("exampledataA")

Format

A data frame with 1000 observations from a treatment group and 1100 observations from a control group:

A

the treatment assignment, where 1 indicates treatment and 0 indicates control

W

the baseline covariate of interest

S

the surrogate outcome

Y

the primary outcome

delta

the indicator for strong surrogacy, where 1 indicates strong and 0 indicates weak

Examples

data(exampledataA)
names(exampledataA)

Example Data (Study B)

Description

Example Data (Study B)

Usage

data("exampledataB")

Format

A data frame with 500 observations from a treatment group and 400 observations from a control group:

A

the treatment assignment, where 1 indicates treatment and 0 indicates control

W

the baseline covariate of interest

S

the surrogate outcome

Y

the primary outcome

delta

the indicator for strong surrogacy, where 1 indicates strong and 0 indicates weak

Examples

data(exampledataB)
names(exampledataB)

Function for extrapolating NA values from kernel smoothing

Description

Function for extrapolating NA values from kernel smoothing

Usage

extrapolate.na(y.strong, s.strong)

Arguments

y.strong

y.strong, the vector of predicted primary outcome values for s.strong

s.strong

s.strong, the vector of strong surrogate information

Value

Returns a vector y.strong where the NA values have been filled in with extrolated values based on s.strong

Calculates the conditional expectation of the primary outcome from the control group in Study A, given the surrogate outcome, using kernel smoothing.

Description

Calculates the conditional expectation of the primary outcome from the control group in Study A, given the surrogate outcome, using kernel smoothing.

Usage

get.mu.hat.0(s, A.s0, A.y0)

Arguments

s

s, the surrogate outcome

A.s0

A.s0, the vector of surrogate outcomes from the control group in Study A

A.y0

A.y0, the vector of primary outcomes from the control group in Study A

Value

Returns the estimated conditional expectation of the primary outcome