Add comparison feature

.gitignore

@@ -1 +1,2 @@
+/cache
 .Rproj.user

NAMESPACE

@@ -1,7 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,geposan_comparison)
 S3method(print,geposan_preset)
 export(analyze)
+export(compare)
 export(optimal_weights)
 export(preset)
 export(ranking)

R/comparison.R

@@ -0,0 +1,75 @@
+#' Compare a set of genes with the ranking.
+#'
+#' @param ranking A ranking created using [ranking()].
+#' @param comparison_gene_ids IDs of the genes of interest.
+#'
+#' @returns A comparison object with the following items:
+#'   \describe{
+#'     \item{`mean`}{The mean score of the genes.}
+#'     \item{`min`}{The lowest score of the genes.}
+#'     \item{`max`}{The highest score of the genes.}
+#'     \item{`mean_rank`}{The mean rank of the genes.}
+#'     \item{`first_rank`}{The first rank of the genes.}
+#'     \item{`last_rank`}{The last rank of the genes.}
+#'     \item{`p_value`}{p-value for the null hypothesis that the comparison
+#'       genes do _not_ rank better than other genes. In other words: A low
+#'       p-value means that the comparison genes rank particularly high.}
+#'   }
+#'
+#' @export
+compare <- function(ranking, comparison_gene_ids) {
+    if (!"geposan_ranking" %chin% class(ranking)) {
+        stop("Invalid ranking. Use geposan::ranking().")
+    }
+
+    comparison_ranking <- ranking[gene %chin% comparison_gene_ids]
+
+    p_value <- wilcox.test(
+        x = comparison_ranking[, score],
+        y = ranking[!gene %chin% comparison_gene_ids, score],
+        alternative = "greater"
+    )$p.value
+
+    structure(
+        list(
+            mean = comparison_ranking[, mean(score)],
+            min = comparison_ranking[, min(score)],
+            max = comparison_ranking[, max(score)],
+            mean_rank = comparison_ranking[, mean(rank)],
+            first_rank = comparison_ranking[, min(rank)],
+            last_rank = comparison_ranking[, max(rank)],
+            p_value = p_value
+        ),
+        class = "geposan_comparison"
+    )
+}
+
+#' S3 method to print a comparison object.
+#'
+#' @seealso [compare()]
+#'
+#' @export
+print.geposan_comparison <- function(comparison, ...) {
+    cat("geposan comparison:")
+    cat(sprintf(
+        paste(
+            "\n\n  Mean score: %.3f",
+            "\n  Min score: %.3f",
+            "\n  Max score: %.3f",
+            "\n\n  Mean rank: %.1f",
+            "\n  First rank: %i",
+            "\n  Last rank: %i",
+            "\n\n  p-value for better ranking: %.4f\n",
+            sep = ""
+        ),
+        comparison$mean,
+        comparison$min,
+        comparison$max,
+        comparison$mean_rank,
+        comparison$first_rank,
+        comparison$last_rank,
+        comparison$p_value
+    ))
+
+    invisible(comparison)
+}

man/compare.Rd

@@ -0,0 +1,30 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/comparison.R
+\name{compare}
+\alias{compare}
+\title{Compare a set of genes with the ranking.}
+\usage{
+compare(ranking, comparison_gene_ids)
+}
+\arguments{
+\item{ranking}{A ranking created using \code{\link[=ranking]{ranking()}}.}
+
+\item{comparison_gene_ids}{IDs of the genes of interest.}
+}
+\value{
+A comparison object with the following items:
+\describe{
+\item{\code{mean}}{The mean score of the genes.}
+\item{\code{min}}{The lowest score of the genes.}
+\item{\code{max}}{The highest score of the genes.}
+\item{\code{mean_rank}}{The mean rank of the genes.}
+\item{\code{first_rank}}{The first rank of the genes.}
+\item{\code{last_rank}}{The last rank of the genes.}
+\item{\code{p_value}}{p-value for the null hypothesis that the comparison
+genes do \emph{not} rank better than other genes. In other words: A low
+p-value means that the comparison genes rank particularly high.}
+}
+}
+\description{
+Compare a set of genes with the ranking.
+}

man/print.geposan_comparison.Rd

@@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/comparison.R
+\name{print.geposan_comparison}
+\alias{print.geposan_comparison}
+\title{S3 method to print a comparison object.}
+\usage{
+\method{print}{geposan_comparison}(comparison, ...)
+}
+\description{
+S3 method to print a comparison object.
+}
+\seealso{
+\code{\link[=compare]{compare()}}
+}