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.
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.
Details
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.
Value
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.
Note
Bug reports, malfunctioning, or suggestions for further improvements or
contributions can be sent to Jingqin Luo <rosy@wubios.wustl.edu>.
Author(s)
Jingqin Luo
References
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).
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)
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(DiagTest3Grp)
Loading required package: car
Loading required package: KernSmooth
KernSmooth 2.23 loaded
Copyright M. P. Wand 1997-2009
Loading required package: gplots
Attaching package: 'gplots'
The following object is masked from 'package:stats':
lowess
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/DiagTest3Grp/Youden3Grp.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Youden3Grp
> ### Title: The wrapper function for Youden index analysis
> ### Aliases: Youden3Grp
> ### Keywords: htest nonparametric smooth design optimize
>
> ### ** Examples
>
>
> data(AL)
> group <- AL$group
> table(group)
group
D- D0 D+
45 44 29
>
> ##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)
The DiagTest3Grp summary measure: Youden
Method used for Youden:Normal
Raw Data Summary:
n mu sd
D- 45 -0.5693309 0.8879526
D0 43 1.6222666 1.7218812
D+ 21 4.1991891 1.6988983
Youden=0.5893,95% CI=0.4967~0.6819
Best cut-points: lower=0.5843, upper=2.9041
The group correct classification probabilities are:
Sp Sm Se
0.9031 0.4984 0.7771
Sample Size to estimate Youden within specified margin of error=101
> plot(youden.res)
>
>
> ##Kernel smoothing method with Sheather-Jones plug-in method
> ## Not run:
> ##D youden.res.KS <- Youden3Grp(x=x, y=y, z=z, method = "KS-SJ",randomStart.N=3)
> ##D
> ## End(Not run)
>
>
>
>
>
> dev.off()
null device
1
>