Type: Package
Title: Assessing Heterogeneity in the Utility of a Surrogate Marker
Version: 1.0
Date: 2021-11-10
Author: Layla Parast
Maintainer: Layla Parast <parast@austin.utexas.edu>
Description: Provides a function to assess and test for heterogeneity in the utility of a surrogate marker with respect to a baseline covariate. The main function can be used for either a continuous or discrete baseline covariate. More details will be available in the future in: Parast, L., Cai, T., Tian L (2021). "Testing for Heterogeneity in the Utility of a Surrogate Marker." Biometrics, In press.
License: GPL-2 | GPL-3 [expanded from: GPL]
Imports: stats, Rsurrogate, graphics
NeedsCompilation: no
Packaged: 2021-11-10 14:41:40 UTC; parast
Depends: R (≥ 3.5.0)
Repository: CRAN
Date/Publication: 2021-11-10 16:10:02 UTC

Estimates residual treatment effect when W is discrete.

Description

Estimates residual treatment effect when W is discrete.

Usage

delta.s.estimate.w(sone, szero, yone, yzero, wone, wzero, w.all, weight.perturb = NULL)

Arguments

sone

sone

szero

szero

yone

yone

yzero

yzero

wone

wone

wzero

wzero

w.all

w.all

weight.perturb

perturbation weights

Value

Returns a vector of length equal to the length of w.all with the estimated residual treatment effect for each w value

Example data

Description

Example data

Usage

data("example.data")

Format

A list with 6 elements representing 2000 observations from a treatment group and 1500 observations from a control group:

y1

the primary outcome in the treatment group

y0

the primary outcome in the control group

s1

the surrogate marker in the treatment group

s0

the surrogate marker in the control group

w1

the baseline covariate of interest in the treatment group

w0

the baseline covariate of interest in the control group

Examples

data(example.data)
names(example.data)

Assess and test for heterogeneity in the utility of a surrogate

Description

This function assesses and tests for heterogeneity in the utility of a surrogate with respect to a continuous or discrete baseline covariate. The method is nonparametric and focuses on estimation of the proportion of the treatment effect that is explained by the surrogate marker. Inference information is provided including a confidence band for the proportion and results from formal testing for heterogeneity. When the baseline covariate is continuous, two tests are performed - an omnibus test and a trend test; when the baseline covariate is discrete, only one test is performed - an omnibus test.

Usage

hetsurr.fun(y1, y0, s1, s0, w1, w0, wf.grd = NULL, h0 = NULL, h1 = NULL, h2 = NULL, 
h3 = NULL, h4 = NULL, var.want = FALSE, type = "cont", test.want = FALSE, c.adj = 1)

Arguments

y1

the primary outcome in the treatment group

y0

the primary outcome in the control group

s1

the surrogate marker in the treatment group

s0

the surrogate marker in the control group

w1

the baseline covariate of interest in the treatment group

w0

the baseline covariate of interest in the control group

wf.grd

the grid of the baseline covariate where estimates are wanted; if this is not specified, this will bet set equal to 50 equally spaced points between the 10th and 90th percentile of the union of w1 and w0 values (if continuous) or the set of unique categories (if discrete)

h0

bandwidth; if not specific, this is set to a value of appropriate order

h1

bandwidth; if not specific, this is set to a value of appropriate order

h2

bandwidth; if not specific, this is set to a value of appropriate order

h3

bandwidth; if not specific, this is set to a value of appropriate order

h4

bandwidth; if not specific, this is set to a value of appropriate order

var.want

TRUE or FALSE; indicates whether variance estimate are wanted, default is FALSE

type

"cont" or "discrete"; indicates the form of the baseline covariate w, default is "cont"

test.want

TRUE or FALSE; indicates whether testing results are wanted, default is FALSE

c.adj

a multiplicative adjustment for the bandwidth; default is 1

Details

This function calculates the treatment effect, Delta, the residual treatment effect, Delta_S, and the proportion of treatment effect explained R_S, as a function of the baseline covariate (if continuous) or stratified by category (if discrete). The estimation approach is nonparametric. Variance estimates can be requested including a confidence band for R_S. Results from formal testing for heterogeneity can also be requested. When the baseline covariate is continuous, two tests are performed - an omnibus test and a trend test; when the baseline covariate is discrete, only one test is performed - an omnibus test.

Value

w.values

values of the baseline covariate at which estimates are provided

delta.w

estimated treatment effect, Delta, at each w value

delta.w.s

estimated residual treatment effect, Delta_S, at each w value

R.w.s

estimated proportion of treatment effect explained, R_S, at each w value

se.delta.w

estimated standard error of Delta

se.delta.w.s

estimated standard error of Delta.S

se.R.w.s

estimated standard error of R.S

conf.delta.w.lower

lower bound of the confidence intervals for Delta

conf.delta.w.upper

upper bound of the confidence intervals for Delta

conf.delta.w.s.lower

lower bound of the confidence intervals for Delta.S

conf.delta.w.s.upper

upper bound of the confidence intervals for Delta.S

conf.R.w.s.lower

lower bound of the confidence intervals for R.S

conf.R.w.s.upper

upper bound of the confidence intervals for R.S

band.R.w.s.lower

lower bound of the confidence band for R.S

band.R.w.s.upper

upper bound of the confidence band for R.S

