gROC: ROC curve estimation (generalization included)
In nsROC: Non-Standard ROC Curve Analysis

Description Usage Arguments Details Value References Examples

This function estimates the Receiver Operating Characteristic curve and returns a 'groc' object. This object can be printed or plotted. It is the main function of the package and it includes the ROC curve generalization for non-monotone relationships (see References below).

gROC(X, D, ...)
## Default S3 method:
gROC(X, D, side=c("right", "left", "both", "both2", "auto"),
          Ni = NULL,  plot.roc = FALSE, plot.density = FALSE,
          pval.auc = FALSE, B = 500, ...)

`X`	vector of (bio)marker values.
`D`	vector of response values.
`side`	type of ROC curve. One of "right", "left", "both", "both2" or "auto". If the user does not specify the method, "right" is considered, i.e., the right-sided ROC curve is estimated. If "auto", one of "right" or "left" is assigned automatically according to the Wilcoxon statistic. If the estimate is lower than \frac{number \; of \; controls \times number \; of \; cases}{2}, the right-sided ROC curve is computed, otherwise the left one is considered. If "both", the gROC curve is estimated in the usual way (controls inside the interval) and if "both2", the opposite direction is considered.
`Ni`	number of subintervals of the unit interval (FPR values) considered to calculate the curve. Default: NULL (in this case the fast algorithm considering as many FPR values as number of controls is considered).
`plot.roc`	if TRUE, ROC curve estimate considered is displayed.
`plot.density`	if TRUE, density estimates for the (bio)marker in the positive and negative subjects are displayed in the same plot.
`pval.auc`	if TRUE, a permutation test to test if the AUC differs from $0.5$ is performed. Available if Ni is NULL. Default: FALSE.
`B`	number of permutations used for testing. Default: 500.
`...`	additional arguments for `gROC`. Ignored.

First of all, the data introduced is checked by the ROCcheck function.

If side is not specified, one of "right" or "left" options is considered according to the comparison of the Wilcoxon test estimate and \frac{number \; of \; controls \times number \; of \; cases}{2}. In this case, Wilcoxon rank test is performed in order to test the alternative hypothesis median(controls)<median(cases) and the resulting p-value is shown but side selection is just based in the aforementioned comparison, without taking into account the p-value of the test.

If Ni is NULL, the general ROC curve, R_g(.) is estimated considering every different pair (t, γ \cdot t) available on data. Otherwise it is estimated using {0, 1e-3, 2e-3, ..., 1} as a grid for γ in the unit interval.

If both plot.density and plot.roc are TRUE they are displayed in the same window.

A list of class "groc" with the following content:

`levels`	levels in `D`. The two first ones are the labels of `D` considered controls and cases, respectively.
`controls`	marker values for controls.
`cases`	marker values for cases.
`side`	direction of the comparison between controls and cases. One of "right", "left", "both" or "both2". If `side` is `auto` in input arguments, the output will be the one considered by the function (according to the comparison specified above).
`pvalue.wilcox`	p-value of Wilcoxon test performed to compare cases and controls. Alternative hypothesis: median(controls)<median(cases).
`t`	vector of values of t: {0, 1/`Ni`, 2/`Ni`, ..., 1}.
`roc`	vector of values of R(t) for each t.
`auc`	area under the ROC curve estimate by trapezoidal rule.
`pval.auc`	p-value of the permutation test over the AUC.
`Paucs`	different permutation AUCs displayed if the hypothesis test is performed.
`points.coordinates`	coordinates of the points (FPR, TPR) where the ROC curve estimate has a step in case of right or left-sided curves. The first column corresponds to the values of the `points` vector providing these coordinates.
`pairpoints.coordinates`	coordinates of the points (FPR, TPR) where the ROC curve estimate has a step in case of general curves. The first and second columns correspond to the values of the `pairpoints` matrix providing these coordinates.
`param`	a logical value indicating if the estimation procedure whether parametric or not.
`Ni`	number of subintervals of the unit interval considered to build the curve.
`points`	if `Ni` != `NULL`, vector of cut-off points of the (bio)marker considered to estimate left or right-sided ROC curves. It corresponds to the sorted marker-values, including -∞ and ∞.
`pairpoints`	if `Ni` != `NULL`, matrix whose rows correspond to each pair of cut-off points (xl,xu) such that xl<xu of the (bio)marker considered to estimate general ROC curves.
`specificities`	if `Ni` != `NULL`, vector of specificities associated to `points` if left or right-sided ROC curves are considered and those ones corresponding to `pairpoints` in case of general ROC curves. It could contain repeated values in both cases.
`sensitivities`	if `Ni` != `NULL`, vector of sensitivities associated to `points` if left or right-sided ROC curves are considered and those ones corresponding to `pairpoints` in case of general ROC curves. It could contain repeated values in both cases.
`coordinates`	if `Ni` != `NULL`, matrix whose first column is constituted by the unique values of FPR (1-`specificities`) and its second column is formed by the corresponding values of TPR (`sensitivities`). In the case of general ROC curves, several TPR values could be associated with the same FPR value.
`index`	if `Ni` != `NULL`, in general ROC curves, a vector displaying which row(s) of the `pairpoints` matrix correspond(s) to `pairpoints.coordinates`.

Martinez-Camblor P., Corral N., Rey C., Pascual J., Cernuda-Morollon E., 2014, ROC curve generalization for non-monotone relationships, Statistical Methods in Medical Research, 26(1), 113-123.

# Basic example (side="auto") -> Output side is "right"
set.seed(123)
X <- c(rnorm(45), rnorm(30,2,1.5))
D <- c(rep(0,45), rep(1,30))
gROC(X,D)

# Basic example (side="auto") -> Output side is "left"
X <- c(rnorm(45), rnorm(30,-2,1.5))
D <- c(rep(0,45), rep(1,30))
gROC(X,D)

# General ROC curve example
X <- c(rnorm(45), rnorm(30,1,4))
D <- c(rep(0,45), rep(1,30))
gROC(X, D, side="both")

# Plot density estimates and ROC curve in the same plot
X <- c(rnorm(45), rnorm(30,2,1.5))
D <- c(rep(0,45), rep(1,30))
gROC(X, D, plot.roc=TRUE, plot.density=TRUE)

Data was encoded with 0 (controls) and 1 (cases).
Wilcoxon rank sum test:
 	 alternative hypothesis: median(controls) < median(cases); p-value = 1.482e-09 
It is assumed that larger values of the marker indicate larger confidence that a given subject is a case.
There are 45 controls and 30 cases.
The area under the ROC curve (AUC) is 0.877.
Data was encoded with 0 (controls) and 1 (cases).
Wilcoxon rank sum test:
 	 alternative hypothesis: median(cases) < median(controls); p-value = 1 
It is assumed that lower values of the marker indicate larger confidence that a given subject is a case.
There are 45 controls and 30 cases.
The area under the ROC curve (AUC) is 0.867.
Data was encoded with 0 (controls) and 1 (cases).
It is assumed that both lower and larges values of the marker indicate larger confidence that a given subject is a case.
There are 45 controls and 30 cases.
There are pairs of points returning the same sensitivity and specificity (See pairpoints.coordinates) 
The area under the ROC curve (AUC) is 0.923.
Data was encoded with 0 (controls) and 1 (cases).
Wilcoxon rank sum test:
 	 alternative hypothesis: median(controls) < median(cases); p-value = 8.965e-13 
It is assumed that larger values of the marker indicate larger confidence that a given subject is a case.
There are 45 controls and 30 cases.
The area under the ROC curve (AUC) is 0.93.