From 4992bb293043fb83341e1d5639fd039d49bd69fa Mon Sep 17 00:00:00 2001
From: Elias Projahn <elias@johrpan.de>
Date: Fri, 5 Nov 2021 14:47:33 +0100
Subject: [PATCH] ranking: Use S3 classes and rename optimize method

---
 NAMESPACE                                     |  2 +-
 R/ranking.R                                   | 52 ++++++++++++-------
 man/analyze.Rd                                |  7 +--
 ...optimize_weights.Rd => optimal_weights.Rd} | 11 ++--
 man/ranking.Rd                                | 14 +++--
 5 files changed, 55 insertions(+), 31 deletions(-)
 rename man/{optimize_weights.Rd => optimal_weights.Rd} (62%)

diff --git a/NAMESPACE b/NAMESPACE
index 011c4ce..59b6db6 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,7 +2,7 @@
 
 S3method(print,geposan_preset)
 export(analyze)
-export(optimize_weights)
+export(optimal_weights)
 export(preset)
 export(ranking)
 import(data.table)
diff --git a/R/ranking.R b/R/ranking.R
index 48d8369..e55917d 100644
--- a/R/ranking.R
+++ b/R/ranking.R
@@ -1,29 +1,40 @@
 #' Rank the results by computing a score.
 #'
-#' This function takes the result from [analyze()] and creates a score by
+#' This function takes the result of [analyze()] and creates a score by
 #' computing a weighted mean across the different methods' results.
 #'
-#' @param results Results from [analyze()].
-#' @param weights Named list pairing method names with weighting factors.
+#' @param analysis Analysis object resulting from [analyze()].
+#' @param weights Named list pairing method names with weighting factors. Only
+#'   methods that are contained within this list will be included.
 #'
-#' @result The input data with an additional column containing the score and
-#'   another column containing the rank.
+#' @returns A ranking object. The object extends the analysis with additional
+#'   columns containing the `score` and the `rank` of each gene. It will be
+#'   ordered by rank.
 #'
 #' @export
