From c6ca93b009f221ed0197fd172edef0c2b34e51b5 Mon Sep 17 00:00:00 2001
From: Elias Projahn <elias@johrpan.de>
Date: Wed, 22 Jun 2022 11:20:39 +0200
Subject: [PATCH] Allow customizing method metadata

---
 R/method_adjacency.R         | 15 +++++++++++----
 R/method_clustering.R        | 14 ++++++++++----
 R/method_correlation.R       | 14 ++++++++++----
 R/method_neural.R            | 16 ++++++++++++----
 R/method_proximity.R         | 14 ++++++++++----
 R/method_species_adjacency.R | 14 ++++++++++----
 man/adjacency.Rd             | 14 +++++++++++++-
 man/clustering.Rd            | 13 ++++++++++++-
 man/correlation.Rd           | 13 ++++++++++++-
 man/neural.Rd                | 15 ++++++++++++++-
 man/proximity.Rd             | 13 ++++++++++++-
 man/species_adjacency.Rd     | 14 +++++++++++++-
 12 files changed, 139 insertions(+), 30 deletions(-)

diff --git a/R/method_adjacency.R b/R/method_adjacency.R
index 2ece9e6..de0c68c 100644
--- a/R/method_adjacency.R
+++ b/R/method_adjacency.R
@@ -28,6 +28,9 @@ densest <- function(data) {
 #' combined. The resulting value is compared to the reference genes and
 #' determines the gene's score in relation to other genes.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
 #' @param distance_estimate A function that will be used to summarize the
 #'   distance values for each gene. See [densest()] for the default
 #'   implementation.
@@ -39,11 +42,15 @@ densest <- function(data) {
 #' @seealso [species_adjacency()]
 #'
 #' @export
-adjacency <- function(distance_estimate = densest, summarize = stats::median) {
+adjacency <- function(id = "adjacency",
+                      name = "Adjacency",
+                      description = "Adjacency to reference genes",
+                      distance_estimate = densest,
+                      summarize = stats::median) {
   method(
-    id = "adjacency",
-    name = "Adjacency",
-    description = "Adjacency to reference genes",
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/R/method_clustering.R b/R/method_clustering.R
index 18016d4..a318a90 100644
--- a/R/method_clustering.R
+++ b/R/method_clustering.R
@@ -70,16 +70,22 @@ clusteriness <- function(data,
 #' The result will be cached and can be reused for different presets, because
 #' it is independent of the reference genes in use.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
+#'
 #' @return An object of class `geposan_method`.
 #'
 #' @seealso [clusteriness()]
 #'
 #' @export
-clustering <- function() {
-  method(
-    id = "clustering",
+clustering <- function(id = "clustering",
     name = "Clustering",
-    description = "Clustering of genes",
+                       description = "Clustering of genes") {
+  method(
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/R/method_correlation.R b/R/method_correlation.R
index 1b69861..4b61bd8 100644
--- a/R/method_correlation.R
+++ b/R/method_correlation.R
@@ -1,5 +1,8 @@
 #' Score genes based on their correlation with the reference genes.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
 #' @param summarize A function for combining the different correlation
 #'   coefficients into one metric. By default, [stats::median()] is used. Other
 #'   suggested options include [max()] and [mean()].
@@ -7,11 +10,14 @@
 #' @return An object of class `geposan_method`.
 #'
 #' @export
-correlation <- function(summarize = stats::median) {
+correlation <- function(id = "correlation",
+                        name = "Correlation",
+                        description = "Correlation with reference genes",
+                        summarize = stats::median) {
   method(
-    id = "correlation",
-    name = "Correlation",
-    description = "Correlation with reference genes",
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/R/method_neural.R b/R/method_neural.R
index dafd0cf..0a29eb6 100644
--- a/R/method_neural.R
+++ b/R/method_neural.R
@@ -1,5 +1,8 @@
 #' Find genes by training and applying a neural network.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
 #' @param seed The seed will be used to make the results reproducible.
 #' @param n_models This number specifies how many sets of training data should
 #'   be created. For each set, there will be a model trained on the remaining
@@ -14,11 +17,16 @@
 #' @return An object of class `geposan_method`.
 #'
 #' @export
-neural <- function(seed = 180199, n_models = 5, control_ratio = 0.5) {
+neural <- function(id = "neural",
+                   name = "Neural",
+                   description = "Assessment by neural network",
+                   seed = 180199,
+                   n_models = 5,
+                   control_ratio = 0.5) {
   method(
-    id = "neural",
-    name = "Neural",
-    description = "Assessment by neural network",
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/R/method_proximity.R b/R/method_proximity.R
index 20a6d55..f5d7713 100644
--- a/R/method_proximity.R
+++ b/R/method_proximity.R
@@ -3,6 +3,9 @@
 #' A score will be given to each gene such that 0.0 corresponds to the maximal
 #' distance across all genes and 1.0 corresponds to a distance of 0.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
 #' @param summarize A function for combining the different proximities into one
 #'   metric. By default, [stats::median()] is used. Other suggested options
 #'   include [min()] and [mean()].
@@ -10,11 +13,14 @@
 #' @return An object of class `geposan_method`.
 #'
 #' @export
-proximity <- function(summarize = stats::median) {
+proximity <- function(id = "proximity",
+                      name = "Proximity",
+                      description = "Proximity to telomeres",
+                      summarize = stats::median) {
   method(
-    id = "proximity",
-    name = "Proximity",
-    description = "Proximity to telomeres",
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/R/method_species_adjacency.R b/R/method_species_adjacency.R
index 76f06b5..0b57ba6 100644
--- a/R/method_species_adjacency.R
+++ b/R/method_species_adjacency.R
@@ -4,6 +4,9 @@
 #' to the reference genes within that species. Afterwards, the results are
 #' summarized across species and determine the gene's score.
 #'
+#' @param id Unique ID for the method and its results.
+#' @param name Human readable name for the method.
+#' @param description Method description.
 #' @param distance_estimate Function for combining the distance differences
 #'   within one species.
 #' @param summarize Function for summarizing the distance values across species.
@@ -13,12 +16,15 @@
 #' @seealso [adjacency()]
 #'
 #' @export
-species_adjacency <- function(distance_estimate = stats::median,
+species_adjacency <- function(id = "species_adjacency",
+                              name = "Species adj.",
+                              description = "Species adjacency",
+                              distance_estimate = stats::median,
                               summarize = stats::median) {
   method(
-    id = "species_adjacency",
-    name = "Species adj.",
-    description = "Species adjacency",
+    id = id,
+    name = name,
+    description = description,
     function(preset, progress) {
       species_ids <- preset$species_ids
       gene_ids <- preset$gene_ids
diff --git a/man/adjacency.Rd b/man/adjacency.Rd
index a1437d8..a5de928 100644
--- a/man/adjacency.Rd
+++ b/man/adjacency.Rd
@@ -4,9 +4,21 @@
 \alias{adjacency}
 \title{Score genes based on their proximity to the reference genes.}
 \usage{
-adjacency(distance_estimate = densest, summarize = stats::median)
+adjacency(
+  id = "adjacency",
+  name = "Adjacency",
+  description = "Adjacency to reference genes",
+  distance_estimate = densest,
+  summarize = stats::median
+)
 }
 \arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
+
 \item{distance_estimate}{A function that will be used to summarize the
 distance values for each gene. See \code{\link[=densest]{densest()}} for the default
 implementation.}
diff --git a/man/clustering.Rd b/man/clustering.Rd
index 55ab855..a594c00 100644
--- a/man/clustering.Rd
+++ b/man/clustering.Rd
@@ -4,7 +4,18 @@
 \alias{clustering}
 \title{Process genes clustering their distance to telomeres.}
 \usage{
-clustering()
+clustering(
+  id = "clustering",
+  name = "Clustering",
+  description = "Clustering of genes"
+)
+}
+\arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
 }
 \value{
 An object of class \code{geposan_method}.
diff --git a/man/correlation.Rd b/man/correlation.Rd
index 8732a4a..a8e26b4 100644
--- a/man/correlation.Rd
+++ b/man/correlation.Rd
@@ -4,9 +4,20 @@
 \alias{correlation}
 \title{Score genes based on their correlation with the reference genes.}
 \usage{
-correlation(summarize = stats::median)
+correlation(
+  id = "correlation",
+  name = "Correlation",
+  description = "Correlation with reference genes",
+  summarize = stats::median
+)
 }
 \arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
+
 \item{summarize}{A function for combining the different correlation
 coefficients into one metric. By default, \code{\link[stats:median]{stats::median()}} is used. Other
 suggested options include \code{\link[=max]{max()}} and \code{\link[=mean]{mean()}}.}
diff --git a/man/neural.Rd b/man/neural.Rd
index 671494c..c7962ea 100644
--- a/man/neural.Rd
+++ b/man/neural.Rd
@@ -4,9 +4,22 @@
 \alias{neural}
 \title{Find genes by training and applying a neural network.}
 \usage{
-neural(seed = 180199, n_models = 5, control_ratio = 0.5)
+neural(
+  id = "neural",
+  name = "Neural",
+  description = "Assessment by neural network",
+  seed = 180199,
+  n_models = 5,
+  control_ratio = 0.5
+)
 }
 \arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
+
 \item{seed}{The seed will be used to make the results reproducible.}
 
 \item{n_models}{This number specifies how many sets of training data should
diff --git a/man/proximity.Rd b/man/proximity.Rd
index f8c2768..d75cc2b 100644
--- a/man/proximity.Rd
+++ b/man/proximity.Rd
@@ -4,9 +4,20 @@
 \alias{proximity}
 \title{Score the distance of genes to the telomeres across species.}
 \usage{
-proximity(summarize = stats::median)
+proximity(
+  id = "proximity",
+  name = "Proximity",
+  description = "Proximity to telomeres",
+  summarize = stats::median
+)
 }
 \arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
+
 \item{summarize}{A function for combining the different proximities into one
 metric. By default, \code{\link[stats:median]{stats::median()}} is used. Other suggested options
 include \code{\link[=min]{min()}} and \code{\link[=mean]{mean()}}.}
diff --git a/man/species_adjacency.Rd b/man/species_adjacency.Rd
index bdfaba6..d2b64bd 100644
--- a/man/species_adjacency.Rd
+++ b/man/species_adjacency.Rd
@@ -4,9 +4,21 @@
 \alias{species_adjacency}
 \title{Score genes based on their adjacency to the reference genes within species.}
 \usage{
-species_adjacency(distance_estimate = stats::median, summarize = stats::median)
+species_adjacency(
+  id = "species_adjacency",
+  name = "Species adj.",
+  description = "Species adjacency",
+  distance_estimate = stats::median,
+  summarize = stats::median
+)
 }
 \arguments{
+\item{id}{Unique ID for the method and its results.}
+
+\item{name}{Human readable name for the method.}
+
+\item{description}{Method description.}
+
 \item{distance_estimate}{Function for combining the distance differences
 within one species.}