nicqTest: Non-inferiority control quantile test
In nivm: Noninferiority Tests with Variable Margins

Description Usage Arguments Details Value warning Author(s) References Examples

Tests for a difference in proportion of failures between test and control by the time the qth quantile of the contol group has failed. Uses a variable margin function, and the time of the qth quantile of the control group is unknown.

If the cumulative distributions for the two groups are F1 (control) and F2 (test), then we are interested in the difference: delta=F2(t0)-F1(t0), where F1(t0)=q. Note F1,F2 are unknown and non-parametric, and t0 is unknown. In this case, using a constant delta does not give practical non-inferiority margins, therefore we use a variable margin function, so that we test (when alternative='less') H0: F2(t) >= g(F1(t)) versus H1: F2(t) < g(F1(t)) for all t.

The test also works for other types of continuous responses besides time to failure (see details), but the help description uses time to failure for brevity.

nicqTest(x,delta0,q,g=nimDiffOR,yc=NULL,nc=NULL,nt=NULL,
    ic="prop",
    z=NULL,status=NULL,ties=c("cons","approx"),
    alternative=c("less","greater"),
    conf.level=0.95,
    conf.int=TRUE,
    conf.sided=c("two.sided","one.sided"), 
    gname=NULL,
    control=nicqControl())

`x`	either a vector of failure times for the both groups (when z is given), a vector of failure times for the test group (when yc is given), or the number of failures in the test group that have occured by the ic^th failure in the control group (when ic is an integer, nc and nt are given). See details.
`delta0`	difference, F2(t0)-F1(t0), on the boundary between the null and alternative hypotheses, where t0 is defined so that F1(t0)=q.
`q`	probability associated with the quantile of interest in control group
`g`	non-inferiority margin function. Must have arguments `q` (representing the quantile of interest in the control group) and `delta` (representing the difference, F2(t0)-F1(t0), where F2 and F2 are the cumulative distributions of failures for the test (F2) and control (F1) at t, where F1(t)=q). Default values for `q` and `delta` are ignored. Default function is `nimDiffOR`.
`yc`	vector of failure times in the control group. If given, `x` is the vector of failure times in the test group.
`nc`	number of individuals in the control group. Not needed if `z` or `yc` is given.
`nt`	number of individuals in the test group. Not needed if `z` or `yc` is given.
`ic`	used to find i. The test is based on the number of failures in the test group that have occured by the ith failure in the control group. ic="prop" gives i=ceiling(q*nc), ic="maxpower" gives the i value that maximizes the power given F1=F2 and g, and ic=a postive integer gives i=ic (with ic between 1 and nc inclusive).
`z`	a vector of group indicators, with either 1 (for control) or 2 (for test). If given, x is a vector of all failures in both groups.
`status`	a vector denoting right censoring (0) or not (1). Not needed if there is no censoring. Only used when `z` is given. If any censoring occurs at or before the ith failure (see ic argument) in the control group, then the test is undefined.
`ties`	how should ties be handled, "cons" use a conservative adjustment for ties, "approx" use an approximate adjustment. See details.
`alternative`	direction of alternative hypothesis.
`conf.level`	confidence level
`conf.int`	logical, do confidence intervals
`conf.sided`	character, either 'one.sided' or 'two.sided' (see warning)
`gname`	name for g function, if NULL uses name of inputed g function
`control`	a list of arguments for numeric calculation settings, see `nicqControl`.

The data may be entered in 3 different formats, and the first argument x changes depending on which format. When z is given then x is the vector of failure times from both groups and z gives the group membership of each of those failures. If there is right censoring this may be given using status, and the nicq function will make sure that the censoring happens late enough so that the test can still be calculated. When yc is given then x is a vector of failure times in the test group and yc are the failure times in the control group. When ic is an integer, then x represents the number of failure times that have occurred in the test group at or before the time of the icth failure in the control group. In this last format only nc (number in control group) and nt (number in the test group) must be given.

The confidence interval is calculated on the difference, F2(t0)-F1(t0), where t0 is unknonwn and defined so that F1(t0)=q, with q given.

The responses can be any numeric values, as long as the difference, F2(t0)- F1(t0), is of interest.

For more details see Fay and Follmann (2015).

The confidence intervals for the qth quantile of the control is calculated using the bpcp function followed by the quantile.kmciLR from the bpcp R package.

An nicq object which inherits from htest class (the print method for is slightly different). A list with elements:

`statistic`	number of failure in test group at or before the qth quantile of the control group
`parameter`	vector with elements: q (quantile of interest in control group),i (rank of qth quantile), n1 (number in control group), n2 (number in test group)
`p.value`	one-sided p.value
`conf.int`	confidence interval on F2(t0)-F1(t0), may be one- or two-sided, see attributes
`estimate`	vector of estimates. Values are: x2/n2= proportion of failures in test group by i, i/n1= proportion failures in control group by i, 'x2/n2-i/n1'=difference, tau=qth quantile of control (same at t0), lower CL=lower confidence limit for tau, upper CL, conf.level=conf.level for CI on tau
`null.value`	null value for the difference
`alternative`	either 'less' or 'greater'. two.sided is not allowed
`method`	description of test

Since 'two.sided' alternatives are not allowed, the p-values may not match the confidence intervals in the usual way if conf.sided='two.sided' (the default). Consider the example below, with alternative='less' and delta0=0.10. The p-value is 0.04, so we might expect that the upper limit of the 95 percent confidence limit would be less than 0.10, but this is not so because conf.sided='two.sided' and we are using the two-sided confidence interval and p is greater than 0.05/2=0.025.

Michael P. Fay (mfay@niaid.nih.gov)

Fay, MP and Follmann DA (2015). Non-inferiority Tests for Anti-Infective Drugs using Control Quantiles. (unpublished manuscript).

## if you know that q=0.20 and there are no ties then ic=q*nc=40 
nicqTest(66,g=nimDiffOR,delta0=.1,q=.2,nc=200,nt=300,ic=40,conf.int=FALSE)
## examples with confidence intervals may be slower: see
##  demo(nicqTest.examples)

Loading required package: bpcp
Loading required package: survival
Loading required package: ggplot2
Loading required package: ssanv

	Non-inferiority test for variable margin using control quantiles with
	F1(tau)=0.2 with variable margin function=nimDiffOR and assuming no
	tied responses

data:  
x2=x_2(t_1(i)) = 66, q = 0.2, i = 40.0, n1 = 200.0, n2 = 300.0, p-value
= 0.04172
alternative hypothesis: true F2(tau)-F1(tau) 
 [where F1(tau)=0.2] is less than 0.1

proportions and difference:
     x2/n2       i/n1 x2/n2-i/n1 
      0.22       0.20       0.02