diff --git a/DESCRIPTION b/DESCRIPTION
index dad6f0b..02ddcc9 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,34 +1,35 @@
Package: challengeR
Type: Package
Title: Analyzing assessment data of biomedical image analysis competitions and visualization of results
-Version: 1.0.4
-Date: 2022-10-15
-Author: Manuel Wiesenfarth, Matthias Eisenmann, Laura Aguilera Saiz, Annette Kopp-Schneider
+Version: 1.0.5
+Date: 2023-08-10
+Author: Manuel Wiesenfarth, Matthias Eisenmann, Laura Aguilera Saiz, Annette Kopp-Schneider, Ali Emre Kavur
Maintainer: Manuel Wiesenfarth <m.wiesenfarth@dkfz.de>
Description: Analyzing assessment data of biomedical image analysis competitions and visualization of results.
License: GPL (>= 2)
Depends:
R (>= 3.5.2),
ggplot2 (>= 3.3.0),
purrr (>= 0.3.3)
Imports:
dplyr (>= 0.8.5),
graph (>= 1.64.0),
knitr (>= 1.28),
methods (>= 3.6.0),
plyr (>= 1.8.6),
relations (>= 0.6-9),
reshape2 (>= 1.4.3),
rlang (>= 0.4.5),
rmarkdown (>= 2.1),
tidyr (>= 1.0.2),
viridisLite (>= 0.3.0)
Suggests:
doParallel (>= 1.0.15),
+ doRNG (>= 1.8.6),
foreach (>= 1.4.8),
ggpubr (>= 0.2.5),
Rgraphviz (>= 2.30.0),
testthat (>= 2.1.0)
VignetteBuilder: knitr
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.0
diff --git a/HIP_Logo.png b/HIP_Logo.png
deleted file mode 100644
index 274e293..0000000
Binary files a/HIP_Logo.png and /dev/null differ
diff --git a/Helmholtz_Imaging_Logo.svg b/Helmholtz_Imaging_Logo.svg
new file mode 100644
index 0000000..ff4ff26
--- /dev/null
+++ b/Helmholtz_Imaging_Logo.svg
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ version="1.1"
+ id="svg2"
+ width="613.44"
+ height="123.84"
+ viewBox="0 0 613.44 123.84"
+ sodipodi:docname="RZ_211119_Helmholtz-Imaging_Logo_RGB_Black.svg"
+ inkscape:version="1.1.1 (3bf5ae0d25, 2021-09-20)"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:svg="http://www.w3.org/2000/svg">
+ <defs
+ id="defs6" />
+ <sodipodi:namedview
+ id="namedview4"
+ pagecolor="#ffffff"
+ bordercolor="#999999"
+ borderopacity="1"
+ inkscape:pageshadow="0"
+ inkscape:pageopacity="0"
+ inkscape:pagecheckerboard="0"
+ showgrid="false"
+ inkscape:zoom="2.0605111"
+ inkscape:cx="323.94875"
+ inkscape:cy="-42.950508"
+ inkscape:window-width="1920"
+ inkscape:window-height="1001"
+ inkscape:window-x="-9"
+ inkscape:window-y="-9"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="g8" />
+ <g
+ inkscape:groupmode="layer"
+ inkscape:label="Image"
+ id="g8">
+ <path
+ style="fill:#000000;fill-opacity:1;stroke-width:0.32"
+ d="m 338.9096,122.53197 c -9.79402,-2.17387 -16.51306,-9.12593 -18.6073,-19.25254 -0.62624,-3.02823 -0.435,-9.800497 0.35917,-12.71875 1.79943,-6.61224 6.57069,-12.541978 12.48813,-15.52032 3.94653,-1.986352 6.86739,-2.625389 12,-2.625389 5.17098,0 8.03504,0.634963 12.16,2.695866 5.02883,2.512499 8.98579,7.464099 9.85315,12.329843 l 0.29949,1.68 h -5.98566 -5.98567 l -0.37651,-1.25665 c -0.20707,-0.691158 -0.98816,-1.885987 -1.73571,-2.655177 -3.40723,-3.505779 -9.12531,-4.349293 -14.0865,-2.077987 -8.94451,4.094937 -11.03667,19.221544 -3.67584,26.577094 6.46611,6.46147 18.45523,4.89835 21.32835,-2.78076 0.38144,-1.0195 0.61111,-1.98704 0.51034,-2.15008 -0.10077,-0.16304 -2.04672,-0.29644 -4.32432,-0.29644 h -4.14112 v -4 -4 h 12.48 12.48 v 4 4 h -2.24685 c -2.55309,0 -2.29625,-0.27334 -3.52256,3.7493 -2.04845,6.71964 -7.37789,11.73801 -14.71936,13.8602 -3.23286,0.93453 -11.23648,1.17752 -14.55123,0.44179 z m 142.75232,0.004 c -9.81434,-2.19459 -16.61328,-9.13219 -18.60666,-18.98614 -0.76064,-3.76014 -0.5184,-10.462372 0.49258,-13.628673 3.20765,-10.04601 10.83581,-16.291376 21.32739,-17.461255 9.08099,-1.012592 18.21875,2.611802 22.37623,8.8753 1.38528,2.087024 2.69814,5.415456 2.69814,6.840512 v 0.945443 h -5.88531 -5.88531 l -0.2073,-0.825895 c -0.54618,-2.17624 -3.22346,-4.774918 -5.88774,-5.714937 -4.80666,-1.695885 -10.66615,-0.260295 -14.00231,3.430614 -5.9663,6.600685 -5.53379,18.799371 0.86394,24.366771 5.12099,4.45637 13.95155,4.47765 18.38489,0.0443 1.6033,-1.60329 3.28266,-4.93562 2.84458,-5.64443 -0.10077,-0.16304 -2.04672,-0.29644 -4.32432,-0.29644 h -4.14112 v -4 -4 h 12.48 12.48 v 4 4 h -2.39389 c -2.35315,0 -2.39709,0.015 -2.57984,0.88 -0.5112,2.41955 -2.17024,6.39032 -3.51533,8.41361 -2.57939,3.87998 -6.83264,6.82038 -12.04822,8.32934 -3.17427,0.91837 -11.22077,1.15852 -14.4704,0.43186 z M 0.1896014,97.92068 v -24.16 h 5.44 5.4399996 v 9.76 9.76 h 8.48 8.48 v -9.76 -9.76 h 5.44 5.44 v 24.16 24.16 h -5.44 -5.44 v -9.6 -9.6 h -8.48 -8.48 v 9.6 9.6 h -5.4399996 -5.44 z m 63.0399996,18.56 v -5.6 h 22.88 22.879999 v -18.56 -18.56 h 5.6 5.6 v 24.16 24.16 h -28.479999 -28.48 z m 117.759999,-18.88 v -24.16 h 5.6 5.6 v 24.16 24.16 h -5.6 -5.6 z m 26.88,0 v -24.16 h 6.37701 6.37701 l 0.63349,1.68 c 2.75106,7.295651 11.94365,31.10826 12.15433,31.48471 0.17931,0.32041 2.32423,-4.95813 6.6415,-16.344416 l 6.37666,-16.817664 6.32,-0.0013 6.32,-0.0013 v 24.16 24.16 h -5.4368 -5.43681 l -0.0832,-14.70617 -0.0832,-14.706169 -5.12,14.705749 -5.12,14.70575 -4.19423,3.2e-4 -4.19424,5.2e-4 -5.19656,-14.48 c -2.85811,-7.964 -5.32671,-14.6168 -5.48577,-14.784 -0.17248,-0.181309 -0.2892,5.66272 -0.2892,14.48 v 14.78397 h -5.27999 -5.28 z m 62.08097,21.52705 c 0.52468,-1.45588 4.39787,-12.29505 8.60707,-24.08705 l 7.6531,-21.44 h 5.18514 5.18515 l 8.45169,23.36 c 4.64843,12.848 8.53678,23.68724 8.64078,24.08719 l 0.18909,0.7272 -6.01009,-0.0872 -6.0101,-0.0872 -0.93307,-2.8 -0.93306,-2.8 h -8.58667 -8.58667 l -0.93306,2.8 -0.93307,2.8 -5.9701,0.0871 -5.9701,0.087 z m 27.05357,-12.64705 c -0.7107,-3.18594 -5.58625,-19.029331 -5.73616,-18.64 -0.41573,1.079722 -5.63838,18.82663 -5.63838,19.1596 0,0.25391 1.70944,0.3604 5.78543,0.3604 h 5.78542 z m 87.82546,-8.88 v -24.16 h 5.6 5.6 v 24.16 24.16 h -5.6 -5.6 z m 26.88,0 v -24.16 l 5.84,0.0068 5.84,0.0068 8.64,15.664051 c 4.752,8.615229 8.748,15.668139 8.88,15.673149 0.132,0.005 0.24,-7.046896 0.24,-15.670896 V 73.44068 h 5.44 5.44 v 24.16 24.16 h -5.8737 -5.87369 l -8.60631,-15.38475 -8.6063,-15.384754 -0.0831,15.384754 -0.0831,15.38475 h -5.59693 -5.59693 z m 45.92,-47.721847 c -1.232,-0.25832 -3.752,-1.19958 -5.6,-2.09169 -2.96851,-1.43303 -3.69933,-1.96392 -6.27235,-4.55629 -2.43395,-2.45228 -3.15722,-3.43165 -4.40317,-5.96222 -2.11683,-4.29941 -2.7887,-7.22616 -2.7887,-12.14795 0,-4.92179 0.67187,-7.84855 2.7887,-12.14795 1.99859,-4.05921 6.01331,-8.1914702 9.87552,-10.1646302 4.67286,-2.38733 6.58822,-2.80742 12.8,-2.80742 6.22147,0 8.15142,0.42473 12.8,2.81695 3.85744,1.98508 7.83757,6.0816102 9.85491,10.1430502 2.27991,4.59016 2.62835,6.2584 2.60672,12.48 -0.017,4.85448 -0.0877,5.48631 -0.8783,7.84 -1.38291,4.11691 -3.18624,7.02653 -6.27114,10.1183 -2.38544,2.39074 -3.19993,2.97472 -6.11219,4.38234 -2.03856,0.98533 -4.33005,1.81976 -5.8265,2.1217 -3.09555,0.624575 -9.53846,0.612182 -12.5735,-0.0242 z m 12.40646,-10.77063 c 10.97028,-5.4218 10.95847,-22.55909 -0.0192,-27.98458 -2.36976,-1.1712 -2.52729,-1.20294 -5.97056,-1.20294 -3.30678,0 -3.67552,0.0658 -5.67408,1.01264 -3.63939,1.72419 -6.20633,4.60573 -7.67289,8.61319 -0.56093,1.53275 -0.69322,2.59633 -0.69322,5.57417 0,2.97784 0.13229,4.04141 0.69322,5.57417 1.71081,4.67496 4.92637,7.84459 9.49037,9.35482 0.79939,0.26452 2.43494,0.39133 4.3559,0.33774 2.81862,-0.0786 3.27786,-0.18563 5.49056,-1.27921 z M 180.9896,25.120683 V 0.8006828 h 5.43538 5.43537 l 0.0846,9.8400002 0.0846,9.84 h 8.32 8.32 l 0.0846,-9.84 0.0846,-9.8400002 h 5.59537 5.59538 v 24.3200002 24.32 h -5.59531 -5.5953 l -0.0847,-9.68 -0.0847,-9.68 h -8.32 -8.32 l -0.0847,9.68 -0.0847,9.68 h -5.4353 -5.43531 z m 54.4,0 V 0.8006828 h 14.72 14.72 v 4.48 4.4800002 h -9.12 -9.12 v 5.6 5.6 h 9.12 9.12 v 4.32 4.32 h -9.12 -9.12 v 5.44 5.44 h 9.12 9.12 v 4.48 4.48 h -14.72 -14.72 z m 46.08,0 V 0.8006828 h 5.59752 5.59752 l 0.0825,19.4400002 0.0825,19.44 6.8,0.0864 6.8,0.0864 v 4.79362 4.79364 h -12.48004 -12.48 z m 38.08,-0.007 V 0.7870228 l 6.44854,0.0866 6.44855,0.0866 6.41065,16.7141302 c 3.52589,9.19276 6.49204,16.63441 6.59146,16.537 0.0995,-0.0974 3.01072,-7.61877 6.46947,-16.71412 l 6.28871,-16.5370002 6.27129,-0.0868 6.27133,-0.0868 v 24.3267602 24.32677 h -5.28 -5.28 v -14.72 c 0,-8.096 -0.108,-14.71802 -0.24,-14.71559 -0.132,0.002 -2.53994,6.63039 -5.35098,14.7288 l -5.111,14.72437 -4.12647,-0.0888 -4.12649,-0.0888 -5.21908,-14.50989 c -2.87052,-7.98044 -5.30166,-14.59244 -5.40256,-14.69333 -0.10086,-0.10089 -0.18342,6.46456 -0.18342,14.58989 v 14.77334 h -5.44 -5.44 v -24.32663 z m 66.88,0.007 V 0.8006828 h 5.59536 5.59539 l 0.0846,9.8400002 0.0846,9.84 h 8.32 8.32 l 0.0846,-9.84 0.0846,-9.8400002 h 5.43549 5.43536 v 24.3200002 24.32 h -5.4353 -5.43532 l -0.0847,-9.68 -0.0847,-9.68 h -8.32 -8.32 l -0.0847,9.68 -0.0847,9.68 h -5.59528 -5.5953 z m 114.88,0 V 0.8006828 h 5.59754 5.5975 l 0.0825,19.4400002 0.0825,19.44 6.8,0.0864 6.8,0.0864 v 4.79362 4.79364 h -12.48 -12.48 z m 40.88246,4.88 -0.0825,-19.44 -5.36,-0.0877 -5.36,-0.0877 v -4.7922602 -4.79226 h 16.48004 16.48 v 4.8 4.8000002 h -5.44 -5.44 v 19.52 19.52 h -5.59754 -5.5975 z m 29.60301,19.03884 c 0.0847,-0.22064 5.29693,-8.88238 11.58282,-19.2483 6.28589,-10.36593 11.50342,-19.04141 11.59453,-19.27884 0.13699,-0.35699 -1.69552,-0.4317 -10.58858,-0.4317 H 573.6296 v -4.6400002 -4.64 h 19.69126 c 18.6585,0 19.67498,0.0294 19.38087,0.56 -0.17069,0.308 -5.48499,9.0560002 -11.80954,19.4400002 -6.32454,10.384 -11.43744,18.988 -11.36198,19.12 0.0754,0.132 5.24067,0.24 11.47827,0.24 h 11.34112 v 4.64 4.64 h -20.35424 c -16.18333,0 -20.32269,-0.0822 -20.20029,-0.40116 z M -0.1303986,24.960683 V 0.8006828 h 42.3999996 42.4 v 5.59865 5.5986502 l -36.72,0.0814 -36.72,0.0813 -0.0826,18.48 -0.0826,18.48 H 5.467002 -0.1303986 Z m 109.1199986,0 V 0.8006828 h 5.6 5.6 v 24.1600002 24.16 h -5.6 -5.6 z"
+ id="path950" />
+ </g>
+</svg>
diff --git a/R/Bootstrap.R b/R/Bootstrap.R
index df66d74..8d172ea 100644
--- a/R/Bootstrap.R
+++ b/R/Bootstrap.R
@@ -1,219 +1,222 @@
# Copyright (c) German Cancer Research Center (DKFZ)
# All rights reserved.
#
# This file is part of challengeR.
#
# challengeR is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# challengeR is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with challengeR. If not, see <https://www.gnu.org/licenses/>.
bootstrap <- function(object,...) UseMethod("bootstrap")
bootstrap.default <- function(object, ...) stop("not implemented for this class")
#' Performs bootstrapping
#'
#' Performs bootstrapping on a ranked assessment data set and applies the ranking method to each bootstrap sample. One bootstrap sample of
#' a task with \code{n} cases consists of \code{n} cases randomly drawn with replacement from this task.
#' A total of \code{nboot} of these bootstrap samples are drawn.
#'
+#' To ensure reproducibility, please use the doRNG package on Windows or RNG kind = "L'Ecuyer-CMRG" in set.seed(), e.g. set.seed(1, kind = "L'Ecuyer-CMRG").
+#'
#' @param object The ranked assessment data set.
#' @param nboot The number of bootstrap samples.
#' @param parallel A boolean specifying whether parallel processing should be enabled.
#' @param progress A string specifying the type of progress indication.
#' @param ... Further arguments passed to or from other functions.
#'
#' @return An S3 object of class "bootstrap.list" to represent a bootstrapped, ranked assessment data set.
#'
#' @examples
#'
#' \dontrun{
#' # perform bootstrapping with 1000 bootstrap samples using one CPU
-#' set.seed(1)
+#' set.seed(123, kind="L'Ecuyer-CMRG")
#' ranking_bootstrapped <- bootstrap(ranking, nboot = 1000)
#' }
#'
#' \dontrun{
#' # perform bootstrapping using multiple CPUs (here: 8 CPUs)
#' library(doParallel)
-#' registerDoParallel(cores=8)
-#' set.seed(1)
+#' library(doRNG)
+#' registerDoParallel(cores = 8)
+#' registerDoRNG(123)
#' ranking_bootstrapped <- bootstrap(ranking, nboot = 1000, parallel = TRUE, progress = "none")
#' stopImplicitCluster()
#' }
#'
#' @export
bootstrap.ranked.list=function(object,
nboot,
parallel=FALSE,
progress="text",
...){
algorithm=attr(object$data,"algorithm")
by=attr(object$data,"case")
# exclude if only 1 test case or only 1 algorithm
tidy.data.id=sapply(object$data,
function(data.subset) {
ifelse((length(unique(data.subset[[by]]))==1 | length(unique(data.subset[[algorithm]]))<=1 ),
yes=FALSE,
no=TRUE)
})
if (sum(tidy.data.id)==0) {
if (length(object$matlist)>1) stop("All tasks only contained 1 test case. Bootstrapping with 1 test case not sensible.")
else stop("Only 1 test case included. Bootstrapping with 1 test case not sensible.")
}
if (sum(tidy.data.id)<length(object$matlist)) message("Task(s) ",
paste(names(tidy.data.id)[!tidy.data.id], collapse = ", "),
" with only 1 test case excluded from bootstrapping.")
tidy.data=object$data[tidy.data.id]
tidy.matlist=object$matlist[tidy.data.id]
res= llply(1:nboot,
function(it){
# draw 1 sample for each task
bootDatalist = lapply(tidy.data, function(data.subset) {
index = unique(data.subset[[by]])
# bootIndex=sample(index,size=length(index),replace=TRUE)
# bootData=bind_rows(lapply(bootIndex,function(zz) data.subset[data.subset[[by]]==zz,]))
# faster:
bootIndex = data.frame(sample(index,
size = length(index),
replace = TRUE))
colnames(bootIndex) = by
bootData = merge(bootIndex,
data.subset,
by = by)
bootData
})
attr(bootDatalist, "inverseOrder") = attr(object$data, "inverseOrder")
attr(bootDatalist, "algorithm") = attr(object$data, "algorithm")
attr(bootDatalist, "case") = attr(object$data, "case")
attr(bootDatalist, "check") = FALSE
object$FUN(bootDatalist)$mat
},
.parallel = parallel,
.progress = progress)
rankmatlist = lapply(res[[1]],
function(z) z[, "rank", drop = F]
)
for (j in 2:length(res)) {
rankmatlist = quickmerge.list(rankmatlist,
lapply(res[[j]],
function(z) z[, "rank", drop = F]))
}
aggmatlist = lapply(res[[1]],
function(z) z[, -2, drop = F])
for (j in 2:length(res)) {
aggmatlist = quickmerge.list(aggmatlist,
lapply(res[[j]],
function(z) z[, -2, drop = F]))
}
final=list(bootsrappedRanks=rankmatlist,
bootsrappedAggregate=aggmatlist,
data=object$data,
matlist=tidy.matlist,
FUN=object$FUN,
FUN.list=object$FUN.list)
class(final)=c("bootstrap.list")
final
}
####################################################################################################
# deprecate following functions?
rankFrequencies <- function(object,...) UseMethod("rankFrequencies")
rankFrequencies.default <- function(object, ...) stop("not implemented for this class")
rankFrequencies.bootstrap=function(object, who,...){
if (is.data.frame(who)) who=rownames(who)
if (length(who)==1){
res=table(t(object$bootsrappedRanks[rownames(object$bootsrappedRanks)==who,]))
cat("\n",who,"\n")
print(res)
} else {
res=lapply(who, function(w){
rr=table(t(object$bootsrappedRanks[rownames(object$bootsrappedRanks)==w,]))
cat(w,"\n")
print(rr)
cat("\n")
rr
})
}
res=c(list(rankFrequencies=res),object)
invisible(res)
}
rankFrequencies.bootstrap.list=function(object, who,...){
if (is.data.frame(who)) who=rownames(who)
res=lapply(object$bootsrappedRanks,function(bootMat){
if (length(who)==1){
res=table(t(bootMat[rownames(bootMat)==who,]))
cat("\n",who,"\n")
print(res)
} else {
res=lapply(who, function(w){
rr=table(t(bootMat[rownames(bootMat)==w,]))
cat(w,"\n")
print(rr)
cat("\n")
rr
})
}
res
})
res=c(list(rankFrequencies=res),object)
invisible(res)
}
winnerFrequencies <- function(object,...) UseMethod("winnerFrequencies")
winnerFrequencies.default <- function(object, ...) stop("not implemented for this class")
# Achtung: bester rank muss ==1 sein und nicht z.B. 1.5
winnerFrequencies.bootstrap=function(object,...){
rankings_dicho=ifelse(object$bootsrappedRanks==1,1,0)
winnerFrequencies=data.frame(winnerFrequency=rowSums(rankings_dicho),row.names = rownames(object$bootsrappedRanks))
res=merge(object$mat,winnerFrequencies,by="row.names",...)
rownames(res)=res[,1]
res=res[,-1]
# res=c(res=res,object)
# class(res)="bootstrapResults"
res
}
winnerFrequencies.bootstrap.list=function(object,...){
res=lapply(1:length(object$bootsrappedRanks),function(id){
rankings_dicho=ifelse(object$bootsrappedRanks[[id]]==1,1,0)
winnerFrequencies=data.frame(winnerFrequency=rowSums(rankings_dicho),row.names = rownames(object$bootsrappedRanks[[id]]))
res=merge(object$matlist[[id]],winnerFrequencies,by="row.names",...)
rownames(res)=res[,1]
res=res[,-1]
res
})
names(res)=names(object$bootsrappedRanks)
res
}
diff --git a/README.md b/README.md
index 2e5a224..37fef34 100644
--- a/README.md
+++ b/README.md
@@ -1,556 +1,658 @@
Methods and open-source toolkit for analyzing and visualizing challenge
results
================
- [Introduction](#introduction)
- [Installation](#installation)
- [Terms of use](#terms-of-use)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
- [Changes](#changes)
- [Team](#team)
- [Reference](#reference)
# Introduction
-The current framework is a tool for analyzing and visualizing challenge results in the field of biomedical image analysis and beyond.
-
-Biomedical challenges have become the de facto standard for benchmarking biomedical image analysis algorithms. While the number of challenges is steadily increasing, surprisingly little effort has been invested in ensuring high quality design, execution and reporting for these international competitions. Specifically, results analysis and visualization in the event of uncertainties have been given almost no attention in the literature.
-
-Given these shortcomings, the current framework aims to enable fast and wide adoption of comprehensively analyzing and visualizing the results of single-task and multi-task challenges. This approach offers an intuitive way to gain important insights into the relative and absolute performance of algorithms, which cannot be revealed by commonly applied visualization techniques.
+The current framework is a tool for analyzing and visualizing challenge
+results in the field of biomedical image analysis and beyond.
+
+Biomedical challenges have become the de facto standard for benchmarking
+biomedical image analysis algorithms. While the number of challenges is
+steadily increasing, surprisingly little effort has been invested in
+ensuring high quality design, execution and reporting for these
+international competitions. Specifically, results analysis and
+visualization in the event of uncertainties have been given almost no
+attention in the literature.
+
+Given these shortcomings, the current framework aims to enable fast and
+wide adoption of comprehensively analyzing and visualizing the results
+of single-task and multi-task challenges. This approach offers an
+intuitive way to gain important insights into the relative and absolute
+performance of algorithms, which cannot be revealed by commonly applied
+visualization techniques.
# Installation
-Requires R version \>= 3.5.2 (<https://www.r-project.org>).
-
-Further, a recent version of Pandoc (\>= 1.12.3) is required. RStudio (<https://rstudio.com>) automatically includes this so you do not need to download Pandoc if you plan to use rmarkdown from the RStudio IDE, otherwise you’ll need to install Pandoc for your platform (<https://pandoc.org/installing.html>). Finally, if you want to generate a PDF report you will need to have LaTeX installed (e.g. MiKTeX, MacTeX or TinyTeX).
+Requires R version >= 3.5.2 (<https://www.r-project.org>).
-To get the latest released version (master branch) of the R package from GitHub:
+Further, a recent version of Pandoc (>= 1.12.3) is required. RStudio
+(<https://rstudio.com>) automatically includes this so you do not need
+to download Pandoc if you plan to use rmarkdown from the RStudio IDE,
+otherwise you’ll need to install Pandoc for your platform
+(<https://pandoc.org/installing.html>). Finally, if you want to generate
+a PDF report you will need to have LaTeX installed (e.g. MiKTeX, MacTeX
+or TinyTeX).
+To get the latest released version (master branch) of the R package from
+GitHub:
-```r
+``` r
if (!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("Rgraphviz", dependencies = TRUE)
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
-If you are asked whether you want to update installed packages and you type "a" for all, you might need administrator permissions to update R core packages. You can also try to type "n" for updating no packages. If you are asked "Do you want to install from sources the packages which need compilation? (Yes/no/cancel)", you can safely type "no".
+If you are asked whether you want to update installed packages and you
+type “a” for all, you might need administrator permissions to update R
+core packages. You can also try to type “n” for updating no packages. If
+you are asked “Do you want to install from sources the packages which
+need compilation? (Yes/no/cancel)”, you can safely type “no”.
-If you get *warning* messages (in contrast to *error* messages), these might not be problematic and you can try to proceed. If you encounter errors during the setup, looking into the "Troubleshooting" section might be worth it.
+If you get *warning* messages (in contrast to *error* messages), these
+might not be problematic and you can try to proceed. If you encounter
+errors during the setup, looking into the “Troubleshooting” section
+might be worth it.
-For Linux users: Some system libraries might be missing. Check the output in the R console for further hints carefully during the installation of packages.
+For Linux users: Some system libraries might be missing. Check the
+output in the R console for further hints carefully during the
+installation of packages.
# Terms of use
Copyright (c) German Cancer Research Center (DKFZ). All rights reserved.
challengeR is available under license GPLv2 or any later version.
If you use this software for a publication, please cite:
-Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods and open-source toolkit for analyzing and visualizing challenge results. *Sci Rep* **11**, 2369 (2021). <https://doi.org/10.1038/s41598-021-82017-6>
+Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera
+Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods
+and open-source toolkit for analyzing and visualizing challenge results.
+*Sci Rep* **11**, 2369 (2021).
+<https://doi.org/10.1038/s41598-021-82017-6>
# Usage
-Each of the following steps has to be run to generate the report: (1) Load package, (2) load data, (3) perform ranking, (4) perform bootstrapping and (5) generation of the report
+Each of the following steps has to be run to generate the report: (1)
+Load package, (2) load data, (3) perform ranking, (4) perform
+bootstrapping and (5) generation of the report
-You can find R scripts for quickstart in the directory "vignettes". An overview of all available plots is provided in the "Visualizations" vignette demonstrating the use of their corresponding plot functions as well.
+You can find R scripts for quickstart in the directory “vignettes”. An
+overview of all available plots is provided in the “Visualizations”
+vignette demonstrating the use of their corresponding plot functions as
+well.
-Here, we provide a step-by-step guide that leads you to your final report.
+Here, we provide a step-by-step guide that leads you to your final
+report.
## 1. Load package
Load package
-
-```r
+``` r
library(challengeR)
```
## 2. Load data
### Data requirements
Data requires the following *columns*:
-- *task identifier* in case of multi-task challenges (string or numeric)
+- *task identifier* in case of multi-task challenges (string or
+ numeric)
- *test case identifier* (string or numeric)
- *algorithm identifier* (string or numeric)
- *metric value* (numeric)
-In case of missing metric values, a missing observation has to be provided (either as blank field or "NA").
-
-For example, in a challenge with 2 tasks, 2 test cases and 2 algorithms, where in task "T2", test case "case2", algorithm "A2" didn't give a prediction (and thus NA or a blank field for missing value is inserted), the data set might look like this:
-
-
-|Task |TestCase |Algorithm | MetricValue|
-|:----|:--------|:---------|-----------:|
-|T1 |case1 |A1 | 0.266|
-|T1 |case1 |A2 | 0.202|
-|T1 |case2 |A1 | 0.573|
-|T1 |case2 |A2 | 0.945|
-|T2 |case1 |A1 | 0.372|
-|T2 |case1 |A2 | 0.898|
-|T2 |case2 |A1 | 0.908|
-|T2 |case2 |A2 | NA|
+In case of missing metric values, a missing observation has to be
+provided (either as blank field or “NA”).
+
+For example, in a challenge with 2 tasks, 2 test cases and 2 algorithms,
+where in task “T2”, test case “case2”, algorithm “A2” didn’t give a
+prediction (and thus NA or a blank field for missing value is inserted),
+the data set might look like this:
+
+| Task | TestCase | Algorithm | MetricValue |
+|:-----|:---------|:----------|------------:|
+| T1 | case1 | A1 | 0.266 |
+| T1 | case1 | A2 | 0.202 |
+| T1 | case2 | A1 | 0.573 |
+| T1 | case2 | A2 | 0.945 |
+| T2 | case1 | A1 | 0.372 |
+| T2 | case1 | A2 | 0.898 |
+| T2 | case2 | A1 | 0.908 |
+| T2 | case2 | A2 | NA |
### 2.1 Load data from file
-If you have assessment data at hand stored in a csv file (if you want to use simulated data, skip the following code line) use
-
+If you have assessment data at hand stored in a csv file (if you want to
+use simulated data, skip the following code line) use
-```r
+``` r
data_matrix <- read.csv(file.choose()) # type ?read.csv for help
-
```
-This allows to choose a file interactively, otherwise replace *file.choose()* by the file path (in style "/path/to/dataset.csv") in quotation marks.
+This allows to choose a file interactively, otherwise replace
+*file.choose()* by the file path (in style “/path/to/dataset.csv”) in
+quotation marks.
### 2.2 Simulate data
-In the following, simulated data is generated *instead* for illustration purposes (skip the following code chunk if you have already loaded data). The data is also stored as "inst/extdata/data_matrix.csv" in the repository.
-
+In the following, simulated data is generated *instead* for illustration
+purposes (skip the following code chunk if you have already loaded
+data). The data is also stored as “inst/extdata/data\_matrix.csv” in the
+repository.
-```r
+``` r
if (!requireNamespace("permute", quietly = TRUE)) install.packages("permute")
n <- 50
set.seed(4)
strip <- runif(n,.9,1)
c_ideal <- cbind(task="c_ideal",
rbind(
data.frame(alg_name="A1",value=runif(n,.9,1),case=1:n),
data.frame(alg_name="A2",value=runif(n,.8,.89),case=1:n),
data.frame(alg_name="A3",value=runif(n,.7,.79),case=1:n),
data.frame(alg_name="A4",value=runif(n,.6,.69),case=1:n),
data.frame(alg_name="A5",value=runif(n,.5,.59),case=1:n)
))
set.seed(1)
c_random <- data.frame(task="c_random",
alg_name=factor(paste0("A",rep(1:5,each=n))),
value=plogis(rnorm(5*n,1.5,1)),case=rep(1:n,times=5)
)
strip2 <- seq(.8,1,length.out=5)
a <- permute::allPerms(1:5)
c_worstcase <- data.frame(task="c_worstcase",
alg_name=c(t(a)),
value=rep(strip2,nrow(a)),
case=rep(1:nrow(a),each=5)
)
c_worstcase <- rbind(c_worstcase,
data.frame(task="c_worstcase",alg_name=1:5,value=strip2,case=max(c_worstcase$case)+1)
)
c_worstcase$alg_name <- factor(c_worstcase$alg_name,labels=paste0("A",1:5))
data_matrix <- rbind(c_ideal, c_random, c_worstcase)
-
```
## 3. Perform ranking
### 3.1 Define challenge object
Code differs slightly for single- and multi-task challenges.
In case of a single-task challenge use
-
-```r
+``` r
# Use only task "c_random" in object data_matrix
dataSubset <- subset(data_matrix, task=="c_random")
challenge <- as.challenge(dataSubset,
# Specify which column contains the algorithms,
# which column contains a test case identifier
# and which contains the metric value:
algorithm = "alg_name", case = "case", value = "value",
# Specify if small metric values are better
smallBetter = FALSE)
```
*Instead*, for a multi-task challenge use
-
-```r
+``` r
# Same as above but with 'by="task"' where variable "task" contains the task identifier
challenge <- as.challenge(data_matrix,
by = "task",
algorithm = "alg_name", case = "case", value = "value",
smallBetter = FALSE)
```
### 3.2 Configure ranking
Different ranking methods are available, choose one of them:
-- for "aggregate-then-rank" use (here: take mean for aggregation)
+- for “aggregate-then-rank” use (here: take mean for aggregation)
-
-```r
+``` r
ranking <- challenge%>%aggregateThenRank(FUN = mean, # aggregation function,
# e.g. mean, median, min, max,
# or e.g. function(x) quantile(x, probs=0.05)
na.treat = 0, # either "na.rm" to remove missing data,
# set missings to numeric value (e.g. 0)
# or specify a function,
# e.g. function(x) min(x)
ties.method = "min" # a character string specifying
# how ties are treated, see ?base::rank
)
```
-- *alternatively*, for "rank-then-aggregate" with arguments as above (here: take mean for aggregation)
-
+- *alternatively*, for “rank-then-aggregate” with arguments as above
+ (here: take mean for aggregation)
-```r
+``` r
ranking <- challenge%>%rankThenAggregate(FUN = mean,
ties.method = "min"
)
```
-- *alternatively*, for test-then-rank based on Wilcoxon signed rank test
+- *alternatively*, for test-then-rank based on Wilcoxon signed rank
+ test
-
-```r
+``` r
ranking <- challenge%>%testThenRank(alpha = 0.05, # significance level
p.adjust.method = "none", # method for adjustment for
# multiple testing, see ?p.adjust
na.treat = 0, # either "na.rm" to remove missing data,
# set missings to numeric value (e.g. 0)
# or specify a function, e.g. function(x) min(x)
ties.method = "min" # a character string specifying
# how ties are treated, see ?base::rank
)
-
```
## 4. Perform bootstrapping
Perform bootstrapping with 1000 bootstrap samples using one CPU
-
-```r
-set.seed(1)
+``` r
+set.seed(123, kind = "L'Ecuyer-CMRG")
ranking_bootstrapped <- ranking%>%bootstrap(nboot = 1000)
```
If you want to use multiple CPUs (here: 8 CPUs), use
-
-```r
+``` r
library(doParallel)
+library(doRNG)
registerDoParallel(cores = 8)
-set.seed(1)
+registerDoRNG(123)
ranking_bootstrapped <- ranking%>%bootstrap(nboot = 1000, parallel = TRUE, progress = "none")
stopImplicitCluster()
```
## 5. Generate the report
-Generate report in PDF, HTML or DOCX format. Code differs slightly for single- and multi-task challenges.
+Generate report in PDF, HTML or DOCX format. Code differs slightly for
+single- and multi-task challenges.
### 5.1 For single-task challenges
-
-```r
+``` r
ranking_bootstrapped %>%
report(title = "singleTaskChallengeExample", # used for the title of the report
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex", #LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean = TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
-
```
-Argument *file* allows for specifying the output file path as well, otherwise the working directory is used. If file is specified but does not have a file extension, an extension will be automatically added according to the output format given in *format*. Using argument *clean=FALSE* allows to retain intermediate files, such as separate files for each figure.
+Argument *file* allows for specifying the output file path as well,
+otherwise the working directory is used. If file is specified but does
+not have a file extension, an extension will be automatically added
+according to the output format given in *format*. Using argument
+*clean=FALSE* allows to retain intermediate files, such as separate
+files for each figure.
-If argument "file" is omitted, the report is created in a temporary folder with file name "report".
+If argument “file” is omitted, the report is created in a temporary
+folder with file name “report”.
### 5.2 For multi-task challenges
-Same as for single-task challenges, but additionally consensus ranking (rank aggregation across tasks) has to be given.
+Same as for single-task challenges, but additionally consensus ranking
+(rank aggregation across tasks) has to be given.
-Compute ranking consensus across tasks (here: consensus ranking according to mean ranks across tasks)
+Compute ranking consensus across tasks (here: consensus ranking
+according to mean ranks across tasks)
-
-```r
+``` r
# See ?relation_consensus for different methods to derive consensus ranking
meanRanks <- ranking%>%consensus(method = "euclidean")
meanRanks # note that there may be ties (i.e. some algorithms have identical mean rank)
```
-Generate report as above, but with additional specification of consensus ranking
-
+Generate report as above, but with additional specification of consensus
+ranking
-```r
+``` r
ranking_bootstrapped %>%
report(consensus = meanRanks,
title = "multiTaskChallengeExample",
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex"#LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
)
```
-The consensus ranking is given according to mean ranks across tasks if method="euclidean" where in case of ties (equal ranks for multiple algorithms) the average rank is used, i.e. ties.method="average".
+The consensus ranking is given according to mean ranks across tasks if
+method=“euclidean” where in case of ties (equal ranks for multiple
+algorithms) the average rank is used, i.e. ties.method=“average”.
# Troubleshooting
-In this section we provide an overview of issues that the users reported and how they were solved.
+In this section we provide an overview of issues that the users reported
+and how they were solved.
## Issues related to RStudio
### Issue: Rtools is missing
While trying to install the current version of the repository:
-
-```r
+``` r
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The following warning showed up in the output:
-
-```r
+``` r
WARNING: Rtools is required to build R packages, but is not currently installed.
```
-Therefore, Rtools was installed via a separate executable: <https://cran.r-project.org/bin/windows/Rtools/> and the warning disappeared.
+Therefore, Rtools was installed via a separate executable:
+<https://cran.r-project.org/bin/windows/Rtools/> and the warning
+disappeared.
#### Solution:
-Actually there is no need of installing Rtools, it is not really used in the toolkit. Insted, choose not to install it when it is asked. See comment in the installation section:
+Actually there is no need of installing Rtools, it is not really used in
+the toolkit. Insted, choose not to install it when it is asked. See
+comment in the installation section:
-“If you are asked whether you want to update installed packages and you type “a” for all, you might need administrator rights to update R core packages. You can also try to type “n” for updating no packages. If you are asked “Do you want to install from sources the packages which need compilation? (Yes/no/cancel)”, you can safely type “no”.”
+“If you are asked whether you want to update installed packages and you
+type “a” for all, you might need administrator rights to update R core
+packages. You can also try to type “n” for updating no packages. If you
+are asked “Do you want to install from sources the packages which need
+compilation? (Yes/no/cancel)”, you can safely type “no”.”
### Issue: Package versions are mismatching
Installing the current version of the tool from GitHub failed.
The error message was:
-
-```r
+``` r
byte-compile and prepare package for lazy loading
Error: (converted from warning) package 'ggplot2' was built under R version 3.6.3
Execution halted
ERROR: lazy loading failed for package 'challengeR'
* removing 'C:/Users/.../Documents/R/win-library/3.6/challengeR'
* restoring previous 'C:/Users/.../Documents/R/win-library/3.6/challengeR'
Error: Failed to install 'challengeR' from GitHub:
(converted from warning) installation of package 'C:/Users/.../AppData/Local/Temp/Rtmp615qmV/file4fd419555eb4/challengeR_0.3.1.tar.gz' had non-zero exit status
```
-The problem was that some of the packages that were built under R3.6.1 had been updated, but the current installed version was still R3.6.1.
+The problem was that some of the packages that were built under R3.6.1
+had been updated, but the current installed version was still R3.6.1.
#### Solution:
-The solution was to update R3.6.1 to R3.6.3. Another way would have been to reset the single packages to the versions built under R3.6.1.
+The solution was to update R3.6.1 to R3.6.3. Another way would have been
+to reset the single packages to the versions built under R3.6.1.
### Issue: Package is missing
Installing the current version of the tool from GitHub failed.
-
-```r
+``` r
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The error message was:
-
-```r
+``` r
Error: .onLoad failed in loadNamespace() for 'pkgload', details:
call: loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]])
error: there is no package called ‘backports’
```
-The problem was that the packages 'backports' had not been installed.
+The problem was that the packages ‘backports’ had not been installed.
#### Solution:
-The solution was to install 'backports' manually.
+The solution was to install ‘backports’ manually.
-
-```r
+``` r
install.packages("backports")
```
### Issue: Packages are not detected correctly
-While trying to install the package after running the following commands:
-
+While trying to install the package after running the following
+commands:
-```r
+``` r
if (!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("Rgraphviz", dependencies = TRUE)
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The error message was:
-
-```r
+``` r
ERROR:
1: In file(con, "r") :
URL 'https://bioconductor.org/config.yaml': status was 'SSL connect error'
2: packages ‘BiocVersion’, ‘Rgraphviz’ are not available (for R version 3.6.1)
```
#### Solution:
The solution was to restart RStudio.
## Issues related to MiKTeX
### Issue: Missing packages
-While generating the PDF with MiKTeX (2.9), the following error showed up:
+While generating the PDF with MiKTeX (2.9), the following error showed
+up:
-
-```r
+``` r
fatal pdflatex - gui framework cannot be initialized
```
There is an issue with installing missing packages in LaTeX.
##### Solution:
-Open your MiKTeX Console --\> Settings, select "Always install missing packages on-the-fly". Then generate the report. Once the report is generated, you can reset the settings to your preferred ones.
+Open your MiKTeX Console –> Settings, select “Always install missing
+packages on-the-fly”. Then generate the report. Once the report is
+generated, you can reset the settings to your preferred ones.
### Issue: Unable to generate report
While generating the PDF with MiKTeX (2.9):
-
-```r
+``` r
ranking_bootstrapped %>%
report(title = "singleTaskChallengeExample", # used for the title of the report
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex", #LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean = TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
-
```
The following error showed up:
-
-```r
+``` r
output file: filename.knit.md
"C:/Program Files/RStudio/bin/pandoc/pandoc" +RTS -K512m -RTS filename.utf8.md --to latex --from markdown+autolink_bare_uris+tex_math_single_backslash --output filename.tex --self-contained --number-sections --highlight-style tango --pdf-engine pdflatex --variable graphics --lua-filter "C:/Users/adm/Documents/R/win-library/3.6/rmarkdown/rmd/lua/pagebreak.lua" --lua-filter "C:/Users/adm/Documents/R/win-library/3.6/rmarkdown/rmd/lua/latex-div.lua" --variable "geometry:margin=1in"
Error: LaTeX failed to compile filename.tex. See https://yihui.org/tinytex/r/#debugging for debugging tips.
Warning message:
In system2(..., stdout = if (use_file_stdout()) f1 else FALSE, stderr = f2) :
'"pdflatex"' not found
```
#### Solution:
The solution was to restart RStudio.
# Changes
+#### Version 1.0.5
+
+- Ensure reproducibility with parallel bootstrapping
+ ([T29361](https://phabricator.mitk.org/T29361))
+
#### Version 1.0.4
-- Fix NaN values cause error ([T28746](https://phabricator.mitk.org/T28746))
-- Fix Bars and dots don't match in podium plot ([T29167](https://phabricator.mitk.org/T29167))
-- Fix y-axis of blob plots always scaled to 5 ([T28966](https://phabricator.mitk.org/T28966))
+- Fix NaN values cause error
+ ([T28746](https://phabricator.mitk.org/T28746))
+- Fix Bars and dots don’t match in podium plot
+ ([T29167](https://phabricator.mitk.org/T29167))
+- Fix y-axis of blob plots always scaled to 5
+ ([T28966](https://phabricator.mitk.org/T28966))
#### Version 1.0.3
-- Fix ggplot warning in various places of the report ([T28710](https://phabricator.mitk.org/T28710))
+- Fix ggplot warning in various places of the report
+ ([T28710](https://phabricator.mitk.org/T28710))
#### Version 1.0.2
-- Fix error when all metric values are the same ([T28453](https://phabricator.mitk.org/T28453))
-- Fix wrong number of algorithms shown in report summary ([T28465](https://phabricator.mitk.org/T28465))
+- Fix error when all metric values are the same
+ ([T28453](https://phabricator.mitk.org/T28453))
+- Fix wrong number of algorithms shown in report summary
+ ([T28465](https://phabricator.mitk.org/T28465))
#### Version 1.0.1
-- Fix error raised in case there are more tasks than algorithms contained in the dataset ([T28193](https://phabricator.mitk.org/T28193))
-- Drop restriction that at least three algorithms are required for bootstrapping ([T28194](https://phabricator.mitk.org/T28194))
-- Avoid blank pages in PDF report when bootstrapping is disabled ([T28201](https://phabricator.mitk.org/T28201))
-- Handle tasks having only one case for bootstrapping ([T28202](https://phabricator.mitk.org/T28202))
+- Fix error raised in case there are more tasks than algorithms
+ contained in the dataset
+ ([T28193](https://phabricator.mitk.org/T28193))
+- Drop restriction that at least three algorithms are required for
+ bootstrapping ([T28194](https://phabricator.mitk.org/T28194))
+- Avoid blank pages in PDF report when bootstrapping is disabled
+ ([T28201](https://phabricator.mitk.org/T28201))
+- Handle tasks having only one case for bootstrapping
+ ([T28202](https://phabricator.mitk.org/T28202))
- Update citation ([T28210](https://phabricator.mitk.org/T28210))
#### Version 1.0.0
- Revision of the underlying data structure
- Roxygen documentation for main functionality
-- Vignettes for quickstart and overview of available plots demonstrating the use of their corresponding plot functions
-- Introduction of unit tests (package coverage \>70%)
+- Vignettes for quickstart and overview of available plots
+ demonstrating the use of their corresponding plot functions
+- Introduction of unit tests (package coverage >70%)
- Troubleshooting section covering potential issues during setup
-- Finally: Extensive bug fixes and improvements (for a complete overview please check the [Phabricator tasks](https://phabricator.mitk.org/search/query/vtj0qOqH5qL6/))
+- Finally: Extensive bug fixes and improvements (for a complete
+ overview please check the [Phabricator
+ tasks](https://phabricator.mitk.org/search/query/vtj0qOqH5qL6/))
#### Version 0.3.3
-- Force line break to avoid that authors exceed the page in generated PDF reports
+- Force line break to avoid that authors exceed the page in generated
+ PDF reports
#### Version 0.3.2
- Correct names of authors
#### Version 0.3.1
- Refactoring
#### Version 0.3.0
- Major bug fix release
#### Version 0.2.5
- Bug fixes
#### Version 0.2.4
- Automatic insertion of missings
#### Version 0.2.3
- Bug fixes
-- Reports for subsets (top list) of algorithms: Use e.g. `subset(ranking_bootstrapped, top=3) %>% report(...)` (or `subset(ranking, top=3) %>% report(...)` for report without bootstrap results) to only show the top 3 algorithms according to the chosen ranking methods, where `ranking_bootstrapped` and `ranking` objects as defined in the example. Line plot for ranking robustness can be used to check whether algorithms performing well in other ranking methods are excluded. Bootstrapping still takes entire uncertainty into account. Podium plot and ranking heatmap neglect excluded algorithms. Only available for single-task challenges (for multi-task challenges not sensible because each task would contain a different set of algorithms).
-- Reports for subsets of tasks: Use e.g. `subset(ranking_bootstrapped, tasks=c("task1", "task2","task3")) %>% report(...)` to restrict report to tasks "task1", "task2","task3. You may want to recompute the consensus ranking before using `meanRanks=subset(ranking, tasks=c("task1", "task2", "task3"))%>%consensus(method = "euclidean")`
+- Reports for subsets (top list) of algorithms: Use
+ e.g. `subset(ranking_bootstrapped, top=3) %>% report(...)` (or
+ `subset(ranking, top=3) %>% report(...)` for report without
+ bootstrap results) to only show the top 3 algorithms according to
+ the chosen ranking methods, where `ranking_bootstrapped` and
+ `ranking` objects as defined in the example. Line plot for ranking
+ robustness can be used to check whether algorithms performing well
+ in other ranking methods are excluded. Bootstrapping still takes
+ entire uncertainty into account. Podium plot and ranking heatmap
+ neglect excluded algorithms. Only available for single-task
+ challenges (for multi-task challenges not sensible because each task
+ would contain a different set of algorithms).
+- Reports for subsets of tasks: Use
+ e.g. `subset(ranking_bootstrapped, tasks=c("task1", "task2","task3")) %>% report(...)`
+ to restrict report to tasks “task1”, “task2”,"task3. You may want to
+ recompute the consensus ranking before using
+ `meanRanks=subset(ranking, tasks=c("task1", "task2", "task3"))%>%consensus(method = "euclidean")`
#### Version 0.2.1
-- Introduction in reports now mentions e.g. ranking method, number of test cases,...
-- Function `subset()` allows selection of tasks after bootstrapping, e.g. `subset(ranking_bootstrapped,1:3)`
-- `report()` functions gain argument `colors` (default: `default_colors`). Change e.g. to `colors=viridisLite::inferno` which "is designed in such a way that it will analytically be perfectly perceptually-uniform, both in regular form and also when converted to black-and-white. It is also designed to be perceived by readers with the most common form of color blindness." See package `viridis` for further similar functions.
+- Introduction in reports now mentions e.g. ranking method, number of
+ test cases,…
+- Function `subset()` allows selection of tasks after bootstrapping,
+ e.g. `subset(ranking_bootstrapped,1:3)`
+- `report()` functions gain argument `colors` (default:
+ `default_colors`). Change e.g. to `colors=viridisLite::inferno`
+ which “is designed in such a way that it will analytically be
+ perfectly perceptually-uniform, both in regular form and also when
+ converted to black-and-white. It is also designed to be perceived by
+ readers with the most common form of color blindness.” See package
+ `viridis` for further similar functions.
#### Version 0.2.0
-- Improved layout in case of many algorithms and tasks (while probably still not perfect)
+- Improved layout in case of many algorithms and tasks (while probably
+ still not perfect)
- Consistent coloring of algorithms across figures
-- `report()` function can be applied to ranked object before bootstrapping (and thus excluding figures based on bootstrapping), i.e. in the example `ranking %>% report(...)`
+- `report()` function can be applied to ranked object before
+ bootstrapping (and thus excluding figures based on bootstrapping),
+ i.e. in the example `ranking %>% report(...)`
- bug fixes
# Team
-The developer team includes members from both division of Computer Assisted Medical Interventions (CAMI) and Biostatistics at the German Cancer Research Center (DKFZ):
+The developer team includes members from both division of Intelligent
+Medical Systems (IMSY) and Biostatistics at the German Cancer Research
+Center (DKFZ):
- Manuel Wiesenfarth
- Annette Kopp-Schneider
- Annika Reinke
- Matthias Eisenmann
- Laura Aguilera Saiz
- Elise Récéjac
- Lena Maier-Hein
+- Ali Emre Kavur
# Reference
-Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods and open-source toolkit for analyzing and visualizing challenge results. *Sci Rep* **11**, 2369 (2021). <https://doi.org/10.1038/s41598-021-82017-6>
+Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera
+Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods
+and open-source toolkit for analyzing and visualizing challenge results.
+*Sci Rep* **11**, 2369 (2021).
+<https://doi.org/10.1038/s41598-021-82017-6>
-<img src="DKFZ_Logo.png" width="300px"/> <img src="HIP_Logo.png" width="340px"/>
+</br> <img src="Helmholtz_Imaging_Logo.svg" height="70px" /> </br></br>
+<img src="DKFZ_Logo.png" height="100px" />
diff --git a/Readme.Rmd b/Readme.Rmd
index 73d3051..8c547e8 100644
--- a/Readme.Rmd
+++ b/Readme.Rmd
@@ -1,533 +1,539 @@
---
title: "Methods and open-source toolkit for analyzing and visualizing challenge results"
output:
github_document:
toc: yes
toc_depth: '1'
html_document:
toc: yes
toc_depth: '1'
pdf_document:
toc: yes
toc_depth: '1'
editor_options:
chunk_output_type: console
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
# fig.path = "README-",
fig.width = 9,
fig.height = 5,
width=160
)
```
# Introduction
The current framework is a tool for analyzing and visualizing challenge results in the field of biomedical image analysis and beyond.
Biomedical challenges have become the de facto standard for benchmarking biomedical image analysis algorithms. While the number of challenges is steadily increasing, surprisingly little effort has been invested in ensuring high quality design, execution and reporting for these international competitions. Specifically, results analysis and visualization in the event of uncertainties have been given almost no attention in the literature.
Given these shortcomings, the current framework aims to enable fast and wide adoption of comprehensively analyzing and visualizing the results of single-task and multi-task challenges. This approach offers an intuitive way to gain important insights into the relative and absolute performance of algorithms, which cannot be revealed by commonly applied visualization techniques.
# Installation
Requires R version >= 3.5.2 (https://www.r-project.org).
Further, a recent version of Pandoc (>= 1.12.3) is required. RStudio (https://rstudio.com) automatically includes this so you do not need to download Pandoc if you plan to use rmarkdown from the RStudio IDE, otherwise you’ll need to install Pandoc for your platform (https://pandoc.org/installing.html). Finally, if you want to generate a PDF report you will need to have LaTeX installed (e.g. MiKTeX, MacTeX or TinyTeX).
To get the latest released version (master branch) of the R package from GitHub:
```{r, eval=F,R.options,}
if (!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("Rgraphviz", dependencies = TRUE)
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
If you are asked whether you want to update installed packages and you type "a" for all, you might need administrator permissions to update R core packages. You can also try to type "n" for updating no packages. If you are asked "Do you want to install from sources the packages which need compilation? (Yes/no/cancel)", you can safely type "no".
If you get *warning* messages (in contrast to *error* messages), these might not be problematic and you can try to proceed. If you encounter errors during the setup, looking into the "Troubleshooting" section might be worth it.
For Linux users: Some system libraries might be missing. Check the output in the R console for further hints carefully during the installation of packages.
# Terms of use
Copyright (c) German Cancer Research Center (DKFZ). All rights reserved.
challengeR is available under license GPLv2 or any later version.
If you use this software for a publication, please cite:
Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods and open-source toolkit for analyzing and visualizing challenge results. *Sci Rep* **11**, 2369 (2021). https://doi.org/10.1038/s41598-021-82017-6
# Usage
Each of the following steps has to be run to generate the report: (1) Load package, (2) load data, (3) perform ranking, (4) perform bootstrapping and (5) generation of the report
You can find R scripts for quickstart in the directory "vignettes". An overview of all available plots is provided in the "Visualizations" vignette demonstrating the use of their corresponding plot functions as well.
Here, we provide a step-by-step guide that leads you to your final report.
## 1. Load package
Load package
```{r, eval=F}
library(challengeR)
```
## 2. Load data
### Data requirements
Data requires the following *columns*:
* *task identifier* in case of multi-task challenges (string or numeric)
* *test case identifier* (string or numeric)
* *algorithm identifier* (string or numeric)
* *metric value* (numeric)
In case of missing metric values, a missing observation has to be provided (either as blank field or "NA").
For example, in a challenge with 2 tasks, 2 test cases and 2 algorithms, where in task "T2", test case "case2", algorithm "A2" didn't give a prediction (and thus NA or a blank field for missing value is inserted), the data set might look like this:
```{r, eval=T, echo=F,results='asis'}
set.seed(1)
a <- cbind(expand.grid(Task=paste0("T",1:2),TestCase=paste0("case",1:2),Algorithm=paste0("A",1:2)),MetricValue=round(c(runif(7,0,1),NA),3))
print(knitr::kable(a[order(a$Task,a$TestCase,a$Algorithm),],row.names=F))
```
### 2.1 Load data from file
If you have assessment data at hand stored in a csv file (if you want to use simulated data, skip the following code line) use
```{r, eval=F, echo=T}
data_matrix <- read.csv(file.choose()) # type ?read.csv for help
```
This allows to choose a file interactively, otherwise replace *file.choose()* by the file path (in style "/path/to/dataset.csv") in quotation marks.
### 2.2 Simulate data
In the following, simulated data is generated *instead* for illustration purposes (skip the following code chunk if you have already loaded data). The data is also stored as "inst/extdata/data_matrix.csv" in the repository.
```{r, eval=F, echo=T}
if (!requireNamespace("permute", quietly = TRUE)) install.packages("permute")
n <- 50
set.seed(4)
strip <- runif(n,.9,1)
c_ideal <- cbind(task="c_ideal",
rbind(
data.frame(alg_name="A1",value=runif(n,.9,1),case=1:n),
data.frame(alg_name="A2",value=runif(n,.8,.89),case=1:n),
data.frame(alg_name="A3",value=runif(n,.7,.79),case=1:n),
data.frame(alg_name="A4",value=runif(n,.6,.69),case=1:n),
data.frame(alg_name="A5",value=runif(n,.5,.59),case=1:n)
))
set.seed(1)
c_random <- data.frame(task="c_random",
alg_name=factor(paste0("A",rep(1:5,each=n))),
value=plogis(rnorm(5*n,1.5,1)),case=rep(1:n,times=5)
)
strip2 <- seq(.8,1,length.out=5)
a <- permute::allPerms(1:5)
c_worstcase <- data.frame(task="c_worstcase",
alg_name=c(t(a)),
value=rep(strip2,nrow(a)),
case=rep(1:nrow(a),each=5)
)
c_worstcase <- rbind(c_worstcase,
data.frame(task="c_worstcase",alg_name=1:5,value=strip2,case=max(c_worstcase$case)+1)
)
c_worstcase$alg_name <- factor(c_worstcase$alg_name,labels=paste0("A",1:5))
data_matrix <- rbind(c_ideal, c_random, c_worstcase)
```
## 3. Perform ranking
### 3.1 Define challenge object
Code differs slightly for single- and multi-task challenges.
In case of a single-task challenge use
```{r, eval=F, echo=T}
# Use only task "c_random" in object data_matrix
dataSubset <- subset(data_matrix, task=="c_random")
challenge <- as.challenge(dataSubset,
# Specify which column contains the algorithms,
# which column contains a test case identifier
# and which contains the metric value:
algorithm = "alg_name", case = "case", value = "value",
# Specify if small metric values are better
smallBetter = FALSE)
```
*Instead*, for a multi-task challenge use
```{r, eval=F, echo=T}
# Same as above but with 'by="task"' where variable "task" contains the task identifier
challenge <- as.challenge(data_matrix,
by = "task",
algorithm = "alg_name", case = "case", value = "value",
smallBetter = FALSE)
```
### 3.2 Configure ranking
Different ranking methods are available, choose one of them:
- for "aggregate-then-rank" use (here: take mean for aggregation)
```{r, eval=F, echo=T}
ranking <- challenge%>%aggregateThenRank(FUN = mean, # aggregation function,
# e.g. mean, median, min, max,
# or e.g. function(x) quantile(x, probs=0.05)
na.treat = 0, # either "na.rm" to remove missing data,
# set missings to numeric value (e.g. 0)
# or specify a function,
# e.g. function(x) min(x)
ties.method = "min" # a character string specifying
# how ties are treated, see ?base::rank
)
```
- *alternatively*, for "rank-then-aggregate" with arguments as above (here: take mean for aggregation)
```{r, eval=F, echo=T}
ranking <- challenge%>%rankThenAggregate(FUN = mean,
ties.method = "min"
)
```
- *alternatively*, for test-then-rank based on Wilcoxon signed rank test
```{r, eval=F, echo=T}
ranking <- challenge%>%testThenRank(alpha = 0.05, # significance level
p.adjust.method = "none", # method for adjustment for
# multiple testing, see ?p.adjust
na.treat = 0, # either "na.rm" to remove missing data,
# set missings to numeric value (e.g. 0)
# or specify a function, e.g. function(x) min(x)
ties.method = "min" # a character string specifying
# how ties are treated, see ?base::rank
)
```
## 4. Perform bootstrapping
Perform bootstrapping with 1000 bootstrap samples using one CPU
```{r, eval=F, echo=T}
-set.seed(1)
+set.seed(123, kind = "L'Ecuyer-CMRG")
ranking_bootstrapped <- ranking%>%bootstrap(nboot = 1000)
```
If you want to use multiple CPUs (here: 8 CPUs), use
```{r, eval=F, echo=T}
library(doParallel)
+library(doRNG)
registerDoParallel(cores = 8)
-set.seed(1)
+registerDoRNG(123)
ranking_bootstrapped <- ranking%>%bootstrap(nboot = 1000, parallel = TRUE, progress = "none")
stopImplicitCluster()
```
## 5. Generate the report
Generate report in PDF, HTML or DOCX format. Code differs slightly for single- and multi-task challenges.
### 5.1 For single-task challenges
```{r, eval=F, echo=T}
ranking_bootstrapped %>%
report(title = "singleTaskChallengeExample", # used for the title of the report
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex", #LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean = TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
```
Argument *file* allows for specifying the output file path as well, otherwise the working directory is used.
If file is specified but does not have a file extension, an extension will be automatically added according to the output format given in *format*.
Using argument *clean=FALSE* allows to retain intermediate files, such as separate files for each figure.
If argument "file" is omitted, the report is created in a temporary folder with file name "report".
### 5.2 For multi-task challenges
Same as for single-task challenges, but additionally consensus ranking (rank aggregation across tasks) has to be given.
Compute ranking consensus across tasks (here: consensus ranking according to mean ranks across tasks)
```{r, eval=F, echo=T}
# See ?relation_consensus for different methods to derive consensus ranking
meanRanks <- ranking%>%consensus(method = "euclidean")
meanRanks # note that there may be ties (i.e. some algorithms have identical mean rank)
```
Generate report as above, but with additional specification of consensus ranking
```{r, eval=F, echo=T}
ranking_bootstrapped %>%
report(consensus = meanRanks,
title = "multiTaskChallengeExample",
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex"#LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
)
```
The consensus ranking is given according to mean ranks across tasks if method="euclidean" where in case of ties (equal ranks for multiple algorithms) the average rank is used, i.e. ties.method="average".
# Troubleshooting
In this section we provide an overview of issues that the users reported and how they were solved.
## Issues related to RStudio
### Issue: Rtools is missing
While trying to install the current version of the repository:
```{r, eval=F, echo=T}
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The following warning showed up in the output:
```{r, eval=F, echo=T}
WARNING: Rtools is required to build R packages, but is not currently installed.
```
Therefore, Rtools was installed via a separate executable: https://cran.r-project.org/bin/windows/Rtools/ and the warning disappeared.
#### Solution:
Actually there is no need of installing Rtools, it is not really used in the toolkit. Insted, choose not to install it when it is asked. See comment in the installation section:
“If you are asked whether you want to update installed packages and you type “a” for all, you might need administrator rights to update R core packages. You can also try to type “n” for updating no packages. If you are asked “Do you want to install from sources the packages which need compilation? (Yes/no/cancel)”, you can safely type “no”.”
### Issue: Package versions are mismatching
Installing the current version of the tool from GitHub failed.
The error message was:
```{r, eval=F, echo=T}
byte-compile and prepare package for lazy loading
Error: (converted from warning) package 'ggplot2' was built under R version 3.6.3
Execution halted
ERROR: lazy loading failed for package 'challengeR'
* removing 'C:/Users/.../Documents/R/win-library/3.6/challengeR'
* restoring previous 'C:/Users/.../Documents/R/win-library/3.6/challengeR'
Error: Failed to install 'challengeR' from GitHub:
(converted from warning) installation of package 'C:/Users/.../AppData/Local/Temp/Rtmp615qmV/file4fd419555eb4/challengeR_0.3.1.tar.gz' had non-zero exit status
```
The problem was that some of the packages that were built under R3.6.1 had been updated, but the current installed version was still R3.6.1.
#### Solution:
The solution was to update R3.6.1 to R3.6.3. Another way would have been to reset the single packages to the versions built under R3.6.1.
### Issue: Package is missing
Installing the current version of the tool from GitHub failed.
```{r, eval=F, echo=T}
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The error message was:
```{r, eval=F, echo=T}
Error: .onLoad failed in loadNamespace() for 'pkgload', details:
call: loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]])
error: there is no package called ‘backports’
```
The problem was that the packages 'backports' had not been installed.
#### Solution:
The solution was to install 'backports' manually.
```{r, eval=F, echo=T}
install.packages("backports")
```
### Issue: Packages are not detected correctly
While trying to install the package after running the following commands:
```{r, eval=F, echo=T}
if (!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("Rgraphviz", dependencies = TRUE)
devtools::install_github("wiesenfa/challengeR", dependencies = TRUE)
```
The error message was:
```{r, eval=F, echo=T}
ERROR:
1: In file(con, "r") :
URL 'https://bioconductor.org/config.yaml': status was 'SSL connect error'
2: packages ‘BiocVersion’, ‘Rgraphviz’ are not available (for R version 3.6.1)
```
#### Solution:
The solution was to restart RStudio.
## Issues related to MiKTeX
### Issue: Missing packages
While generating the PDF with MiKTeX (2.9), the following error showed up:
```{r, eval=F, echo=T}
fatal pdflatex - gui framework cannot be initialized
```
There is an issue with installing missing packages in LaTeX.
##### Solution:
Open your MiKTeX Console --> Settings, select "Always install missing packages on-the-fly". Then generate the report. Once the report is generated, you can reset the settings to your preferred ones.
### Issue: Unable to generate report
While generating the PDF with MiKTeX (2.9):
```{r, eval=F, echo=T}
ranking_bootstrapped %>%
report(title = "singleTaskChallengeExample", # used for the title of the report
file = "filename",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine = "pdflatex", #LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean = TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
```
The following error showed up:
```{r, eval=F, echo=T}
output file: filename.knit.md
"C:/Program Files/RStudio/bin/pandoc/pandoc" +RTS -K512m -RTS filename.utf8.md --to latex --from markdown+autolink_bare_uris+tex_math_single_backslash --output filename.tex --self-contained --number-sections --highlight-style tango --pdf-engine pdflatex --variable graphics --lua-filter "C:/Users/adm/Documents/R/win-library/3.6/rmarkdown/rmd/lua/pagebreak.lua" --lua-filter "C:/Users/adm/Documents/R/win-library/3.6/rmarkdown/rmd/lua/latex-div.lua" --variable "geometry:margin=1in"
Error: LaTeX failed to compile filename.tex. See https://yihui.org/tinytex/r/#debugging for debugging tips.
Warning message:
In system2(..., stdout = if (use_file_stdout()) f1 else FALSE, stderr = f2) :
'"pdflatex"' not found
```
#### Solution:
The solution was to restart RStudio.
# Changes
+#### Version 1.0.5
+
+- Ensure reproducibility with parallel bootstrapping ([T29361](https://phabricator.mitk.org/T29361))
+
#### Version 1.0.4
- Fix NaN values cause error ([T28746](https://phabricator.mitk.org/T28746))
- Fix Bars and dots don't match in podium plot ([T29167](https://phabricator.mitk.org/T29167))
- Fix y-axis of blob plots always scaled to 5 ([T28966](https://phabricator.mitk.org/T28966))
#### Version 1.0.3
- Fix ggplot warning in various places of the report ([T28710](https://phabricator.mitk.org/T28710))
#### Version 1.0.2
- Fix error when all metric values are the same ([T28453](https://phabricator.mitk.org/T28453))
- Fix wrong number of algorithms shown in report summary ([T28465](https://phabricator.mitk.org/T28465))
#### Version 1.0.1
- Fix error raised in case there are more tasks than algorithms contained in the dataset ([T28193](https://phabricator.mitk.org/T28193))
- Drop restriction that at least three algorithms are required for bootstrapping ([T28194](https://phabricator.mitk.org/T28194))
- Avoid blank pages in PDF report when bootstrapping is disabled ([T28201](https://phabricator.mitk.org/T28201))
- Handle tasks having only one case for bootstrapping ([T28202](https://phabricator.mitk.org/T28202))
- Update citation ([T28210](https://phabricator.mitk.org/T28210))
#### Version 1.0.0
- Revision of the underlying data structure
- Roxygen documentation for main functionality
- Vignettes for quickstart and overview of available plots demonstrating the use of their corresponding plot functions
- Introduction of unit tests (package coverage >70%)
- Troubleshooting section covering potential issues during setup
- Finally: Extensive bug fixes and improvements (for a complete overview please check the [Phabricator tasks](https://phabricator.mitk.org/search/query/vtj0qOqH5qL6/))
-
#### Version 0.3.3
- Force line break to avoid that authors exceed the page in generated PDF reports
#### Version 0.3.2
- Correct names of authors
#### Version 0.3.1
- Refactoring
#### Version 0.3.0
- Major bug fix release
#### Version 0.2.5
- Bug fixes
-
#### Version 0.2.4
- Automatic insertion of missings
#### Version 0.2.3
- Bug fixes
- Reports for subsets (top list) of algorithms: Use e.g. `subset(ranking_bootstrapped, top=3) %>% report(...)` (or `subset(ranking, top=3) %>% report(...)` for report without bootstrap results) to only show the top 3 algorithms according to the chosen ranking methods, where `ranking_bootstrapped` and `ranking` objects as defined in the example. Line plot for ranking robustness can be used to check whether algorithms performing well in other ranking methods are excluded. Bootstrapping still takes entire uncertainty into account. Podium plot and ranking heatmap neglect excluded algorithms. Only available for single-task challenges (for multi-task challenges not sensible because each task would contain a different set of algorithms).
- Reports for subsets of tasks: Use e.g. `subset(ranking_bootstrapped, tasks=c("task1", "task2","task3")) %>% report(...)` to restrict report to tasks "task1", "task2","task3. You may want to recompute the consensus ranking before using `meanRanks=subset(ranking, tasks=c("task1", "task2", "task3"))%>%consensus(method = "euclidean")`
#### Version 0.2.1
- Introduction in reports now mentions e.g. ranking method, number of test cases,...
- Function `subset()` allows selection of tasks after bootstrapping, e.g. `subset(ranking_bootstrapped,1:3)`
- `report()` functions gain argument `colors` (default: `default_colors`). Change e.g. to `colors=viridisLite::inferno` which "is designed in such a way that it will analytically be perfectly perceptually-uniform, both in regular form and also when converted to black-and-white. It is also designed to be perceived by readers with the most common form of color blindness." See package `viridis` for further similar functions.
#### Version 0.2.0
- Improved layout in case of many algorithms and tasks (while probably still not perfect)
- Consistent coloring of algorithms across figures
- `report()` function can be applied to ranked object before bootstrapping (and thus excluding figures based on bootstrapping), i.e. in the example `ranking %>% report(...)`
- bug fixes
# Team
-The developer team includes members from both division of Computer Assisted Medical Interventions (CAMI) and Biostatistics at the German Cancer Research Center (DKFZ):
+The developer team includes members from both division of Intelligent Medical Systems (IMSY) and Biostatistics at the German Cancer Research Center (DKFZ):
- Manuel Wiesenfarth
- Annette Kopp-Schneider
- Annika Reinke
- Matthias Eisenmann
- Laura Aguilera Saiz
- Elise Récéjac
- Lena Maier-Hein
+- Ali Emre Kavur
# Reference
Wiesenfarth, M., Reinke, A., Landman, B.A., Eisenmann, M., Aguilera Saiz, L., Cardoso, M.J., Maier-Hein, L. and Kopp-Schneider, A. Methods and open-source toolkit for analyzing and visualizing challenge results. *Sci Rep* **11**, 2369 (2021). https://doi.org/10.1038/s41598-021-82017-6
-<img src="DKFZ_Logo.png" width="300px" />
-<img src="HIP_Logo.png" width="340px" />
+</br>
+<img src="Helmholtz_Imaging_Logo.svg" height="70px" />
+</br></br>
+<img src="DKFZ_Logo.png" height="100px" />
diff --git a/tests/testthat/test-bootstrap.R b/tests/testthat/test-bootstrap.R
index 50cdcfb..9524e15 100644
--- a/tests/testthat/test-bootstrap.R
+++ b/tests/testthat/test-bootstrap.R
@@ -1,80 +1,117 @@
-test_that("Single task bootstrapping with 1 test case stopped with message", {
+test_that("single-task bootstrapping with 1 test case stopped with message", {
dataTask1 <- cbind(task="T1",
rbind(
data.frame(algo="A1", value=0.8, case="C1"),
data.frame(algo="A2", value=0.6, case="C1")
))
challenge <- as.challenge(dataTask1, algorithm="algo", case="case", value="value", smallBetter=FALSE)
ranking <- challenge%>%aggregateThenRank(FUN=median, ties.method="min")
set.seed(1)
-
-
expect_error(rankingBootstrapped <- ranking%>%bootstrap(nboot=10),
"Only 1 test case included. Bootstrapping with 1 test case not sensible.", fixed = TRUE)
})
-test_that("Multi task bootstrapping, all tasks with 1 test case stopped with message", {
+test_that("multi-task bootstrapping, all tasks with 1 test case stopped with message", {
dataTask1 <- cbind(task="T1",
rbind(
data.frame(algo="A1", value=0.8, case="C1"),
data.frame(algo="A2", value=0.6, case="C1")
))
dataTask2 <- cbind(task="T2",
rbind(
data.frame(algo="A1", value=0.2, case="C1"),
data.frame(algo="A2", value=0.3, case="C1")
))
dataTask3 <- cbind(task="T3",
rbind(
data.frame(algo="A1", value=0.1, case="C1"),
data.frame(algo="A2", value=0.8, case="C1")
))
-
+
data <- rbind(dataTask1, dataTask2, dataTask3)
-
+
challenge <- as.challenge(data, by="task", algorithm="algo", case="case", value="value", smallBetter=FALSE)
-
+
ranking <- challenge%>%aggregateThenRank(FUN=median, ties.method="min")
-
+
set.seed(1)
expect_error(rankingBootstrapped <- ranking%>%bootstrap(nboot=10),
"All tasks only contained 1 test case. Bootstrapping with 1 test case not sensible.", fixed = TRUE)
})
-test_that("Multi task bootstrapping, only one task with >1 test case continued with message", {
+test_that("multi-task bootstrapping, only one task with >1 test case continued with message", {
dataTask1 <- cbind(task="T1",
rbind(
data.frame(algo="A1", value=0.8, case="C1"),
data.frame(algo="A2", value=0.6, case="C1")
))
dataTask2 <- cbind(task="T2",
rbind(
data.frame(algo="A1", value=0.2, case="C1"),
data.frame(algo="A2", value=0.3, case="C1"),
data.frame(algo="A1", value=0.2, case="C2"),
data.frame(algo="A2", value=0.3, case="C2")
))
dataTask3 <- cbind(task="T3",
rbind(
data.frame(algo="A1", value=0.1, case="C1"),
data.frame(algo="A2", value=0.8, case="C1")
))
-
+
data <- rbind(dataTask1, dataTask2, dataTask3)
-
+
challenge <- as.challenge(data, by="task", algorithm="algo", case="case", value="value", smallBetter=FALSE)
-
+
ranking <- challenge%>%aggregateThenRank(FUN=median, ties.method="min")
-
+
set.seed(1)
expect_message(rankingBootstrapped <- ranking%>%bootstrap(nboot=3),
"Task(s) T1, T3 with only 1 test case excluded from bootstrapping.", fixed = TRUE)
})
+test_that("two sequential bootstrappings yield same results", {
+ data <- read.csv(system.file("extdata", "data_matrix.csv", package="challengeR", mustWork=TRUE))
+
+ challenge <- as.challenge(data, by="task", algorithm="alg_name", case="case", value="value", smallBetter=FALSE)
+
+ ranking <- challenge%>%rankThenAggregate(FUN=mean, ties.method="min")
+
+ set.seed(123, kind="L'Ecuyer-CMRG")
+ rankingBootstrapped1 <- ranking%>%bootstrap(nboot=10)
+
+ set.seed(123, kind="L'Ecuyer-CMRG")
+ rankingBootstrapped2 <- ranking%>%bootstrap(nboot=10)
+
+ expect_equal(rankingBootstrapped1, rankingBootstrapped2)
+})
+
+
+test_that("two parallel bootstrappings yield same results", {
+ data <- read.csv(system.file("extdata", "data_matrix.csv", package="challengeR", mustWork=TRUE))
+
+ challenge <- as.challenge(data, by="task", algorithm="alg_name", case="case", value="value", smallBetter=FALSE)
+
+ ranking <- challenge%>%rankThenAggregate(FUN=mean, ties.method="min")
+
+ library(doParallel)
+ library(doRNG)
+ numCores <- detectCores(logical=FALSE)
+ registerDoParallel(cores=numCores)
+
+ registerDoRNG(123)
+ rankingBootstrapped1 <- ranking%>%bootstrap(nboot=10, parallel=TRUE, progress="none")
+
+ registerDoRNG(123)
+ rankingBootstrapped2 <- ranking%>%bootstrap(nboot=10, parallel=TRUE, progress="none")
+
+ stopImplicitCluster()
+
+ expect_equal(rankingBootstrapped1, rankingBootstrapped2)
+})
diff --git a/vignettes/MultiTask_rank-then-aggregate.R b/vignettes/MultiTask_rank-then-aggregate.R
index 7d97424..89b119d 100644
--- a/vignettes/MultiTask_rank-then-aggregate.R
+++ b/vignettes/MultiTask_rank-then-aggregate.R
@@ -1,79 +1,80 @@
## Multitask, rank-then-aggregate ranking
## 1\. Load package
library(challengeR)
## 2\. Load data
if (!requireNamespace("permute", quietly = TRUE)) install.packages("permute")
n=50
set.seed(4)
strip=runif(n,.9,1)
c_ideal=cbind(task="c_ideal",
rbind(
data.frame(alg_name="A1",value=runif(n,.9,1),case=1:n),
data.frame(alg_name="A2",value=runif(n,.8,.89),case=1:n),
data.frame(alg_name="A3",value=runif(n,.7,.79),case=1:n),
data.frame(alg_name="A4",value=runif(n,.6,.69),case=1:n),
data.frame(alg_name="A5",value=runif(n,.5,.59),case=1:n)
))
set.seed(1)
c_random=data.frame(task="c_random",
alg_name=factor(paste0("A",rep(1:5,each=n))),
value=plogis(rnorm(5*n,1.5,1)),case=rep(1:n,times=5)
)
strip2=seq(.8,1,length.out=5)
a=permute::allPerms(1:5)
c_worstcase=data.frame(task="c_worstcase",
alg_name=c(t(a)),
value=rep(strip2,nrow(a)),
case=rep(1:nrow(a),each=5)
)
c_worstcase=rbind(c_worstcase,
data.frame(task="c_worstcase",alg_name=1:5,value=strip2,case=max(c_worstcase$case)+1)
)
c_worstcase$alg_name=factor(c_worstcase$alg_name,labels=paste0("A",1:5))
data_matrix=rbind(c_ideal, c_random, c_worstcase)
## 3 Perform ranking
### 3.1 Define challenge object
challenge=as.challenge(data_matrix,
by="task",
algorithm="alg_name", case="case", value="value",
smallBetter = FALSE)
### 3.2 Perform ranking
ranking=challenge%>%rankThenAggregate(FUN = mean,
ties.method = "min"
)
## 4\. Perform bootstrapping
library(doParallel)
-registerDoParallel(cores=8)
-set.seed(1)
-ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress = "none")
+library(doRNG)
+registerDoParallel(cores=8)
+registerDoRNG(1)
+ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress="none")
stopImplicitCluster()
## 5\. Generate the report
meanRanks=ranking%>%consensus(method = "euclidean")
meanRanks # note that there may be ties (i.e. some algorithms have identical mean rank)
ranking_bootstrapped %>%
report(consensus=meanRanks,
title="multiTaskChallengeExample",
file = "MultiTask_rank-then-aggregate",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine="pdflatex",#LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean=TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
diff --git a/vignettes/MultiTask_test-then-rank.R b/vignettes/MultiTask_test-then-rank.R
index 554823c..ee187f2 100644
--- a/vignettes/MultiTask_test-then-rank.R
+++ b/vignettes/MultiTask_test-then-rank.R
@@ -1,82 +1,83 @@
## Multi-task, test-then-rank based on Wilcoxon signed rank ranking
## 1\. Load package
library(challengeR)
## 2\. Load data
if (!requireNamespace("permute", quietly = TRUE)) install.packages("permute")
n=50
set.seed(4)
strip=runif(n,.9,1)
c_ideal=cbind(task="c_ideal",
rbind(
data.frame(alg_name="A1",value=runif(n,.9,1),case=1:n),
data.frame(alg_name="A2",value=runif(n,.8,.89),case=1:n),
data.frame(alg_name="A3",value=runif(n,.7,.79),case=1:n),
data.frame(alg_name="A4",value=runif(n,.6,.69),case=1:n),
data.frame(alg_name="A5",value=runif(n,.5,.59),case=1:n)
))
set.seed(1)
c_random=data.frame(task="c_random",
alg_name=factor(paste0("A",rep(1:5,each=n))),
value=plogis(rnorm(5*n,1.5,1)),case=rep(1:n,times=5)
)
strip2=seq(.8,1,length.out=5)
a=permute::allPerms(1:5)
c_worstcase=data.frame(task="c_worstcase",
alg_name=c(t(a)),
value=rep(strip2,nrow(a)),
case=rep(1:nrow(a),each=5)
)
c_worstcase=rbind(c_worstcase,
data.frame(task="c_worstcase",alg_name=1:5,value=strip2,case=max(c_worstcase$case)+1)
)
c_worstcase$alg_name=factor(c_worstcase$alg_name,labels=paste0("A",1:5))
data_matrix=rbind(c_ideal, c_random, c_worstcase)
## 3 Perform ranking
### 3.1 Define challenge object
challenge=as.challenge(data_matrix,
by="task",
algorithm="alg_name", case="case", value="value",
smallBetter = FALSE)
### 3.2 Perform ranking
#{r, eval=F, echo=T}
ranking=challenge%>%testThenRank(alpha=0.05,
p.adjust.method="none",
na.treat=0,
ties.method = "min"
)
## 4\. Perform bootstrapping
library(doParallel)
-registerDoParallel(cores=8)
-set.seed(1)
-ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress = "none")
+library(doRNG)
+registerDoParallel(cores=8)
+registerDoRNG(1)
+ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress="none")
stopImplicitCluster()
## 5\. Generate the report
meanRanks=ranking%>%consensus(method = "euclidean")
meanRanks # note that there may be ties (i.e. some algorithms have identical mean rank)
ranking_bootstrapped %>%
report(consensus=meanRanks,
title="multiTaskChallengeExample",
file = "MultiTask_test-then-rank",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine="pdflatex",#LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean=TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
diff --git a/vignettes/SingleTask_aggregate-then-rank.R b/vignettes/SingleTask_aggregate-then-rank.R
index c1004cd..5d56654 100644
--- a/vignettes/SingleTask_aggregate-then-rank.R
+++ b/vignettes/SingleTask_aggregate-then-rank.R
@@ -1,71 +1,72 @@
## Single task, aggregate-then-rank ranking
## 1\. Load package
library(challengeR)
## 2\. Load data
if (!requireNamespace("permute", quietly = TRUE)) install.packages("permute")
n=50
set.seed(4)
strip=runif(n,.9,1)
c_ideal=cbind(task="c_ideal",
rbind(
data.frame(alg_name="A1",value=runif(n,.9,1),case=1:n),
data.frame(alg_name="A2",value=runif(n,.8,.89),case=1:n),
data.frame(alg_name="A3",value=runif(n,.7,.79),case=1:n),
data.frame(alg_name="A4",value=runif(n,.6,.69),case=1:n),
data.frame(alg_name="A5",value=runif(n,.5,.59),case=1:n)
))
set.seed(1)
c_random=data.frame(task="c_random",
alg_name=factor(paste0("A",rep(1:5,each=n))),
value=plogis(rnorm(5*n,1.5,1)),case=rep(1:n,times=5)
)
strip2=seq(.8,1,length.out=5)
a=permute::allPerms(1:5)
c_worstcase=data.frame(task="c_worstcase",
alg_name=c(t(a)),
value=rep(strip2,nrow(a)),
case=rep(1:nrow(a),each=5)
)
c_worstcase=rbind(c_worstcase,
data.frame(task="c_worstcase",alg_name=1:5,value=strip2,case=max(c_worstcase$case)+1)
)
c_worstcase$alg_name=factor(c_worstcase$alg_name,labels=paste0("A",1:5))
data_matrix=rbind(c_ideal, c_random, c_worstcase)
## 3 Perform ranking
### 3.1 Define challenge object
dataSubset=subset(data_matrix, task=="c_random")
challenge=as.challenge(dataSubset, algorithm="alg_name", case="case", value="value", smallBetter = FALSE)
### 3.2 Perform ranking
ranking=challenge%>%aggregateThenRank(FUN = mean, na.treat=0, ties.method = "min")
## 4\. Perform bootstrapping
library(doParallel)
-registerDoParallel(cores=8)
-set.seed(1)
-ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress = "none")
+library(doRNG)
+registerDoParallel(cores=8)
+registerDoRNG(1)
+ranking_bootstrapped=ranking%>%bootstrap(nboot=1000, parallel=TRUE, progress="none")
stopImplicitCluster()
## 5\. Generate the report
ranking_bootstrapped %>%
report(title="singleTaskChallengeExample", # used for the title of the report
file = "SingleTask_aggregate-then-rank",
format = "PDF", # format can be "PDF", "HTML" or "Word"
latex_engine="pdflatex", #LaTeX engine for producing PDF output. Options are "pdflatex", "lualatex", and "xelatex"
clean=TRUE #optional. Using TRUE will clean intermediate files that are created during rendering.
)
diff --git a/vignettes/visualizations.Rmd b/vignettes/visualizations.Rmd
index 93c3796..5205c44 100644
--- a/vignettes/visualizations.Rmd
+++ b/vignettes/visualizations.Rmd
@@ -1,167 +1,167 @@
---
title: "Visualizations"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Visualizations}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(challengeR)
```
The package offers an intuitive way to gain important insights into the relative and absolute performance of algorithms. It enables you to generate a benchmarking report that contains visualizations and respective explanations. An overview of all available visualizations is provided on this page demonstrating the use of their corresponding plot functions. This might be of interest if you want to generate the plots separately (e.g. to apply other styles).
The provided plots are described in the following sections:
* Visualizing assessment data
* Visualizing ranking stability
* Visualizing cross-task insights
Details can be found in [Wiesenfarth et al. (2021)](https://rdcu.be/ceiaN).
# Visualizing assessment data
```{r}
data <- read.csv(system.file("extdata", "data_matrix.csv", package = "challengeR", mustWork = TRUE))
challenge <- as.challenge(data, by = "task", algorithm = "alg_name", case = "case", value = "value", smallBetter = FALSE)
ranking <- challenge%>%aggregateThenRank(FUN = mean, ties.method = "min")
```
## Dot- and boxplots
Dot- and boxplots visualize the assessment data separately for each algorithm. Boxplots representing descriptive statistics for all test cases
(median, quartiles and outliers) are combined with horizontally jittered dots representing individual test cases.
```{r boxplot}
boxplot(ranking)
```
## Podium plots
Upper part of the podium plot: Algorithms are color-coded, and each colored dot in the plot represents a performance value achieved with the respective algorithm. The actual value is encoded by the y-axis. Each podium (here: $p = 5$) represents one possible rank, ordered from best (1) to worst (here: 5). The assignment of values (i.e. colored dots) to one of the podiums is based on the rank that the respective algorithm achieved on the corresponding test case.Note that the plot part above each podium place is further subdivided into $p$ “columns”, where each column represents one algorithm. Dots corresponding to identical test cases are connected by a line, producing the spaghetti structure shown here. Lower part: Bar charts represent the relative frequency at which each algorithm actually achieves the rank encoded by the podium place.
```{r podium,fig.width=5}
podium(ranking,
layout.heights = c(.6, 0.4))
```
## Ranking heatmaps
In a ranking heatmap, each cell $\left( i, A_j \right)$ shows the absolute frequency of cases in which algorithm $A_j$ achieved rank $i$.
```{r rankingHeatmap}
rankingHeatmap(ranking)
```
# Visualizing ranking stability
The ranking robustness can by analyzed with respect to the ranking method used (see [Wiesenfarth et al. (2021)](https://rdcu.be/ceiaN) for different ranking methods).
## Line plots
Line plots visualize the robustness of ranking across different ranking methods. Each algorithm is represented by one colored line.
For each ranking method encoded on the x-axis, the height of the line represents the corresponding rank. Horizontal lines indicate identical ranks for all methods.
```{r lineplot, fig.width = 7}
methodsplot(challenge)
```
For a specific ranking method, the ranking stability can be investigated via bootstrapping and the testing approach.
A ranking object containing the bootstrapping samples has to be created which serves as the basis for the plots.
```{r bootstrapping, results = "hide"}
-set.seed(1)
+set.seed(1, kind="L'Ecuyer-CMRG")
rankingBootstrapped <- ranking%>%bootstrap(nboot = 1000)
```
## Blob plots
Blob plots for visualizing ranking stability are based on bootstrap sampling. Algorithms are color-coded, and the area of each blob at position $\left( A_i, \text{rank } j \right)$ is proportional to the relative frequency $A_i$ achieved rank $j$ (here across $b = 1000$ bootstrap samples). The median rank for each algorithm is indicated by a black cross. 95% bootstrap intervals across bootstrap samples (ranging from the 2.5th to
the 97.5th percentile of the bootstrap distribution) are indicated by black lines.
```{r stabilityByTask1, fig.width = 7}
stabilityByTask(rankingBootstrapped)
```
## Violin plots
Violin plots provide a more condensed way to analyze bootstrap results. In these plots, the focus is on the comparison of the ranking list computed on the full assessment data and the individual bootstrap samples, respectively. Kendall’s $\tau$ is chosen for comparison as it is has an upper and lower bound (+1/-1). Kendall’s $\tau$ is computed for each pair of rankings, and a violin plot that simultaneously depicts a boxplot and a density plot is generated from the results.
```{r violin, results = "hide"}
violin(rankingBootstrapped)
```
## Significance maps
Significance maps visualize ranking stability based on statistical significance. They depict incidence matrices of pairwise significant test results for the one-sided Wilcoxon signed rank test at 5% significance level with adjustment for multiple testing according to Holm. Yellow shading indicates that performance values of the algorithm on the x-axis are significantly superior to those from the algorithm on the y-axis, blue color indicates no significant difference.
```{r significanceMap}
significanceMap(ranking)
```
# Visualizing cross-task insights
For cross-task insights, a consensus ranking (rank aggregation across tasks) has to be given additionally. The consensus ranking according to mean ranks across tasks is computed here.
```{r}
meanRanks <- ranking%>%consensus(method = "euclidean")
```
The consensus ranking is given according to mean ranks across tasks if method="euclidean" where in case of ties (equal ranks for multiple algorithms) the average rank is used, i.e. ties.method="average".
## Characterization of algorithms
The primary goal of most multi-task challenges is to identify methods that consistently outperform competing algorithms across all tasks. We propose the followig methods for analyzing this:
### Blob plots visualizing the ranking variability across tasks
Blob plots visualize the distribution of ranks across tasks. All ranks that an algorithm achieved in any task are displayed along the y-axis, with the area of the blob being proportional to the frequency. If all tasks provided the same stable ranking, narrow intervals around the diagonal would be expected. Consensus rankings above algorithm names highlight the presence of ties.
```{r stability, fig.width = 5, fig.height = 4}
stability(ranking, ordering = names(meanRanks))
```
### Blob plots visualizing the ranking variability based on bootstrapping
This variant of the blob plot approach involves replacing the algorithms on the x-axis with the tasks and then generating a separate plot for each algorithm. This allows assessing the variability of rankings for each algorithm across multiple tasks and bootstrap samples. Here, color coding is used for the tasks, and separation by algorithm enables a relatively straightforward strength-weaknesses analysis for individual methods.
```{r stabilityByAlgorithm1, fig.width = 7, fig.height = 5}
stabilityByAlgorithm(rankingBootstrapped, ordering = names(meanRanks))
```
### Stacked frequency plots visualizing the ranking variability based on bootstrapping
An alternative representation is provided by a stacked frequency plot of the observed ranks, separated by algorithm. Observed ranks across bootstrap samples are displayed with coloring according to the task. For algorithms that achieve the same rank in different tasks for the full assessment data set, vertical lines are on top of each other. Vertical lines allow to compare the achieved rank of each algorithm over different tasks.
```{r stabilityByAlgorithm2, fig.width = 7, fig.height = 5}
stabilityByAlgorithm(rankingBootstrapped, ordering = names(meanRanks), stacked = TRUE)
```
## Characterization of tasks
It may also be useful to structure the analysis around the different tasks. This section proposes visualizations to analyze and compare tasks of a competition.
### Blob plots visualizing bootstrap results
Bootstrap results can be shown in a blob plot showing one plot for each task. Algorithms should be ordered according to
the consensus ranking. In this view, the spread of the blobs for each algorithm can be compared across tasks. Deviations from the diagonal indicate deviations from the consensus ranking (over tasks). Specifically, if rank distribution of an algorithm is consistently below the diagonal, the algorithm performed better in this task than on average across tasks, while if the rank distribution of an algorithm is consistently above the diagonal, the algorithm performed worse in this task than on average across tasks. At the bottom of each panel, ranks for each algorithm in the tasks are provided.
```{r stabilityByTask2, fig.width = 7, fig.height = 3.5}
stabilityByTask(rankingBootstrapped, ordering = names(meanRanks))
```
### Violin plots visualizing bootstrap results
To obtain a more condensed visualization, violin plots (see above) can be applied separately to all tasks. The overall stability of the rankings can then be compared by assessing the locations and lengths of the violins.
### Cluster analysis
There is increasing interest in assessing the similarity of the tasks, e.g., for pre-training a machine learning algorithm. A potential approach to this could involve the comparison of the rankings for a challenge. Given the same teams participate in all tasks, it may be of interest to cluster tasks into groups where rankings of algorithms are similar and to identify tasks which lead to very dissimilar rankings of algorithms. To enable such an analysis, we propose the generation of a dendrogram from hierarchical cluster analysis. Here, it depicts clusters according to a chosen distance measure (Spearman’s footrule) as well as a chosen agglomeration method (complete agglomeration).
```{r dendrogram, fig.width = 7, fig.height = 3.5}
dendrogram(ranking)
```