R: Provide point estimates for the extended Youden index, the...
Youden3Grp.PointEst
R Documentation
Provide point estimates for the extended Youden index, the associated
optimal cut-points, and sample size for three ordinal groups
Description
Estimate for the extended Youden index, the associated optimal
cut-points using normal and non-parametric methods and the
associated. The sample size to estimate the extended Youden index of a
diagnostic marker within a given margin of error under normal
assumptions is also provided.
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 D^0 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 D^0 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.
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 list of three components. “dat”: a list of compoenents x, y, z,
recording raw data inputted (with NAs removed); “dat.summary”:
a data frame of three rows (corresponding to D^-, D^0 and
D^+) separately and three columns (number of non-missing observations, mean
and SD of raw data); “est”: a data frame of one row and the following
columns numeric value components:
mu.minus
The sample mean estimate of the a diagnostic's
measurements in the D^- group, which is sample mean of data if
method=“Normal”/“EMP”/“KS”/“KS-SJ” while
if method=“TN”, mu.minus is the sample mean of
the data after Box-cox transformation.
mu0
The sample mean estimate of the a diagnostic's
measurements in the D0 group, which is sample mean of data if
method=Normal while if method=TN, mu0 is the sample mean of
the data after Box-cox transformation.
mu.plus
The sample mean estimate of the a diagnostic's
measurements in the D+ group, which is sample mean of data if
method=Normal while if method=TN, mu.plus is the sample mean of
the data after Box-cox transformation.
s.minus
The sample standard deviation (SD) estimate of the a diagnostic's
measurements in the D- group, which is sample SD of data if
method=Normal while if method=TN, the s.minus is the sample SD of
the data after Box-cox transformation.
s0
The sample standard deviation (SD) estimate of the a diagnostic's
measurements in the D0 group, which is sample SD of data if
method=Normal while if method=TN, the s0 is the sample SD of
the data after Box-cox transformation.
s.plus
The sample standard deviation (SD) estimate of the a diagnostic's
measurements in the D+ group, which is sample SD of data if
method=Normal while if method=TN, the s.plus is the sample SD of
the data after Box-cox transformation.
t.minus
The estimate of the lower optimal cut-point.
t.plus
The estimate of the upper optimal cut-point.
Se
Sensitivity, the probability of a randomly selected subject
from D+ group has a test result above t.plus.
Sp
Specificity the probability of a randomly selected subject
from D- group has a test result below t.minus.
Sm
The probability of a randomly selected subject
from D0 group has a test result between t.minus and t.plus.
youden
The extended Youden index for three ordinal groups
attained at the optimal cut-point t.minus and t.plus.
youden.z
The Fisher's Z transformation of the extended Youden
index.
lambda.est
The estimated lambda, the parameter used in
Box-Cox transformation y=(x^lambda-1)/lambda. The estimate will be a
numeric value when the method=TN is
used to estimate the extended Youden index and NA when other methods
were used.
t.minus.TN
The optimal lower cut-point t.minus estimated for the data after Box-Cox
transformation. The estimate will be a numeric value when the method=TN is
used to estimate the extended Youden index and NA when other methods
are used.
t.plus.TN
The optimal upper cut-point t.plus estimated for the
data after Box-Cox transformation. The estimate will be a numeric
value when the method=TN is used to estimate the extended Youden
index and NA when other methods are used.
sampleSize
The sample size on investigating a diagnostic test
based on pilot measurments x, y, z. The sample size calculated such
that based on given population proportion of the three diagnosis
groups, the margin of error on the (1-typeIerror)*100% confidence
interval of the extended Youden index estimate under normality is
as specified, by default 0.05.
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).
See Also
Youden3Grp.Variance.Bootstrap
Examples
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.normal <- Youden3Grp.PointEst(x=x, y=y, z=z, method = "Normal")
youden.res.normal$est$youden
##Kernel smoothing method with Sheather-Jones plug-in method
youden.res.KS <- Youden3Grp.PointEst(x=x, y=y, z=z, method = "KS-SJ",randomStart.N=3)
youden.res.KS$est$youden
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.PointEst.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Youden3Grp.PointEst
> ### Title: Provide point estimates for the extended Youden index, the
> ### associated optimal cut-points, and sample size for three ordinal
> ### groups
> ### Aliases: Youden3Grp.PointEst
> ### 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.normal <- Youden3Grp.PointEst(x=x, y=y, z=z, method = "Normal")
> youden.res.normal$est$youden
[1] 0.5892511
>
> ##Kernel smoothing method with Sheather-Jones plug-in method
> youden.res.KS <- Youden3Grp.PointEst(x=x, y=y, z=z, method = "KS-SJ",randomStart.N=3)
> youden.res.KS$est$youden
[1] 0.6533407
>
>
>
>
>
> dev.off()
null device
1
>