README.md
1[![Build Status](https://api.travis-ci.com/xrobin/pROC.svg?branch=master)](https://app.travis-ci.com/github/xrobin/pROC)
2[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/xrobin/pROC?branch=master&svg=true)](https://ci.appveyor.com/project/xrobin/pROC)
3[![Codecov coverage](https://codecov.io/github/xrobin/pROC/branch/master/graphs/badge.svg)](https://codecov.io/github/xrobin/pROC)
4[![CRAN Version](http://www.r-pkg.org/badges/version/pROC)](https://cran.r-project.org/package=pROC)
5[![Downloads](http://cranlogs.r-pkg.org/badges/pROC)](https://cran.r-project.org/package=pROC)
6
7pROC
8=============
9
10An [R](https://www.r-project.org/) package to display and analyze ROC curves.
11
12For more information, see:
13
141. Xavier Robin, Natacha Turck, Alexandre Hainard, *et al.* (2011) “pROC: an open-source package for R and S+ to analyze and compare ROC curves”. *BMC Bioinformatics*, **7**, 77. DOI: [10.1186/1471-2105-12-77](http://dx.doi.org/10.1186/1471-2105-12-77)
152. [The official web page on ExPaSy](http://www.expasy.org/tools/pROC/)
163. [The CRAN page](https://cran.r-project.org/package=pROC)
174. [My blog](http://xavier.robin.name/tag/pROC/)
185. [The FAQ](https://github.com/xrobin/pROC/wiki/FAQ---Frequently-asked-questions)
19
20Stable
21-------
22
23The latest stable version is best installed from the CRAN:
24
25 install.packages("pROC")
26
27Getting started
28-------
29
30If you don't want to read the manual first, try the following:
31
32### Loading
33
34```R
35library(pROC)
36data(aSAH)
37```
38### Basic ROC / AUC analysis
39```R
40roc(aSAH$outcome, aSAH$s100b)
41roc(outcome ~ s100b, aSAH)
42```
43### Smoothing
44```R
45roc(outcome ~ s100b, aSAH, smooth=TRUE)
46```
47### more options, CI and plotting
48```R
49roc1 <- roc(aSAH$outcome,
50 aSAH$s100b, percent=TRUE,
51 # arguments for auc
52 partial.auc=c(100, 90), partial.auc.correct=TRUE,
53 partial.auc.focus="sens",
54 # arguments for ci
55 ci=TRUE, boot.n=100, ci.alpha=0.9, stratified=FALSE,
56 # arguments for plot
57 plot=TRUE, auc.polygon=TRUE, max.auc.polygon=TRUE, grid=TRUE,
58 print.auc=TRUE, show.thres=TRUE)
59
60 # Add to an existing plot. Beware of 'percent' specification!
61 roc2 <- roc(aSAH$outcome, aSAH$wfns,
62 plot=TRUE, add=TRUE, percent=roc1$percent)
63```
64### Coordinates of the curve
65```R
66coords(roc1, "best", ret=c("threshold", "specificity", "1-npv"))
67coords(roc2, "local maximas", ret=c("threshold", "sens", "spec", "ppv", "npv"))
68```
69### Confidence intervals
70```R
71# Of the AUC
72ci(roc2)
73
74# Of the curve
75sens.ci <- ci.se(roc1, specificities=seq(0, 100, 5))
76plot(sens.ci, type="shape", col="lightblue")
77plot(sens.ci, type="bars")
78
79# need to re-add roc2 over the shape
80plot(roc2, add=TRUE)
81
82# CI of thresholds
83plot(ci.thresholds(roc2))
84```
85### Comparisons
86```R
87 # Test on the whole AUC
88 roc.test(roc1, roc2, reuse.auc=FALSE)
89
90 # Test on a portion of the whole AUC
91 roc.test(roc1, roc2, reuse.auc=FALSE, partial.auc=c(100, 90),
92 partial.auc.focus="se", partial.auc.correct=TRUE)
93
94 # With modified bootstrap parameters
95 roc.test(roc1, roc2, reuse.auc=FALSE, partial.auc=c(100, 90),
96 partial.auc.correct=TRUE, boot.n=1000, boot.stratified=FALSE)
97```
98### Sample size
99```R
100 # Two ROC curves
101 power.roc.test(roc1, roc2, reuse.auc=FALSE)
102 power.roc.test(roc1, roc2, power=0.9, reuse.auc=FALSE)
103
104 # One ROC curve
105 power.roc.test(auc=0.8, ncases=41, ncontrols=72)
106 power.roc.test(auc=0.8, power=0.9)
107 power.roc.test(auc=0.8, ncases=41, ncontrols=72, sig.level=0.01)
108 power.roc.test(ncases=41, ncontrols=72, power=0.9)
109```
110
111
112Getting Help
113------------
114
115* Type `?pROC` on the R command line
116* Make sure you've [read the FAQ](https://github.com/xrobin/pROC/wiki/FAQ---Frequently-asked-questions)
117* Search for [questions tagged with pROC-R-package on Stack Overflow](https://stackoverflow.com/questions/tagged/proc-r-package?tab=Votes)
118
119If you still can't find an answer, you can:
120
121* [Ask a question on Stack Overflow with the pROC-r-package tag](https://stackoverflow.com/questions/ask?tags=pROC-r-package)
122* [Bug reports should be submitted to the GitHub issue tracker](https://github.com/xrobin/pROC/issues)
123
124
125
126Development
127-------
128
129### Installing the development version
130
131Download the source code from git, unzip it if necessary, and then type `R CMD INSTALL pROC`. Alternatively, you can use the [devtools](https://github.com/r-lib/devtools/wiki) package by [Hadley Wickham](http://hadley.nz) to automate the process (make sure you follow [the full instructions to get started](https://devtools.r-lib.org/)):
132
133```R
134if (! requireNamespace("devtools")) install.packages("devtools")
135devtools::install_github("xrobin/pROC")
136```
137
138### Check
139
140To run all automated tests, including slow tests:
141
142```
143cd .. # Run from parent directory
144VERSION=$(grep Version pROC/DESCRIPTION | sed "s/.\+ //")
145R CMD build pROC
146RUN_SLOW_TESTS=true R CMD check pROC_$VERSION.tar.gz
147```
148
149### vdiffr
150
151The [vdiffr](https://github.com/r-lib/vdiffr) package is used for visual tests of plots.
152
153To run all the test cases (incl. slow ones) from the command line:
154
155```R
156run_slow_tests <- TRUE
157vdiffr::manage_cases()
158```
159
160To run the checks upon R CMD check, set environment variable `NOT_CRAN=1`:
161
162```
163NOT_CRAN=1 RUN_SLOW_TESTS=true R CMD check pROC_$VERSION.tar.gz
164```
165
166### Release steps
167
1681. Get new version to release: `VERSION=$(grep Version pROC/DESCRIPTION | sed "s/.\+ //") && echo $VERSION`
1691. Build & check package: `R CMD build pROC && R CMD check --as-cran pROC_$VERSION.tar.gz`
1701. Check with slow tests: `NOT_CRAN=1 RUN_SLOW_TESTS=true R CMD check pROC_$VERSION.tar.gz`
1711. Check with R-devel: `rhub::check_for_cran()`
1721. Check reverse dependencies: `revdepcheck::revdep_check(num_workers=8, timeout = as.difftime(60, units = "mins"))`
1731. Update `Version` and `Date` in `DESCRIPTION`
1741. Update version and date in `NEWS`
1751. Create a tag: `git tag v$VERSION && git push --tags`
1761. [Submit to CRAN](https://cran.r-project.org/submit.html)
177