test.surrogate.extension: Tests whether the surrogate is valid, extended to the paired,...

In SurrogateRank: Rank-Based Test to Evaluate a Surrogate Marker

Tests whether the surrogate is valid, extended to the paired, two sided test setting

Description

Calculates the rank-based test statistic for Y and the rank-based test statistic for S and the difference, delta, along with corresponding standard error estimates, then tests whether the surrogate is valid. This extends the test.surrogate() function to the case where samples may be paired instead of independent, and where a two sided test is desired.

Usage

test.surrogate.extension(
  yone,
  yzero,
  sone,
  szero,
  alpha = 0.05,
  power.want.s = NULL,
  epsilon = NULL,
  u.y.hyp = NULL,
  alternative = "less",
  paired = FALSE
)

Arguments

yone	numeric vector of primary response values in the treated group.
yzero	numeric vector of primary response values in the untreated group.
sone	matrix or dataframe of surrogate candidates in the treated group with dimension n1 x p where n1 is the number of treated samples and p the number of candidates. Sample ordering must match exactly yone.
szero	matrix or dataframe of surrogate candidates in the untreated group with dimension n0 x p where n0 is the number of untreated samples and p the number of candidates. Sample ordering must match exactly yzero.
alpha	significance level for determining surrogate candidates. Default is 0.05.
power.want.s	numeric in (0,1) - power desired for a test of treatment effect based on the surrogate candidate. Either this or epsilon argument must be specified.
epsilon	numeric in (0,1) - non-inferiority margin for determining surrogate validity. Either this or power.want.s argument must be specified.
u.y.hyp	hypothesised value of the treatment effect on the primary response on the probability scale. If not given, it will be estimated based on the observations.
alternative	character giving the alternative hypothesis type. One of c("less","two.sided"), where "less" corresponds to a non-inferiority test and "two.sided" corresponds to a two one-sided test procedure. Default is "less".
paired	logical flag giving if the data is independent or paired. If FALSE (default), samples are assumed independent. If TRUE, samples are assumed to be from a paired design. The pairs are specified by matching the rows of yone and sone to the rows of yzero and szero.

Value

A list containing:

• u.y Estimated rank-based treatment effect on the outcome.

• u.s Estimated rank-based treatment effect on the surrogate.

• delta.estimate Estimated difference in treatment effects: u.y - u.s.

• sd.u.y Standard deviation of u.y.

• sd.u.s Standard deviation of u.s.

• sd.delta Standard deviation of delta.estimate.

• ci.delta One-sided confidence interval upper bound for delta.estimate.

• p.delta p-value for validity of trial-level surrogacy.

• epsilon.used Non-inferiority threshold used in the test.

• is.surrogate TRUE if the surrogate passes the test, else FALSE.

Author(s)

Arthur Hughes, Layla Parast

Examples

# Load data
data("example.data")
yone <- example.data$y1
yzero <- example.data$y0
sone <- example.data$s1
szero <- example.data$s0
test.surrogate.extension.result <- test.surrogate.extension(
  yone, yzero, sone, szero,
  power.want.s = 0.8, paired = TRUE, alternative = "two.sided"
)

SurrogateRank documentation built on June 8, 2025, 10:27 a.m.