Calculate E-P-values based on LR statistic.

Description

Calculates all possible values of the E-P-value for testing p1-p0 greater than a provided null value psi.

Usage

ESTEP.rd(n0, n1, psi = 0, J = NULL, sided = 1, dec.places = 10, prin = FALSE)

Arguments

Details

This function can take a long time for larger sample sizes. The computation time is of order (n0*n1)^2.

Value

A list with elements

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Exact Power of Test for Selected Sample Sizes.

Description

For known values of the sizes n0, this function computes the exact probability of rejecting the null as a function of baseline probability.

Usage

POWER(
  n0,
  n1,
  alpha = 0.05,
  delta = 0,
  psi = 0,
  type = "lr",
  sided = 1,
  p0 = NULL,
  obj = NULL
)

Arguments

Details

p0 values must be between max(0,-delta) and min(1,1-delta)

Value

list with element x (containing values of baseline probability) and element y (containing corresponding exact powers)

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Examples

oldpar <- graphics::par()
# Typical usage
#       POWER(n0=65,n1=82,psi=0,type="lr") # Exact size of approximate lr test
#       POWER(n0=65,n1=82,psi=0,type="elr",delta=.2) # Exact power of quasi exact test
# To make examples run faster, the package includes objects that contain
# all possible values of various tests when n0=65, n1=82.
load(system.file('files', "lr.stats.Rdata", package = 'exact.n'))
# All possible values of LR statistic p-values for testing p1-p0>0
load(system.file('files', "elr.stats.Rdata", package = 'exact.n'))
# All possible values of ELR statistic p-values for testing p1-p0>0
load(system.file('files', "elr10.stats.Rdata", package = 'exact.n'))
# Object contains all exact p-values for testing if p1-p0>0.1
# All possible values of ELR statistic p-values for testing p1-p0>0.1
#
graphics::par(mfrow=c(1,2))
# When delta=0 this gives type 1 error. The first plot is for the approximate
# lr based p-value, the second is for the quasi-exact e-p-value (alpha=0.05)
plot(POWER(n0=65,n1=82,alpha=0.05,psi=0,delta=0),type="l",
     xlab=expression("p"[0]),ylab="exact size")
abline(h=.05,lty=2)
plot(POWER(obj=elr.stats,alpha=0.05,delta=0),type="l",
     xlab=expression("p"[0]),ylab="exact size")
abline(h=.05,lty=2)
#
# For these sample sizes, power curve is calculated below for
# values of delta=0.1, 0.12, 0.14, 0.16, 0.18, 0.20. Power
# is poor for detecting a difference of 0.1 (see red).
plot(POWER(obj=lr.stats,alpha=0.05,delta=0.1),type="l",
     xlab=expression("p"[0]),ylab="exact power")
TITLE=expression('Exact power of LR test of p'[1]*'-p'[0]*'>0.')
title(main=TITLE,cex.main=0.8)
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.12))
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.14))
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.16))
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.18))
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.20))
lines(POWER(obj=lr.stats,alpha=0.05,delta=0.10),col="red")
#
# The results below are for testing p1-p0>0.1.
plot(c(0,.9),c(0,1),type="n",
     xlab=expression("p"[0]),ylab="Pr(reject null)")
lines(POWER(obj=elr10.stats,alpha=0.05,psi=0.1,delta=0.1)) # Note delta=psi
abline(h=0.05,lty=2)
lines(POWER(obj=elr10.stats,alpha=0.05,delta=0.25),col="blue")
TITLE=expression('Exact size and power of test of p'[1]*'-p'[0]*'>0.1.')
title(main=TITLE,cex.main=0.8)
legend(.4,.4,lty=c(1,1),col=c("black","blue"),box.col="white",
    legend=c("size: p1-p0=0.1","power: p1-p0=0.25"),cex=.7)
# When using the package the above plots would be generated by
# lines(POWER(n0=65,n1=82,alpha=0.05,psi=0.1,delta=0.10,type="elr"))
# lines(POWER(n0=65,n1=82,alpha=0.05,psi=0.1,delta=0.25,type="elr"))
suppressWarnings(graphics::par(oldpar))