-ranking <- function(results, weights) {
-    results <- copy(results)
-    results[, score := 0.0]
+ranking <- function(analysis, weights) {
+    if (!"geposan_analysis" %chin% class(analysis)) {
+        stop("Invalid analyis. Use geposan::analyze().")
+    }
+
+    ranking <- copy(analysis)
+    ranking[, score := 0.0]
 
     for (method in names(weights)) {
-        weighted <- weights[[method]] * results[, ..method]
-        results[, score := score + weighted]
+        weighted <- weights[[method]] * ranking[, ..method]
+        ranking[, score := score + weighted]
     }
 
     # Normalize scores to be between 0.0 and 1.0.
-    results[, score := score / sum(unlist(weights))]
+    ranking[, score := score / sum(unlist(weights))]
 
-    setorder(results, -score)
-    results[, rank := .I]
+    setorder(ranking, -score)
+    ranking[, rank := .I]
+
+    structure(
+        ranking,
+        class = c("geposan_ranking", "geposan_analysis", class(ranking))
+    )
 }
 
 #' Find the best weights to rank the results.
@@ -31,17 +42,22 @@ ranking <- function(results, weights) {
 #' This function finds the optimal parameters to [ranking()] that result in the
 #' reference genes ranking particulary high.
 #'
-#' @param results Results from [analyze()] or [ranking()].
+#' @param analysis Results from [analyze()] or [ranking()].
 #' @param methods Methods to include in the score.
 #' @param reference_gene_ids IDs of the reference genes.
 #' @param target The optimization target. It may be one of "mean", "min" or
 #'   "max" and results in the respective rank being optimized.
 #'
-#' @returns Named list pairing method names with their optimal weights.
+#' @returns Named list pairing method names with their optimal weights. This
+#'   can be used as an argument to [ranking()].
 #'
 #' @export
-optimize_weights <- function(results, methods, reference_gene_ids,
-                             target = "mean") {
+optimal_weights <- function(analysis, methods, reference_gene_ids,
+                            target = "mean") {
+    if (!"geposan_analysis" %chin% class(analysis)) {
+        stop("Invalid analyis. Use geposan::analyze().")
+    }
+
     # Create the named list from the factors vector.
     weights <- function(factors) {
         result <- NULL
@@ -55,7 +71,7 @@ optimize_weights <- function(results, methods, reference_gene_ids,
 
     # Compute the target rank of the reference genes when applying the weights.
     target_rank <- function(factors) {
-        data <- ranking(results, weights(factors))
+        data <- ranking(analysis, weights(factors))
 
         data[gene %chin% reference_gene_ids, if (target == "min") {
             min(rank)
diff --git a/man/analyze.Rd b/man/analyze.Rd
index 6d6cf1a..bf4c6a9 100644
--- a/man/analyze.Rd
+++ b/man/analyze.Rd
@@ -14,9 +14,10 @@ function should accept a number between 0.0 and 1.0 for the current
 progress.}
 }
 \value{
-A \link{data.table} with one row for each gene identified by it's ID
-(\code{gene} column). The additional columns contain the resulting scores per
-method and are named after the method IDs.
+An object containing the results of the analysis. It contains a
+\link{data.table} with one row for each gene identified by it's ID (\code{gene}
+column). The additional columns contain the resulting scores per method
+and are named after the method IDs.
 }
 \description{
 Analyze by applying the specified preset.
diff --git a/man/optimize_weights.Rd b/man/optimal_weights.Rd
similarity index 62%
rename from man/optimize_weights.Rd
rename to man/optimal_weights.Rd
index ea03024..0f0fe81 100644
--- a/man/optimize_weights.Rd
+++ b/man/optimal_weights.Rd
@@ -1,13 +1,13 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/ranking.R
-\name{optimize_weights}
-\alias{optimize_weights}
+\name{optimal_weights}
+\alias{optimal_weights}
 \title{Find the best weights to rank the results.}
 \usage{
-optimize_weights(results, methods, reference_gene_ids, target = "mean")
+optimal_weights(analysis, methods, reference_gene_ids, target = "mean")
 }
 \arguments{
-\item{results}{Results from \code{\link[=analyze]{analyze()}} or \code{\link[=ranking]{ranking()}}.}
+\item{analysis}{Results from \code{\link[=analyze]{analyze()}} or \code{\link[=ranking]{ranking()}}.}
 
 \item{methods}{Methods to include in the score.}
 
@@ -17,7 +17,8 @@ optimize_weights(results, methods, reference_gene_ids, target = "mean")
 "max" and results in the respective rank being optimized.}
 }
 \value{
-Named list pairing method names with their optimal weights.
+Named list pairing method names with their optimal weights. This
+can be used as an argument to \code{\link[=ranking]{ranking()}}.
 }
 \description{
 This function finds the optimal parameters to \code{\link[=ranking]{ranking()}} that result in the
diff --git a/man/ranking.Rd b/man/ranking.Rd
index 40b657a..c32a46d 100644
--- a/man/ranking.Rd
+++ b/man/ranking.Rd
@@ -4,14 +4,20 @@
 \alias{ranking}
 \title{Rank the results by computing a score.}
 \usage{
-ranking(results, weights)
+ranking(analysis, weights)
 }
 \arguments{
-\item{results}{Results from \code{\link[=analyze]{analyze()}}.}
+\item{analysis}{Analysis object resulting from \code{\link[=analyze]{analyze()}}.}
 
-\item{weights}{Named list pairing method names with weighting factors.}
+\item{weights}{Named list pairing method names with weighting factors. Only
+methods that are contained within this list will be included.}
+}
+\value{
+A ranking object. The object extends the analysis with additional
+columns containing the \code{score} and the \code{rank} of each gene. It will be
+ordered by rank.
 }
 \description{
-This function takes the result from \code{\link[=analyze]{analyze()}} and creates a score by
+This function takes the result of \code{\link[=analyze]{analyze()}} and creates a score by
 computing a weighted mean across the different methods' results.
 }