rise.evaluate: Performs the evaluation stage of RISE: Two-Stage Rank-Based...

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

Performs the evaluation stage of RISE: Two-Stage Rank-Based Identification of High-Dimensional Surrogate Markers

Description

A set of high-dimensional surrogate candidates are evaluated jointly. Strength of surrogacy is assessed through a rank-based measure of the similarity in treatment effects on a candidate surrogate and the primary response.

Usage

rise.evaluate(
  yone,
  yzero,
  sone,
  szero,
  alpha = 0.05,
  power.want.s = NULL,
  epsilon = NULL,
  u.y.hyp = NULL,
  p.correction = "BH",
  n.cores = 1,
  alternative = "less",
  paired = FALSE,
  return.all.evaluate = TRUE,
  return.plot.evaluate = TRUE,
  evaluate.weights = TRUE,
  screening.weights = NULL,
  markers = NULL
)

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.
p.correction	character. Method for p-value adjustment (see p.adjust() function). Defaults to the Benjamini-Hochberg method ("BH").
n.cores	numeric giving the number of cores to commit to parallel computation in order to improve computational time through the pbmcapply() function. Defaults to 1.
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.
return.all.evaluate	logical flag. If TRUE (default), a dataframe will be returned giving the evaluation of each individual marker passed to the evaluation stage.
return.plot.evaluate	logical flag. If TRUE (default), a ggplot2 object will be returned allowing the user to visualise the association between the composite surrogate on the individual-scale.
evaluate.weights	logical flag. If TRUE (default), the composite surrogate is constructed with weights as the absolute value of the inverse of the delta values of each candidate, such that surrogates which are predicted to be stronger receive more weight.
screening.weights	dataframe with columns marker and weight giving the weight in for the evaluation. Typically this is taken directly from the screening stage as the output from the rise.screen() function. Must be given if evaluate.weights is TRUE.
markers	a vector of marker names (column names of szero and sone) to evaluate. If not given, will default to evaluating all markers in the dataframes.

Value

A list with:

• individual.metrics If return.all.evaluate = TRUE, a dataframe of evaluation results for each significant marker.

• gamma.s A list with elements gamma.s.one and gamma.s.zero, giving the combined surrogate marker in the treated and untreated groups, respectively.

• gamma.s.evaluate A dataframe giving the evaluation of gamma.s.

• gamma.s.plot A ggplot2 plot showing gamma.s against the primary response on the rank-scale.

Author(s)

Arthur Hughes

Examples

# Load high-dimensional example data
data("example.data.highdim")
yone <- example.data.highdim$y1
yzero <- example.data.highdim$y0
sone <- example.data.highdim$s1
szero <- example.data.highdim$s0

rise.evaluate.result <- rise.evaluate(yone, yzero, sone, szero, power.want.s = 0.8)

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