diff --git a/man/aggregate.challenge.Rd b/man/aggregate.challenge.Rd new file mode 100644 index 0000000..b452a41 --- /dev/null +++ b/man/aggregate.challenge.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/aaggregate.R +\name{aggregate.challenge} +\alias{aggregate.challenge} +\title{Title} +\usage{ +\method{aggregate}{challenge}( + x, + FUN = mean, + na.treat, + alpha = 0.05, + p.adjust.method = "none", + parallel = FALSE, + progress = "none", + ... +) +} +\arguments{ +\item{...}{} +} +\value{ + +} +\description{ +Title +} diff --git a/man/aggregateThenRank.Rd b/man/aggregateThenRank.Rd new file mode 100644 index 0000000..8e57e32 --- /dev/null +++ b/man/aggregateThenRank.Rd @@ -0,0 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rankingMethods.R +\name{aggregateThenRank} +\alias{aggregateThenRank} +\title{Performs ranking via aggregate-then-rank} +\usage{ +aggregateThenRank(object, FUN, ties.method = "min", ...) +} +\arguments{ +\item{object}{The challenge object.} + +\item{FUN}{The aggregation function, e.g. mean, median, min, max, function(x), quantile(x, probs=0.05).} + +\item{ties.method}{A string specifying how ties are treated, see \code{\link[base:rank]{base::rank()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ +An S3 object of class "ranked.list" to represent a ranked assessment data set. +} +\description{ +Performs ranking by first aggregating performance values across all cases (e.g., with the mean, median or another quantile) for each algorithm. +This aggregate is then used to compute a rank for each algorithm. +} +\examples{ + +\dontrun{ + aggregateThenRank(challenge, FUN = mean, ties.method = "average", na.treat = 0) +} + +} +\seealso{ +Other ranking functions: +\code{\link{rankThenAggregate}()}, +\code{\link{testThenRank}()} +} +\concept{ranking functions} diff --git a/man/as.challenge.Rd b/man/as.challenge.Rd new file mode 100644 index 0000000..c08e63f --- /dev/null +++ b/man/as.challenge.Rd @@ -0,0 +1,88 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/challengeR.R +\name{as.challenge} +\alias{as.challenge} +\title{Constructs a challenge object} +\usage{ +as.challenge( + object, + case, + algorithm, + value, + by = NULL, + taskName = NULL, + annotator = NULL, + smallBetter = FALSE, + na.treat = NULL, + check = TRUE +) +} +\arguments{ +\item{object}{A data frame containing the assessment data.} + +\item{case}{A string specifying the name of the column that contains the case identifiers.} + +\item{algorithm}{A string specifying the name of the column that contains the algorithm identifiers.} + +\item{value}{A string specifying the name of the column that contains the performance values.} + +\item{by}{A string specifying the name of the column that contains the task identifiers. Required for multi-task data set.} + +\item{taskName}{A string specifying the task name for single-task data set that does not contain a task column. +This argument is optional for a single-task data set and is ignored for a multi-task data set.} + +\item{annotator}{Not supported} + +\item{smallBetter}{A boolean specifying whether small performance values indicate better algorithm performance.} + +\item{na.treat}{Indicates how missing perfomance values are treated if sanity check is enabled. It can be 'na.rm', numeric value or function. +For a numeric value or function, NAs will be replaced by the specified values. For 'na.rm', rows that contain missing values will be removed.} + +\item{check}{A boolean to indicate to perform a sanity check of the specified data set and arguments if set to \code{TRUE}.} +} +\value{ +An S3 object to represent the configuration of an assessment data set. +} +\description{ +Constructs an S3 object to represent the configuration of an assessment data set originating from a benchmarking competition (so-called "challenge"). +} +\section{Assessment data set}{ + +The toolkit provides visualization approaches for both challenges designed around a single task (single-task challenges) and for challenges comprising multiple tasks (multi-task challenges). +For a single-task challenge, the assessment data set (argument \code{object}) requires the following columns: +\itemize{ +\item test case identifier (string or numeric) +\item algorithm identifier (string or numeric) +\item performance value (numeric) +} + +For a multi-task challenge, the assessment data set (argument \code{object}) requires the following columns: +\itemize{ +\item task identifier (string or numeric) +\item test case identifier (string or numeric) +\item algorithm identifier (string or numeric) +\item performance value (numeric) +} +} + +\section{Sanity check}{ + +It is highly recommended that the sanity check is not disabled when the data set is provided initially. +It checks that: +\itemize{ +\item performance values are numeric (if not, raises error) +\item algorithm performances are observed for all cases (if not, adds them as NA and emits a message) +\item cases appear only once for the same algorithm (if not, raises error) +} +If the argument \code{na.treat} for treatment of NA is specified, NAs will be handled respectively. + +It might be reasonable to disable the sanity check for further computations (e.g., for performance reasons +during bootstrapping (\code{\link{bootstrap.ranked.list}}) where cases are actually allowed to appear more than once for the same algorithm). +} + +\examples{ +# single-task data set + +# multi-task data set + +} diff --git a/man/bootstrap.ranked.list.Rd b/man/bootstrap.ranked.list.Rd new file mode 100644 index 0000000..45106ba --- /dev/null +++ b/man/bootstrap.ranked.list.Rd @@ -0,0 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Bootstrap.R +\name{bootstrap.ranked.list} +\alias{bootstrap.ranked.list} +\title{Performs bootstrapping} +\usage{ +\method{bootstrap}{ranked.list}(object, nboot, parallel = FALSE, progress = "text", ...) +} +\arguments{ +\item{object}{The ranked assessment data set.} + +\item{nboot}{The number of bootstrap samples.} + +\item{parallel}{A boolean specifying whether parallel processing should be enabled.} + +\item{progress}{A string specifying the type of progress indication.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ +An S3 object of class "bootstrap.list" to represent a bootstrapped, ranked assessment data set. +} +\description{ +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. +} +\examples{ + +\dontrun{ + # perform bootstrapping with 1000 bootstrap samples using one CPU + set.seed(1) + ranking_bootstrapped <- bootstrap(ranking, nboot = 1000) +} + +\dontrun{ + # perform bootstrapping using multiple CPUs (here: 8 CPUs) + library(doParallel) + registerDoParallel(cores=8) + set.seed(1) + ranking_bootstrapped <- bootstrap(ranking, nboot = 1000, parallel = TRUE, progress = "none") + stopImplicitCluster() +} + +} diff --git a/man/boxplot.ranked.list.Rd b/man/boxplot.ranked.list.Rd new file mode 100644 index 0000000..8fccd50 --- /dev/null +++ b/man/boxplot.ranked.list.Rd @@ -0,0 +1,38 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/boxplot.R +\name{boxplot.ranked.list} +\alias{boxplot.ranked.list} +\title{Creates dot- and boxplots} +\usage{ +\method{boxplot}{ranked.list}(x, color = "blue", jitter.width = 0.25, ...) +} +\arguments{ +\item{x}{The ranked assessment data set.} + +\item{color}{A string specifying the color of the dots.} + +\item{jitter.width}{A numeric value specifying the jitter width of the dots.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates dot- and boxplots visualizing 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. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize assessment data: +\code{\link{podium.challenge}()}, +\code{\link{podium.ranked.list}()}, +\code{\link{rankingHeatmap.challenge}()}, +\code{\link{rankingHeatmap.ranked.list}()} +} +\concept{functions to visualize assessment data} diff --git a/man/consensus.ranked.list.Rd b/man/consensus.ranked.list.Rd new file mode 100644 index 0000000..3e8a9e6 --- /dev/null +++ b/man/consensus.ranked.list.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/consensus.R +\name{consensus.ranked.list} +\alias{consensus.ranked.list} +\title{Computes a consensus ranking} +\usage{ +\method{consensus}{ranked.list}(object, method, ...) +} +\arguments{ +\item{object}{The ranked asssessment data set.} + +\item{method}{A string specifying the method to derive the consensus ranking, see \code{\link[relations:consensus]{relations::consensus()}} for the methods.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Computes a consensus ranking (rank aggregation) across tasks. +} diff --git a/man/dendrogram.ranked.list.Rd b/man/dendrogram.ranked.list.Rd new file mode 100644 index 0000000..0a3abc3 --- /dev/null +++ b/man/dendrogram.ranked.list.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dendrogram.R +\name{dendrogram.ranked.list} +\alias{dendrogram.ranked.list} +\title{Creates a cluster dendrogram} +\usage{ +\method{dendrogram}{ranked.list}(object, dist = "symdiff", method = "complete", ...) +} +\arguments{ +\item{object}{The ranked assessment data set.} + +\item{dist}{A string specifying the distance measure to be used, see \code{\link[relations:dissimilarity]{relations::dissimilarity()}}.} + +\item{method}{A string specifying agglomeration method to be used, see \code{\link[stats:hclust]{stats::hclust()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates a cluster dendrogram from a ranked assessment data set. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize cross-task insights: +\code{\link{stability.ranked.list}()}, +\code{\link{stabilityByAlgorithm.bootstrap.list}()}, +\code{\link{stabilityByTask.bootstrap.list}()} +} +\concept{functions to visualize cross-task insights} diff --git a/man/methodsplot.challenge.Rd b/man/methodsplot.challenge.Rd new file mode 100644 index 0000000..7f33fd2 --- /dev/null +++ b/man/methodsplot.challenge.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methodsplot.R +\name{methodsplot.challenge} +\alias{methodsplot.challenge} +\title{Creates line plots} +\usage{ +\method{methodsplot}{challenge}( + x, + na.treat = NULL, + methods = list(testBased = . \%>\% test() \%>\% rank(ties.method = "min"), + meanThenRank = . \%>\% aggregate(FUN = "mean") \%>\% rank(ties.method = "min"), + medianThenRank = . \%>\% aggregate(FUN = "median") \%>\% rank(ties.method = "min"), + rankThenMean = . \%>\% rank(ties.method = "min") \%>\% aggregate(FUN = "mean") \%>\% + rank(ties.method = "min"), rankThenMedian = . \%>\% rank(ties.method = "min") \%>\% + aggregate(FUN = "median") \%>\% rank(ties.method = "min")), + ordering, + ... +) +} +\arguments{ +\item{x}{The challenge object.} + +\item{na.treat}{Indicates how missing perfomance values are treated if sanity check is enabled. It can be 'na.rm', numeric value or function. +For a numeric value or function, NAs will be replaced by the specified values. For 'na.rm', rows that contain missing values will be removed.} + +\item{methods}{A list of ranking methods that should be incorporated.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Create line plots that visualize the robustness of ranking across different ranking methods from a challenge object. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize ranking stability: +\code{\link{significanceMap.ranked.list}()}, +\code{\link{stabilityByTask.bootstrap.list}()}, +\code{\link{violin.bootstrap.list}()} +} +\concept{functions to visualize ranking stability} diff --git a/man/podium.challenge.Rd b/man/podium.challenge.Rd new file mode 100644 index 0000000..989f29d --- /dev/null +++ b/man/podium.challenge.Rd @@ -0,0 +1,54 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/podium.R +\name{podium.challenge} +\alias{podium.challenge} +\title{Creates a podium plot} +\usage{ +\method{podium}{challenge}( + object, + ordering, + xlab = NULL, + ylab = NULL, + lines.show = FALSE, + lines.alpha = 0.2, + lines.lwd = 1, + col, + lines.col = col, + dots.pch = 19, + dots.cex = 1, + places.lty = 2, + places.col = 1, + legendfn = function(algs, cols) { legend("topleft", algs, lwd = 1, col = cols, bg + = "white") }, + layout.heights = c(1, 0.4), + ... +) +} +\arguments{ +\item{object}{The challenge object.} + +\item{xlab}{A string specifying the x-axis label.} + +\item{ylab}{A string specifying the y-axis label.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates a podium plot from a challenge object. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize assessment data: +\code{\link{boxplot.ranked.list}()}, +\code{\link{podium.ranked.list}()}, +\code{\link{rankingHeatmap.challenge}()}, +\code{\link{rankingHeatmap.ranked.list}()} +} +\concept{functions to visualize assessment data} diff --git a/man/podium.ranked.list.Rd b/man/podium.ranked.list.Rd new file mode 100644 index 0000000..6ce2c4f --- /dev/null +++ b/man/podium.ranked.list.Rd @@ -0,0 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/podium.R +\name{podium.ranked.list} +\alias{podium.ranked.list} +\title{Creates podium plots} +\usage{ +\method{podium}{ranked.list}( + object, + xlab = "Podium", + ylab = "Performance", + lines.show = TRUE, + lines.alpha = 0.2, + lines.lwd = 1, + col, + lines.col = col, + dots.pch = 19, + dots.cex = 1, + places.lty = 2, + places.col = 1, + legendfn = function(algs, cols) { legend("topleft", algs, lwd = 1, col = cols, bg + = "white") }, + layout.heights = c(1, 0.4), + ... +) +} +\arguments{ +\item{object}{The ranked asssessment data set.} + +\item{xlab}{A string specifying the x-axis label.} + +\item{ylab}{A string specifying the y-axis label.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates podium plots from one or more ranked assessment data sets. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize assessment data: +\code{\link{boxplot.ranked.list}()}, +\code{\link{podium.challenge}()}, +\code{\link{rankingHeatmap.challenge}()}, +\code{\link{rankingHeatmap.ranked.list}()} +} +\concept{functions to visualize assessment data} diff --git a/man/rankThenAggregate.Rd b/man/rankThenAggregate.Rd new file mode 100644 index 0000000..116e74b --- /dev/null +++ b/man/rankThenAggregate.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rankingMethods.R +\name{rankThenAggregate} +\alias{rankThenAggregate} +\title{Performs ranking via rank-then-aggregate} +\usage{ +rankThenAggregate(object, FUN, ties.method = "min") +} +\arguments{ +\item{object}{The challenge object.} + +\item{FUN}{The aggregation function, e.g., mean, median, min, max, function(x), quantile(x, probs=0.05).} + +\item{ties.method}{A string specifying how ties are treated, see \code{\link[base:rank]{base::rank()}}.} +} +\value{ +An S3 object of class "ranked.list" to represent a ranked assessment data set. +} +\description{ +Performs ranking by first computing a rank for each case for each algorithm ("rank first"). +The final rank is based on the aggregated ranks for the cases. This ranking method handles missing values implicitly +by assigning the worst rank to missing algorithm performances. +} +\examples{ +\dontrun{ + rankThenAggregate(challenge, FUN = mean) +} + +} +\seealso{ +Other ranking functions: +\code{\link{aggregateThenRank}()}, +\code{\link{testThenRank}()} +} +\concept{ranking functions} diff --git a/man/rankingHeatmap.challenge.Rd b/man/rankingHeatmap.challenge.Rd new file mode 100644 index 0000000..0f6efda --- /dev/null +++ b/man/rankingHeatmap.challenge.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rankingHeatmap.R +\name{rankingHeatmap.challenge} +\alias{rankingHeatmap.challenge} +\title{Creates a ranking heatmap} +\usage{ +\method{rankingHeatmap}{challenge}(x, ordering, ties.method = "min", ...) +} +\arguments{ +\item{x}{The challenge object.} + +\item{ties.method}{A string specifying how ties are treated, see \code{\link[base:rank]{base::rank()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates a ranking heatmap from a challenge object. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize assessment data: +\code{\link{boxplot.ranked.list}()}, +\code{\link{podium.challenge}()}, +\code{\link{podium.ranked.list}()}, +\code{\link{rankingHeatmap.ranked.list}()} +} +\concept{functions to visualize assessment data} diff --git a/man/rankingHeatmap.ranked.list.Rd b/man/rankingHeatmap.ranked.list.Rd new file mode 100644 index 0000000..a896b69 --- /dev/null +++ b/man/rankingHeatmap.ranked.list.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rankingHeatmap.R +\name{rankingHeatmap.ranked.list} +\alias{rankingHeatmap.ranked.list} +\title{Creates ranking heatmaps} +\usage{ +\method{rankingHeatmap}{ranked.list}(x, ties.method = "min", ...) +} +\arguments{ +\item{x}{The ranked asssessment data set.} + +\item{ties.method}{A string specifying how ties are treated, see \code{\link[base:rank]{base::rank()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates ranking heatmaps from one or more ranked assessment data sets. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize assessment data: +\code{\link{boxplot.ranked.list}()}, +\code{\link{podium.challenge}()}, +\code{\link{podium.ranked.list}()}, +\code{\link{rankingHeatmap.challenge}()} +} +\concept{functions to visualize assessment data} diff --git a/man/report.bootstrap.list.Rd b/man/report.bootstrap.list.Rd new file mode 100644 index 0000000..df0b71a --- /dev/null +++ b/man/report.bootstrap.list.Rd @@ -0,0 +1,60 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/report.R +\name{report.bootstrap.list} +\alias{report.bootstrap.list} +\title{Generates a benchmarking report with bootstrapping results} +\usage{ +\method{report}{bootstrap.list}( + object, + consensus, + file, + title = "", + colors = default_colors, + format = "PDF", + latex_engine = "pdflatex", + clean = TRUE, + fig.format = NULL, + dpi = 150, + open = TRUE, + ... +) +} +\arguments{ +\item{object}{The ranked (bootstrapped) assessment data set.} + +\item{consensus}{The rank aggregation across tasks (consensus ranking). Only needed for a multi-task data set.} + +\item{file}{A string specifying the file name of the report. It allows for specifying the output file path as well, +otherwise the working directory is used. If \code{file} does not have a file extension, an extension will be automatically +added according to the output format given in \code{format}. If the argument is omitted, the report is created in a +temporary folder with file name "report".} + +\item{title}{A string specifying the title of the report.} + +\item{colors}{The color scheme that is applied to the plots.} + +\item{format}{A string specifying the format of the report. The options are "PDF", "HTML" or "Word".} + +\item{latex_engine}{A string specifying the LaTeX engine for producing PDF output. The Options are "pdflatex", "lualatex", and "xelatex".} + +\item{clean}{A boolean indicating whether intermediate files (e.g. individual plots) should be kept. Using \code{TRUE} will clean +intermediate files that are created during rendering.} + +\item{fig.format}{A vector of strings containing the file format of the figures that are not removed if \code{clean} is set to \code{FALSE}. +The options are "jpeg", "png" and "pdf", e.g. \code{fig.format = c("jpeg", "png", "pdf")}.} + +\item{dpi}{A positive integer specifying the resolution of the generated plot (\code{fig.format} "jpeg" or "png") in dots per inch (DPI).} + +\item{open}{A boolean specifying whether the report should be opened with the default system viewer after generation.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Generates a benchmarking report in PDF, HTML or Word format with bootstrapping results. +It contains the rankings, plots of the raw assessment data and plots of the ranking stability. +For multi-task challenges, it also contains plots of cross-task insights. If you are interested in +the individual plots as separate files, set argument \code{clean} to \code{FALSE} and specify \code{fig.format}. +} diff --git a/man/report.ranked.list.Rd b/man/report.ranked.list.Rd new file mode 100644 index 0000000..49131e2 --- /dev/null +++ b/man/report.ranked.list.Rd @@ -0,0 +1,60 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/report.R +\name{report.ranked.list} +\alias{report.ranked.list} +\title{Generates a benchmarking report without bootstrapping results} +\usage{ +\method{report}{ranked.list}( + object, + consensus, + file, + title = "", + colors = default_colors, + format = "PDF", + latex_engine = "pdflatex", + clean = TRUE, + fig.format = NULL, + dpi = 150, + open = TRUE, + ... +) +} +\arguments{ +\item{object}{The ranked assessment data set.} + +\item{consensus}{The rank aggregation across tasks (consensus ranking). Only needed for a multi-task data set.} + +\item{file}{A string specifying the file name of the report. It allows for specifying the output file path as well, +otherwise the working directory is used. If \code{file} does not have a file extension, an extension will be automatically +added according to the output format given in \code{format}. If the argument is omitted, the report is created in a +temporary folder with file name "report".} + +\item{title}{A string specifying the title of the report.} + +\item{colors}{The color scheme that is applied to the plots.} + +\item{format}{A string specifying the format of the report. The options are "PDF", "HTML" or "Word".} + +\item{latex_engine}{A string specifying the LaTeX engine for producing PDF output. The Options are "pdflatex", "lualatex", and "xelatex".} + +\item{clean}{A boolean indicating whether intermediate files (e.g. individual plots) should be kept. Using \code{TRUE} will clean +intermediate files that are created during rendering.} + +\item{fig.format}{A vector of strings containing the file format of the figures that are not removed if \code{clean} is set to \code{FALSE}. +The options are "jpeg", "png" and "pdf", e.g. \code{fig.format = c("jpeg", "png", "pdf")}.} + +\item{dpi}{A positive integer specifying the resolution of the generated plot (\code{fig.format} "jpeg" or "png") in dots per inch (DPI).} + +\item{open}{A boolean specifying whether the report should be opened with the default system viewer after generation.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Generates a benchmarking report in PDF, HTML or Word format without bootstrapping results. +It contains the rankings, plots of the raw assessment data and plots of the ranking stability. +For multi-task challenges, it also contains plots of cross-task insights. If you are interested in +the individual plots as separate files, set argument \code{clean} to \code{FALSE} and specify \code{fig.format}. +} diff --git a/man/significanceMap.ranked.list.Rd b/man/significanceMap.ranked.list.Rd new file mode 100644 index 0000000..b48291b --- /dev/null +++ b/man/significanceMap.ranked.list.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/significanceMap.R +\name{significanceMap.ranked.list} +\alias{significanceMap.ranked.list} +\title{Creates significance maps} +\usage{ +\method{significanceMap}{ranked.list}( + object, + alpha = 0.05, + p.adjust.method = "holm", + order = FALSE, + size.rank = 0.3 * theme_get()$text$size, + ... +) +} +\arguments{ +\item{object}{The ranked assessment data set.} + +\item{alpha}{A numeric values specifying the significance level.} + +\item{p.adjust.method}{A string specifying the adjustment method for multiple testing, see \code{\link[stats:p.adjust]{stats::p.adjust()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates significance maps from a ranked assessment data set. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize ranking stability: +\code{\link{methodsplot.challenge}()}, +\code{\link{stabilityByTask.bootstrap.list}()}, +\code{\link{violin.bootstrap.list}()} +} +\concept{functions to visualize ranking stability} diff --git a/man/stability.ranked.list.Rd b/man/stability.ranked.list.Rd new file mode 100644 index 0000000..6471bfe --- /dev/null +++ b/man/stability.ranked.list.Rd @@ -0,0 +1,39 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stability.R +\name{stability.ranked.list} +\alias{stability.ranked.list} +\title{Creates a blob plot across tasks} +\usage{ +\method{stability}{ranked.list}( + x, + ordering, + probs = c(0.025, 0.975), + max_size = 6, + freq = FALSE, + shape = 4, + ... +) +} +\arguments{ +\item{x}{The ranked asssessment data set.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates a blob plots visualizing the ranking variability across tasks. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize cross-task insights: +\code{\link{dendrogram.ranked.list}()}, +\code{\link{stabilityByAlgorithm.bootstrap.list}()}, +\code{\link{stabilityByTask.bootstrap.list}()} +} +\concept{functions to visualize cross-task insights} diff --git a/man/stabilityByAlgorithm.bootstrap.list.Rd b/man/stabilityByAlgorithm.bootstrap.list.Rd new file mode 100644 index 0000000..e0fb356 --- /dev/null +++ b/man/stabilityByAlgorithm.bootstrap.list.Rd @@ -0,0 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stability.R +\name{stabilityByAlgorithm.bootstrap.list} +\alias{stabilityByAlgorithm.bootstrap.list} +\title{Creates blob plots or stacked frequency plots stratified by algorithm} +\usage{ +\method{stabilityByAlgorithm}{bootstrap.list}( + x, + ordering, + stacked = FALSE, + probs = c(0.025, 0.975), + max_size = 3, + shape = 4, + freq = FALSE, + single = FALSE, + ... +) +} +\arguments{ +\item{x}{The bootstrapped, ranked assessment data set.} + +\item{stacked}{A boolean specifying whether a stacked frequency plot (\code{stacked = TRUE}) or blob plot (\code{stacked = FALSE}) should be created.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates blob plots (\code{stacked = FALSE}) or stacked frequency plots (\code{stacked = TRUE}) for each algorithm +from a bootstrapped, ranked assessment data set. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize cross-task insights: +\code{\link{dendrogram.ranked.list}()}, +\code{\link{stability.ranked.list}()}, +\code{\link{stabilityByTask.bootstrap.list}()} +} +\concept{functions to visualize cross-task insights} diff --git a/man/stabilityByTask.bootstrap.list.Rd b/man/stabilityByTask.bootstrap.list.Rd new file mode 100644 index 0000000..d2d4c24 --- /dev/null +++ b/man/stabilityByTask.bootstrap.list.Rd @@ -0,0 +1,48 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stability.R +\name{stabilityByTask.bootstrap.list} +\alias{stabilityByTask.bootstrap.list} +\title{Creates blob plots stratified by task} +\usage{ +\method{stabilityByTask}{bootstrap.list}( + x, + ordering, + probs = c(0.025, 0.975), + max_size = 3, + size.ranks = 0.3 * theme_get()$text$size, + shape = 4, + showLabelForSingleTask = FALSE, + ... +) +} +\arguments{ +\item{x}{The bootstrapped, ranked assessment data set.} + +\item{showLabelForSingleTask}{A boolean specifying whether the task name should be used as title for a single-task data set.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates blob plots for each task from a bootstrapped, ranked assessment data set. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize ranking stability: +\code{\link{methodsplot.challenge}()}, +\code{\link{significanceMap.ranked.list}()}, +\code{\link{violin.bootstrap.list}()} + +Other functions to visualize cross-task insights: +\code{\link{dendrogram.ranked.list}()}, +\code{\link{stability.ranked.list}()}, +\code{\link{stabilityByAlgorithm.bootstrap.list}()} +} +\concept{functions to visualize cross-task insights} +\concept{functions to visualize ranking stability} diff --git a/man/subset.bootstrap.list.Rd b/man/subset.bootstrap.list.Rd new file mode 100644 index 0000000..f12d99f --- /dev/null +++ b/man/subset.bootstrap.list.Rd @@ -0,0 +1,51 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/subset.R +\name{subset.bootstrap.list} +\alias{subset.bootstrap.list} +\title{Extracts a subset of algorithms or tasks} +\usage{ +\method{subset}{bootstrap.list}(x, top, tasks, ...) +} +\arguments{ +\item{x}{The bootstrapped, ranked asssessment data set.} + +\item{top}{A positive integer specifying the amount of top performing algorithms to be retrieved.} + +\item{tasks}{A vector of strings containing the task identifiers that should remain in the subset.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ +An S3 object of class "bootstrap.list" to represent a bootstrapped, ranked assessment data set. +} +\description{ +Extracts the top performing algorithms or a subset of tasks. +} +\section{Reports for subsets (top list) of algorithms}{ + +If ties are present in the ranking, the subset will consist of more than \code{top} algorithms. +Line plots 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 plots and ranking heatmaps 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). +} + +\section{Reports for subsets of tasks}{ + +You may want to recompute the consensus ranking after creating the subset. An error will be raised +if a task identifier is not contained in the assessment data set to avoid subsequent errors. +} + +\examples{ + +\dontrun{ + # only show the top 3 algorithms according to the chosen ranking method + subset(ranking_bootstrapped, top = 3) \%>\% report(...) +} + +\dontrun{ + # restrict report to tasks "task1" and "task2" and recompute consensus ranking + meanRanks <- subset(ranking, tasks = c("task1", "task2")) \%>\% consensus(method = "euclidean") +} + +} diff --git a/man/subset.ranked.list.Rd b/man/subset.ranked.list.Rd new file mode 100644 index 0000000..6203ab1 --- /dev/null +++ b/man/subset.ranked.list.Rd @@ -0,0 +1,51 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/subset.R +\name{subset.ranked.list} +\alias{subset.ranked.list} +\title{Extracts a subset of algorithms or tasks} +\usage{ +\method{subset}{ranked.list}(x, top, tasks, ...) +} +\arguments{ +\item{x}{The ranked asssessment data set.} + +\item{top}{A positive integer specifying the amount of top performing algorithms to be retrieved.} + +\item{tasks}{A vector of strings containing the task identifiers that should remain in the subset.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ +An S3 object of class "ranked.list" to represent a ranked assessment data set. +} +\description{ +Extracts the top performing algorithms or a subset of tasks. +} +\section{Reports for subsets (top list) of algorithms}{ + +If ties are present in the ranking, the subset will consist of more than \code{top} algorithms. +Line plots 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 plots and ranking heatmaps 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). +} + +\section{Reports for subsets of tasks}{ + +You may want to recompute the consensus ranking after creating the subset. An error will be raised +if a task identifier is not contained in the assessment data set to avoid subsequent errors. +} + +\examples{ + +\dontrun{ + # only show the top 3 algorithms according to the chosen ranking method + subset(ranking, top = 3) \%>\% report(...) +} + +\dontrun{ + # restrict report to tasks "task1" and "task2" + subset(ranking, tasks=c("task1", "task2")) \%>\% report(...) +} + +} diff --git a/man/testThenRank.Rd b/man/testThenRank.Rd new file mode 100644 index 0000000..fa1f17c --- /dev/null +++ b/man/testThenRank.Rd @@ -0,0 +1,39 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rankingMethods.R +\name{testThenRank} +\alias{testThenRank} +\title{Performs ranking via test-then-rank} +\usage{ +testThenRank(object, ties.method = "min", ...) +} +\arguments{ +\item{object}{The challenge object.} + +\item{ties.method}{A string specifying how ties are treated, see \code{\link[base:rank]{base::rank()}}.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ +An S3 object of class "ranked.list" to represent a ranked assessment data set. +} +\description{ +Computes statistical hypothesis tests based on Wilcoxon signed rank test for each possible +pair of algorithms to assess differences in metric values between the algorithms. +Then ranking is performed according to the number of significant one-sided test results. +If algorithms have the same number of significant test results, then they obtain the same rank. +} +\examples{ +\dontrun{ + testThenRank(challenge, + alpha=0.05, # significance level + p.adjust.method="none", # method for adjustment for multiple testing, see ?p.adjust + na.treat = 0) +} + +} +\seealso{ +Other ranking functions: +\code{\link{aggregateThenRank}()}, +\code{\link{rankThenAggregate}()} +} +\concept{ranking functions} diff --git a/man/violin.bootstrap.list.Rd b/man/violin.bootstrap.list.Rd new file mode 100644 index 0000000..87d90e2 --- /dev/null +++ b/man/violin.bootstrap.list.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/violin.R +\name{violin.bootstrap.list} +\alias{violin.bootstrap.list} +\title{Creates a violin plot} +\usage{ +\method{violin}{bootstrap.list}(x, ...) +} +\arguments{ +\item{x}{The bootstrapped, ranked assessment data set.} + +\item{...}{Further arguments passed to or from other functions.} +} +\value{ + +} +\description{ +Creates a violin plot from a bootstrapped, ranked assessment data set. +} +\examples{ + +} +\seealso{ +\code{browseVignettes("challengeR")} + +Other functions to visualize ranking stability: +\code{\link{methodsplot.challenge}()}, +\code{\link{significanceMap.ranked.list}()}, +\code{\link{stabilityByTask.bootstrap.list}()} +} +\concept{functions to visualize ranking stability}