R: Calculation of Lower Informative SCI-bounds

informSCI {informativeSCI}

R Documentation

Calculation of Lower Informative SCI-bounds

Description

The function calculates informative lower SCI-bounds for a given graph of m hypotheses and given information weights. m is a natural number.

Usage

informSCI(
  gMCP = NULL,
  g = NULL,
  weights = NULL,
  q,
  mu_0 = 0,
  estimates = NULL,
  Z = NULL,
  pValues = NULL,
  SE = NULL,
  I = NULL,
  alpha = 0.05,
  eps = 1/10^5,
  timesSmallerEps = 3,
  randomShifts = 0,
  shifts = NULL,
  tolTrueSCI = sqrt(ifelse(!is.null(gMCP), length(getWeights(gMCP)), length(weights))) *
    eps,
  maxIter = 1000,
  maxIterBisec = 1000,
  tolBisec = 1/10^5,
  calculateCSCI = TRUE,
  checkInput = TRUE
)

Arguments

`gMCP`	An object of class `graphMCP` indicating the underlying graphical test.
`g`	Numeric square matrix of transition weights for the graphical test with m rows and m columns. The i-th row of the entered matrix defines the arrows starting from the i-th hypothesis. Each entry has to be between 0 and 1 and each row must sum to a number less than or equal to 1. The diagonal elements must be zero. Entering `g` and `weights` can be used as the input as an alternative to specifying `gMCP`.
`weights`	Numeric vector of weights of dimension m. It defines the initial proportion of significance level which is assigned to each null hypothesis. Entering `g` and `weights` can be used as the input as an alternative to specifying `gMCP`.
`q`	A numeric vector of dimension 1 or m defining the information weights for each hypothesis. The entries have to be between 0 and 1 (inclusive). If `q` has dimension 1, the same information weight is used for each hypothesis.
`mu_0`	A numeric vector of dimension 1 or m defining the bounds of the null hypotheses of the underlying graphical test. If `mu_0` has dimension 1, the same value is used for each null hypothesis.
`estimates`	An m-dimensional numeric vector of unbiased point estimates for the parameters of interest. Each estimator is assumed to be (asymptotically) normal.
`Z`	An m-dimensional numeric vector of z-scores for testing the null hypotheses. `Z` can be entered as an alternative to `estimates`.
`pValues`	An m-dimensional numeric vector of p-values from (asymptotic) z-tests for testing the null hypotheses. `pValues` can be entered as an alternative to `estimates` and `Z`.
`SE`	A positive numeric vector of dimension 1 or m indicating the standard errors of the point estimators. If `SE` has dimension 1, the same value is used for each estimator.
`I`	A positive numeric vector indicating the information of the estimators. It can be entered as an alternative to the vector `SE`. The relationship `SE=1/I^{1/2}` is assumed.
`alpha`	A numeric defining the overall significance level for the graphical test (i.e. SCIs will have coverage probability of at least `1-alpha`. The parameter must be strictly between 0 and 1.
`eps`	A numeric indicating the desired strict upper bound on the Chebyshev distance between two successive calculated approximations (the Chebyshev distance is induced by the maximum norm).
`timesSmallerEps`	A positive integer indicating how many times the Chebyshev distance of two successive calculated approximations should be less than `eps` in succession. Here we use the convention `\|-\infty-(-\infty)\|:=0`.
`randomShifts`	A positive integer indicating how many random directions of length `tolTrueSCI` should be generated. At the end of the algorithm the parameter is passed to the `inExactSCI`- and the `notInExactSCI`-functions to determine whether the approximation `L` of the true lower SCI-bounds is precise or imprecise.
`shifts`	A matrix with m columns and any number of rows. Each entry must be non-negative. Each row is a direction in the m-dimensional real space. Each row must have at least one positive entry. At the end of the algorithm the parameter is passed to the `inExactSCI`- and the `notInExactSCI`-functions to determine whether the approximation `L` of the true lower SCI-bounds is precise or imprecise. `randomShifts` must be a positive integer or `shifts` must contain at least one row. It is recommended to choose `randomShifts>0` or enter a `shifts`-matrix with at least one row. Entering both parameters is also permissible.
`tolTrueSCI`	The randomly generated shift-vectors and the row vectors in `shifts` are rescaled to have length `tolTrueSCI`. It is recommended to choose `tolTrueSCI` greater than `\sqrt{m}\cdoteps` and greater than `tolBisec`.
`maxIter`	Maximum number of iterations for determining the lower informative SCI bounds.
`maxIterBisec`	Maximum number of iterations of the bisection method which is used during the algorithm for finding roots.
`tolBisec`	A non-negative numeric indicating the error tolerance of the bisection method which is used for finding roots.
`calculateCSCI`	A boolean indicating whether compatible bounds should also be calculated.
`checkInput`	A boolean specifying whether the entered values should be checked.

Details

It is assumed that there are m parameters of interest \vartheta_1,\dots,\vartheta_m. For each parameter there is a null hypothesis defined as H_i^{{\mu_0}_i}:\vartheta_i\leq{\mu_0}_i. The bounds {\mu_0} correspond to mu_0. The parameter gMCP or the parameters g and weights define a graphical multiple test procedure for the hypotheses.

The algorithm further assumes that for each hypothesis there is an unbiased point estimator which is (asymptotically) normal. The informSCI-algorithm is based on the p-values from the corresponding (asymptotic) z-tests.

The algorithm terminates when the Chebyshev distance of two successive calculated approximations is less than eps timesSmallerEps-times in succession or if the maximum number of iterations is reached.

The function also tries to find information about the precision of the final calculated approximation of the true lower informative SCI-bounds by calling the inExactSCI- and the notInExactSCI-functions.

For further details see the given references.

Value

The function returns a list containing the calculated lower informative SCI-bounds as well as compatible lower SCI-bounds (if calculateCSCI==TRUE) to allow a comparison. Additionally, the returned list contains elements which can give some information about the precision of the calculated lower informative SCI-bounds compared to the true informative SCI-bounds.

L: A numeric vector of dimension m of the lower informative SCI-bounds
rejecHyp: A boolean vector of dimension m indicating the rejected hypotheses of the multiple test induced by the informative SCI-bounds
diffApprox: A non-negative numeric indicating the Chebyshev distance between the calculated last two approximations of the lower informative SCI-bounds.
timesApprSmallerEps: A natural number between 0 and timesSmallerEps indicating how many times the Chebyshev distance of two successive calculated approximations in succession was less than eps when the algorithm terminated.
numIter: A natural number indicating the number of iterations required by the algorithm.
accuracyL: A string containing information about the collected information about the precision of the calculated lower informative SCI-bounds compared with the true lower SCI-bounds.

If calculateCSCI=TRUE:

informSCIcompatible: A boolean vector of dimension m indicating whether each informative bound is compatible to the test decision about its corresponding null hypothesis by the underlying graphical test.
cSCI: A numeric vector of dimension m of compatible lower SCI-bounds from simConfint.
rejecHypGraph: A boolean vector of dimension m indicating the rejected hypotheses of the underlying graphical test.

References

F. Bretz, W. Maurer, W. Brannath, M. Posch: A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine 28.4 (2009), pp. 586-604.

K. Strassburger, F. Bretz: Compatible simultaneous lower confidence bounds for the Holm procedure and other Bonferroni based closed tests. Statistics in Medicine 27.4 (2008), pp. 4914-4927.

S. Schmidt, W. Brannath: Informative Simultaneous Confidence Intervals in Hierarchical Testing. Methods of Information in Medicine 53.4 (2014), pp. 278–283.

Examples

informSCI(gMCP=BonferroniHolm(3), q=0.3, mu_0=-0.5 ,estimates=c(0,2,-1),
SE=0.1467)
Z <- (c(0,2,-1)-(-0.5))/0.1467
informSCI(gMCP=BonferroniHolm(3), q=0.3, mu_0=-0.5, Z=Z, I=1/(0.1467^2),
randomShifts=100)
informSCI(g=matrix(c(0,0,1,0),2,2), weights=c(1,0), q=c(0.0068,1),
mu_0=c(-1,0), pValues=c(0.0002,0.01), SE=c(0.31,1.11), alpha=0.025, 
shifts=rbind(c(1,0),c(0,1),c(1,1)))
informSCI(g=matrix(c(0,0,1,0),2,2), weights=c(1,0), q=c(0.0068,1),
mu_0=c(-1,0), pValues=c(0.0002,0.01), I=1/c(0.31,1.11)^2, alpha=0.025, 
shifts=rbind(c(1,0),c(0,1),c(1,1)), calculateCSCI = FALSE)

[Package informativeSCI version 1.0.3 Index]