From d23646e0a975077248943958fedb5d32eca93490 Mon Sep 17 00:00:00 2001
From: Elias Projahn <elias@johrpan.de>
Date: Sun, 18 Feb 2024 14:29:23 +0100
Subject: [PATCH] Add more context help

---
 R/comparison_editor.R | 14 +++++++++++++-
 R/methods.R           | 38 ++++++++++++++++++++++++++------------
 R/preset_editor.R     | 24 ++++++++++++++++++++++--
 R/utils.R             | 23 +++++++++++++++++++++++
 4 files changed, 84 insertions(+), 15 deletions(-)

diff --git a/R/comparison_editor.R b/R/comparison_editor.R
index a7c76ef..5dafa0a 100644
--- a/R/comparison_editor.R
+++ b/R/comparison_editor.R
@@ -5,9 +5,21 @@
 comparison_editor_ui <- function(id, options) {
   verticalLayout(
     h5("Comparison"),
+    popover(
+      title = "Comparison genes",
+      help = paste0(
+        "Select your genes of interest to compare their scores with the ",
+        "reference genes. This will not influence the computation of scores, ",
+        "but it will update the visualizations and summary statistics. Select ",
+        "\"Your genes\" and use the other controls below for selecting or ",
+        "pasting the genes. You can also use predefined gene sets for ",
+        "comparison."
+      ),
+      div(class = "label", "Comparison genes")
+    ),
     selectInput(
       NS(id, "comparison_genes"),
-      "Comparison genes",
+      label = NULL,
       choices = c(
         "Your genes",
         "Random genes",
diff --git a/R/methods.R b/R/methods.R
index 2c61526..2c208c2 100644
--- a/R/methods.R
+++ b/R/methods.R
@@ -2,17 +2,38 @@
 methods_ui <- function(id, options) {
   verticalLayout(
     h5("Methods"),
+    popover(
+      title = "Optimization target",
+      help = paste0(
+        "These genes will be used as the target for optimization. This means ",
+        "that the method weights will be automatically adjusted to maximize ",
+        "the scores of this gene set. Select \"Reference genes\", if you want ",
+        "to compare your genes of interest with the reference gene set."
+      ),
+      div(class = "label", "Genes to optimize for")
+    ),
     selectInput(
       NS(id, "optimization_genes"),
-      "Genes to optimize for",
+      label = NULL,
       choices = list(
         "Reference genes" = "reference",
         "Comparison genes" = "comparison"
       )
     ),
+    popover(
+      title = "Optimization target",
+      help = paste0(
+        "This determines how the genes, that were selected for optimization, ",
+        "are combined. For example, \"Mean rank\" optimizes the method ",
+        "weights based on the highest possible mean score across all selected ",
+        "genes and \"First rank\" would always focus on the best performing ",
+        "gene."
+      ),
+      div(class = "label", "Optimization target")
+    ),
     selectInput(
       NS(id, "optimization_target"),
-      "Optimization target",
+      label = NULL,
       choices = list(
         "Mean rank" = "mean",
         "Median rank" = "median",
@@ -23,8 +44,9 @@ methods_ui <- function(id, options) {
     ),
     lapply(options$methods, function(method) {
       verticalLayout(
-        div(
-          style = "display: flex;",
+        popover(
+          title = method$name,
+          help = method$help,
           checkboxInput(
             NS(id, method$id),
             span(
@@ -32,14 +54,6 @@ methods_ui <- function(id, options) {
               class = "control-label"
             ),
             value = TRUE
-          ),
-          div(
-            style = "margin-left: 5px;",
-            bslib::popover(
-              bsicons::bs_icon("question-circle"),
-              title = method$name,
-              method$help
-            )
           )
         ),
         sliderInput(
diff --git a/R/preset_editor.R b/R/preset_editor.R
index 4441bf7..2ddfdf9 100644
--- a/R/preset_editor.R
+++ b/R/preset_editor.R
@@ -17,9 +17,20 @@ preset_editor_ui <- function(id, options) {
 
   verticalLayout(
     h5("Inputs"),
+    popover(
+      title = "Species to include",
+      help = paste0(
+        "This can be used to limit the input dataset to a predefined set of ",
+        "species. Normally, it is reasonable to use all species. So, do not ",
+        "change this unless you have specific reasons to do so. The ",
+        "algorithms will automatically optimize the input dataset by ",
+        "excluding species that do not share enough genes."
+      ),
+      div(class = "label", "Species to include")
+    ),
     selectInput(
       NS(id, "species"),
-      "Species to include",
+      label = NULL,
       choices = species_choices
     ),
     if (!options$locked) {
@@ -36,9 +47,18 @@ preset_editor_ui <- function(id, options) {
         ),
       )
     },
+    popover(
+      title = "Reference genes",
+      help = paste0(
+        "The reference genes are the main input to the computation. They are ",
+        "used for computing some of the scores and for optimizing the weights ",
+        "of the different methods."
+      ),
+      div(class = "label", "Reference genes")
+    ),
     selectInput(
       NS(id, "reference_genes"),
-      "Reference genes",
+      label = NULL,
       choices = gene_choices
     ),
     if (!options$locked) {
diff --git a/R/utils.R b/R/utils.R
index cd2c6db..16323e3 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -3,3 +3,26 @@
 #' @import data.table
 #' @import shiny
 NULL
+
+#' Add a help popover to a control.
+#'
+#' @param title Title of the help popover.
+#' @param help Content of the help popover.
+#' @param child The control to add the popover to.
+#'
+#' @noRd
+popover <- function(title, help, child) {
+  div(
+    style = "display: flex;",
+    child,
+    div(
+      style = "margin-left: 5px;",
+      bslib::popover(
+        bsicons::bs_icon("question-circle"),
+        title = title,
+        help,
+        options = list(offset = c(0, 10))
+      )
+    )
+  )
+}
\ No newline at end of file