Download a target power library

Description

Function downloads one of 85 power libraries from chrislloyd.com.au. The libraries are all four column matrices with roughly 20 million rows and will be around 1.4Gb within R. Download should take roughly a minute. The object will have a name of the form LIB.alpha.delta.Rdata.

Usage

fetch.data(alpha, delta, prin = FALSE)

Arguments

Value

No return value. A library object will appear in the global environment.

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. doi:10.13140/RG.2.2.11828.94085

Examples

#'
## Not run: 
fetch.data(alpha=0.05,delta=0.10)
# Object LIB.a050.d10 will appear with 83,289,960 elements

## End(Not run)

Approximate and exact tests for single data set

Description

For a single provided data sets (y0, n0, y1, n1) calculate approximate and quasi-exact test statistics of the null value p1-p0=psi.

Usage

inference(y0, n0, y1, n1, psi = 0, sided = 1, dec.places = 4)

Arguments

Value

List with elements

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Examples

y0=25
y1=41
n0=65
n1=82
# Non-inferiority test of p1-p0>-0.1. Evidence is strong.
inference(y0,n0,y1,n1,psi=-0.1)

Likelihood ratio statistics for one-sided tests of risk difference.

Description

Calculates all possible values of the (signed) LR statistic for testing p1-p0 greater than a provided null value psi.

Usage

lr.rd(
  n0,
  n1,
  Y0 = NULL,
  Y1 = NULL,
  psi = 0,
  sided = 1,
  mod = 1e-07,
  dec.places = 10
)

Arguments

Details

If Y0,Y1 is not supplied then all possible values are output. If specific values for Y0, Y1 are supplied then only these outcomes of the SRLR are calculated.

Value

A list with elements

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Provide sample size solutions for target size and power.

Description

Function gives smallest values for n1 as function of n0 that achieve target size and power.

Usage

main.function(
  alpha,
  delta,
  beta = 0.75,
  p0 = 0.5,
  type = 2,
  plt = FALSE,
  out = (-1),
  b.lim = 5,
  prin = TRUE
)

Arguments

Details

If out > 0 all solutions (including n1=Inf) are returned. If out=0, infinite values are suppressed. If out < 0, only output satisfying the balance criterion are output.

Value

list with elements n0 and n1

Note

The appropriate data file needs to have been downloaded corresponding to the desired value of alpha and delta. This can be done with the fetch.data() function.

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Examples

# We are interested in designs with power at least 0.75 when exact size
# 0.025 and delta=0.20. Therefore, you would need to have downloaded
# LIB.a025.d20 using fetch(0.015,0.20). The example below instead uses
# the toy data that comes with the package. The baseline probability is
# assumed to be between 0.3 and 0.5.
rdata_file = system.file('files', 'LIB.a025.d20.Rdata', package = 'exact.n')
load(rdata_file)
#' main.function(.025,0.20,p0=c(0.3,0.5),beta=0.75,plt=TRUE)
# The value of the function is the minimum value of n1 for a range
# of values of n0. The sample size ratio is limited to 5 by default.

Find smallest value of n1 that achieves target power

Description

Function calculates minimum value of n1 that achieves power beta. If there is no solution less than 500, it models observed powers as a function of n1 and then extrapolates. It returns an infinite value if the power is unattainable.

Usage

n1.get(data, n0, beta, delta, alpha, type = 1, plt = FALSE)

Arguments

Details

This function is called by n1.get.vector and will likely never be run by the user.

The data matrix will be a subset of one of the 85 main databases. Supplying alpha and delta loads the appropriate database and selecting a value of p0 further subsets this data base. The resulting matrix will have 4 columns and 481^2 rows corresponding to all values of n0 and n1 from 20 to 500 inclusive and is suitable for input into n1.get.

If type=1, the smallest value N1 of n1 so that power > beta is returned. If type=2, the smallest value N1 of n1 so that power > beta for all n1>=N1 is returned.

Value