omnibus.test.statistic

test statistic from omnibus test; for a continuous baseline covariate only

omnibus.p.value

p-value from omnibus test, testing for evidence of heterogeneity; for a continuous baseline covariate only

trend.test.statistic

test statistic from the trend test; for a continuous baseline covariate only

trend.p.value

p-value from trend test, testing for evidence of heterogeneity; for a continuous baseline covariate only

test.statistic

p-value from the test testing for evidence of heterogeneity; for a discrete baseline covariate only

p.value

p-value from the test testing for evidence of heterogeneity; for a discrete baseline covariate only

Author(s)

Layla Parast

References

Parast, L., Cai, T., Tian L (2021). Testing for Heterogeneity in the Utility of a Surrogate Marker. Biometrics, In press.

Examples

	data(example.data)
	names(example.data)
	#computationally intensive
	
	het.ob = hetsurr.fun(y1=example.data$y1, y0=example.data$y0, s1=example.data$s1, 
	s0=example.data$s0, w1=example.data$w1, w0=example.data$w0, wf.grd = seq(0.25, 1.75, 
	length=50), var.want =FALSE, type = "cont")
	het.ob = hetsurr.fun(y1=example.data$y1, y0=example.data$y0, s1=example.data$s1, 
	s0=example.data$s0, w1=example.data$w1, w0=example.data$w0, wf.grd = seq(0.25, 1.75, 
	length=50), var.want =TRUE,  test.want = TRUE, type = "cont")
	
	#reducing dimension of example data to provide a computationally faster example
	het.ob = hetsurr.fun(y1=example.data$y1[1:500], y0=example.data$y0[1:500],
	s1=example.data$s1[1:500], s0=example.data$s0[1:500], w1=example.data$w1[1:500],
	w0=example.data$w0[1:500], wf.grd = seq(0.25, 1.75, length=5), var.want =FALSE, 
	type = "cont")

Constructs plots of the treatment effect, residual treatment effect, and proportion explained as a function of the continuous baseline covariate

Description

Constructs plots of the treatment effect, residual treatment effect, and proportion explained as a function of the continuous baseline covariate

Usage

hetsurr.plot(hetsurr.results, xlab.name = "Baseline Covariate", placement = "bottomleft")

Arguments

hetsurr.results

This is a list produced by the hetsurr.fun function.

xlab.name

This is the label for the x-axis; default is "Baseline Covariate".

placement

This is the placement for the legend; default is "bottomleft".

Value

Produces a plot with 3 panels.

Author(s)

Layla Parast

References

Parast, L., Cai, T., Tian L (2021). Testing for Heterogeneity in the Utility of a Surrogate Marker. Biometrics, In press.

Examples

	data(example.data)
	names(example.data)
	#computationally intensive
	
	het.ob = hetsurr.fun(y1=example.data$y1, y0=example.data$y0, s1=example.data$s1, 
	s0=example.data$s0, w1=example.data$w1, w0=example.data$w0, wf.grd = seq(0.25, 1.75, 
	length=50), var.want =TRUE,  test.want = TRUE, type = "cont")
	hetsurr.plot(het.ob)
	
	#reducing dimension of example data to provide a computationally faster example
	het.ob = hetsurr.fun(y1=example.data$y1[1:300], y0=example.data$y0[1:300],
	s1=example.data$s1[1:300], s0=example.data$s0[1:300], w1=example.data$w1[1:300],
	w0=example.data$w0[1:300], wf.grd = seq(0.25, 1.75, length=5), var.want =TRUE,
	test.want = TRUE, type = "cont")
	hetsurr.plot(het.ob)

Kernel function

Description

Kernel function

Usage

kf(x, h)

Arguments

x

x

h

bandwidth

Value

Returns value for the kernel at the given x

Estimates mu0(w)=E(Y0|W0=w)

Description

Estimates mu0(w)=E(Y0|W0=w)

Usage

mu0wy(w, hyw0,y0,w0)

Arguments

w

w

hyw0

bandwidth

y0

y0

w0

w0

Value

Returns mu0(w) estimate for given w

Estimates mu10(w)

Description

Estimates mu10(w) which is the integral of mu1(s, w) with respect to dF0(s|w)

Usage

mu10(s1,w1,y1,w0,s0,w, hy2w1, hy2s1, hsw1)

Arguments

s1

s1

w1

w1

y1

y1

w0

w0

s0

s0

w

w

hy2w1

bandwidth

hy2s1

bandwidth

hsw1

bandwidth

Value

Returns mu10(w) estimate for given w

Estimates mu1(s, w)=E(Y1|S1=s, W1=w)

Description

Estimates mu1(s, w)=E(Y1|S1=s, W1=w)

Usage

mu1swy(s1,w1,y1,s, w, hy2w1, hy2s1)

Arguments

s1

s1

w1

w1

y1

y1

s

s

w

w

hy2w1

bandwidth

hy2s1

bandwidth

Value

Returns mu1(s,w) estimate for given s and w

Estimates mu1(w)=E(Y1|W1=w)

Description

Estimates mu1(w)=E(Y1|W1=w)

Usage

mu1wy(w, hyw1,y1,w1)

Arguments

w

w

hyw1

bandwidth

y1

y1

w1

w1

Value

Returns mu1(w) estimate for given w