Youden3Grp: The wrapper function for Youden index analysis
In DiagTest3Grp: Diagnostic test summary measures for three ordinal groups

Description Usage Arguments Details Value Note Author(s) References See Also Examples

The wrapper function provide not only point estimates but also variances for the extended Youden index for three ordinal groups, the associated optimal cut-points under parametric and non-parametric methods and sample size under normal.

 Youden3Grp(x, y, z, method = c("Normal","TN","EMP","KS","KS-SJ"), randomStart.N = 1,
optim.method = NULL, t.minus.start = NULL, t.plus.start = NULL,
lam.minus = 1/3, lam0 = 1/3, lam.plus = 1/3, typeIerror = 0.05, margin
 =0.05,NBOOT=10,seed.seq=NULL,alpha=0.05,FisherZ=FALSE,...)

`x`	A numeric vector, a diagnostic test's measurements for subjects in D- (usually a healthy group).
`y`	A numeric vector, a diagnostic test's measurements for subjects in D0 (usually a mildly diseased group).
`z`	A numeric vector, a diagnostic test's measurements for subjects in D+ (usually a severly diseased group).
`method`	A character. Specify a method to be used for estimating the extended Youden index Choices include ‘Normal’—Estimate the extended Youden index under the assumption of normal distributions of a diagnostic test in the three groups. ‘TN’—Transformed normal. Implement Box-cox transformation to approximate normality and then estimate the extended Youden index under normality. ‘EMP’—Estimate the extended Youden index by using empirical cumulative density function. ‘KS’—Estimate the extended Youden index by using Kernel density estimation with a normal reference rule for bandwidth selection. ‘KS-SJ’—Estimate the extended Youden index by using Kernel density estimation with the Sheather-Jones Plug-in method for bandwidth selection.
`randomStart.N`	An argument need to be specified when the method “EMP”, “KS” or “KS-SJ” is used to estimate the optimal cut-point and the extended Youden index J. Default, randomStart.N=1.
`optim.method`	A character argument. The optimization method specified to derive the optimal cut-points when nonparametric methods are used to estimate the extended Youden index. Default, optim.method=L-BFGS-B.see `optim`.
`t.minus.start`	A numeric value. The starting points of the lower optimal cut-point (t-) which separate the D- and D0 group. Default t.minus.start=NULL will randomly generate starting value.
`t.plus.start`	A numeric value. The starting points of the upper optimal cut-point (t+) which separate the D0 and D+ group. Default t.plus.start=NULL will randomly generate starting value.
`lam.minus`	A numeric value. The expected population proportion of the D- group, used for sample size calculation. Default, lam.minus=1/3. The proportions of the three ordinal groups (lam.minus, lam0, lam.plus) should sum to 1.
`lam0`	A numeric value. The expected population proportion of the D0 group, used for sample size calculation. Default, lam0=1/3. The proportions of the three ordinal groups (lam.minus, lam0, lam.plus) should sum to 1.
`lam.plus`	A numeric value. The expected population proportion of the D+ group, used for sample size calculation. Default, lam.plus=1/3.The proportions of the three ordinal groups (lam.minus, lam0, lam.plus) should sum to 1.
`typeIerror`	A numeric value. (1-typeIerror)*100% confidence interval (CI) in sample size calculation. Default typeIerror=0.05, i.e., calculate 95% CI.
`margin`	A numeric value. The margin of error on the Youden index estimate in sample size calculation. Default, margin=0.05.
`NBOOT`	A numeric value. Total number of bootstrap samples to draw for bootstrap variance and CI.
`seed.seq`	a numeric vector of length NBOOT.The sequence of random seeds for bootstrapping procedure to obtain bootstrapping variance and percentile confidence interval if methods other than “Normal” is adopted
`alpha`	A numeric value. Significance level for CI calculation. Default, alpha=0.05
`FisherZ`	Reference to the argument in `Normal.VUS`.
`...`	Other options for the R function `optim`.

Let the marker denoted by T and the density function under Di as fi, i=-,0.+. The Youden index for three ordinal groups is defined as, J(t-,t+)=1/2*(f_(T<= t-)+f0(t-<= T<= t+)+f+(T <= t+)-1]. The optimal index achieved at an optimal pair will be adopted as the final summary measure. Note that the package assumes that the marker values increase monotonically and stochastically with disease severity (the marker means in the three group D-, D0 and D+ are monotonically increasing). If a monotonically decreasing trend, the marker should be negated for anlaysis.