a single scalar value of n1. An integer indicates a solution was found in the database. A non-integer indicates an extrapolated solution. An Inf value indicates no extrapolated solution was found.

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Examples

# Load toy version of power library for alpha=0.025, delta=0.20.
# Alternatively, load the full library using fetch.data(alpha=0.025,delta=0.20)
rdata_file = system.file('files', 'LIB.a025.d20.Rdata', package = 'exact.n')
load(rdata_file)
data=LIB.a025.d20[LIB.a025.d20[,2]==0.5,] # select subset with p0=.5
# For given value of n0, what minimum value of n1 ensures power at least 0.7?
n1.get(data, n0=70, beta=.7, delta=.2, alpha=0.025,
       type = 1, plt = TRUE) # Explicit solution 63 found in data base
n1.get(data, n0=50, beta=.7, delta=.2, alpha=0.025,
       type = 1, plt = TRUE) # Approximate solution 131 extrapolated from toy data base
# You can check the accuracy of this extrapolated result:
# POWER(n0=50,n1=131,alpha=0.025,delta=0.2,p0=0.5,type="elr")
# The minimum power at p0=0.5 is 0.699, slightly less than 0.7.
# With the full library n1.get returns the correct answer of n1=136.
n1.get(data, n0=30, beta=.7, delta=.2, alpha=0.025,
       type = 1, plt = TRUE) # Extrapolated solution is infinite

Find minimal n1 achieving target power for range of values of p0

Description

This function calls n1.get.vector, runs if for all values of p0 within the supplied range and then takes the worst (i.e. largest) solution for n1

Usage

n1.get.solution(data, beta, p0, delta, alpha, type = 1)

Arguments

Value

vector of solutions for n1 with name vector equal to range of n0 values

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Examples

# Load toy version of power library for alpha=0.025, delta=0.20.
rdata_file = system.file('files', 'LIB.a025.d20.Rdata', package = 'exact.n')
load(rdata_file)
# n0 solutions when p0=0.5
n1.get.solution(LIB.a025.d20,beta=.7,p0=0.5,delta=0.2,alpha=0.025,type=1)
# n0 solutions for p0 between 0.4 ad 0.5
n1.get.solution(LIB.a025.d20,beta=.7,p0=c(0.4,0.5),delta=0.2,alpha=0.025,type=1)

Find minimal n1 achieving target power for all values of n0

Description

For values of n0 covered in the matrix data (typically from 20 to 500) the function calls n1.get and finds the minimal value of n1 achieving the target power.

Usage

n1.get.vector(data, beta, p0, delta, alpha, type = 1)

Arguments

Details

This function is called by n1.get.solution and will likely never be run by the user.

The data matrix will be one of the 85 main databases.

If type=1, the smallest value N1 of n1 so that power > beta is returned. If type=2, the smallest value N1 of n1 so that power > beta for all n1>=N1 is returned.

Value

a list with element x (giving range of values of n0) and y (giving minimal solutions for n1 of power > beta). integer indicates

Author(s)

Chris J. Lloyd

References

C.J. Lloyd (2022) Exact samples sizes for clinical trials subject to size and power constraints. Preprint. doi:10.13140/RG.2.2.11828.94085

Image plot of power

Description

Creates image plot of exact power for range of values of n0 and n1. Optionally, the image plot will show where power exceeds a provided power target.

Usage

power.image(data, p = 0.2, binary = TRUE, beta = 0.75)

Arguments

Details

data will be one of the 85 saved objects corresponding to a selected value of alpha and delta.

Value

No return value and if the 'binary' parameter is TRUE then an image will be displayed

Author(s)

Chris J. Lloyd

Examples

oldpar <- graphics::par()
# Load toy version of power library for alpha=0.025, delta=0.20.
rdata_file = system.file('files', 'LIB.a025.d20.Rdata', package = 'exact.n')
load(rdata_file)
graphics::par(mfrow=c(1,2))
power.image(LIB.a025.d20,p=.5,binary=FALSE)
power.image(LIB.a025.d20,p=.2,beta=.7,binary=TRUE)
suppressWarnings(graphics::par(oldpar))