For the extended Youden index and optimal cut-point estimates, see reference paper for details.

For sample size calculation, the (1-typeIerror)% CI on the Youden estimate under normality is (J-Z_a*SE(J),J+Z_a*SE(J)), then the sample size will be calculated such that margin=Z_a*SE(J) or half of the CI's length, where Z_a is the normal quantile, Z_a=1.95 given default typeIerror a=0.05.

A object of DiagTest3Grp with a list of components.

`type`	A character value, type=dQuoteVUS for VUS and type=dQuoteYouden for the extended Youden index, indicating which summary measure is outputted.
`method`	A character value. For VUS, method can be “Normal” or “NonPar” (nonparametric); for Youden index, choices are “Normal/TN/EMP/KS/KS-SJ”, indicating which method is used to estimate the summary measure.
`dat`	A list of 3 components. Three components have names “x”,“y”,“z”, each recording the inputted marker measurements (after removing NAs) under D^-,D^0,D^+ respectively.
`dat.summary`	A data frame with 3 rows (D-, D0,D+) and 3 columns (number of observations,mean, SD).
`estimate`	A numerical value. Point estimate for the summary measure, either VUS or Youden.
`variance`	A numeric value. Variance on the summary measure estimate. For normal method, output normal variance; for other methods output variance from bootstrapping.
`CI`	A named numeric vector of length 2. confidence interval on the summary measure estimate, with name like 2.5%, 97.5% if significance level is set to be 5%. For both VUS and the Youden index, when normal method is in use, the CI is normal CI while bootstrap method was used under other methods.
`cut.point`	A named numeric vector of length 2. optimal cut-points with name “t.minus” for lower optimal cut point and name “t.plus” for upper optimal point.
`classify.prob`	A named numeric vector of 3 values. Estimates on the three group correct classification probabilities. specificity on D^-: Sp==Pr(x≤ t_-\|D^-); sensitivity on D^+: Se=Pr(z≥ t_+\|D^+); correct classification probability on D^0: Sm=SPr(t_-<y<t_+\|D^0). For VUS, it's empirical estimation. For Youden index, depending on method adopted for the Youden index estimate, the three probabilities will be estimated using specified method.
`sampleSize`	A numeric value The sample size to estimate the summary measure within given margin of error and type-I error rate.See `SampleSize.VUS` and `SampleSize.Youden3Grp`.
`alpha`	A numeric value. The significance level for the CI computation, e.g, default=5%.
`typeIerror`	A numeric value for type-I error rate, e.g.,default=5%.
`margin`	A numeric value. The margin of errors (precision) to estimate the summary measure s.t. the half the length of the resulting CI is equal to the given margin. Note: variance and CI on the optimal cut-points are calculated but not returned in the final DiagTest3Grp object output.
`partialDeriv`	A numeric data frame with one row and multiple columns, containing estimated SD parameters in each diagnosis group and the partial derivatives of Youden estimate w.r.t the relevant mean and SD parameters which are outputted for performance of statistical tests on markers under normal method or NA under nonparametric method.

Bug reports, malfunctioning, or suggestions for further improvements or contributions can be sent to Jingqin Luo <rosy@wubios.wustl.edu>.

Jingqin Luo

Luo, J and Xiong, C. (2012) Youden Index and Associated Optimal Cut-point for Three Ordinal Groups. Communications In Statistics-Simulation and Computation (in press).

VUS Youden3Grp.PointEst Youden3Grp.Variance.Bootstrap Youden3Grp.Variance.Normal

 data(AL)
 group <- AL$group
 table(group)

 ##take the negated FACTOR1 marker measurements
 factor1 <- -AL$FACTOR1

 x <- factor1[group=="D-"]
 y <- factor1[group=="D0"]
 z <- factor1[group=="D+"]

 ##Normal method
 youden.res <- Youden3Grp(x=x, y=y, z=z, method = "Normal")
 print(youden.res)
 plot(youden.res)


 ##Kernel smoothing method with Sheather-Jones plug-in method
## Not run: 
 youden.res.KS <- Youden3Grp(x=x, y=y, z=z, method = "KS-SJ",randomStart.N=3)
    
## End(Not run)