Use jq to efficiently extract annotationID description

R/dropdowns.R

@@ -211,6 +211,14 @@ getEnrichmentsModels <- function(study, libraries = NULL) {
 #' \code{\link{addEnrichments}}. Any optional tooltips correspond to the
 #' descriptions added with \code{\link{addAnnotations}}.
 #'
+#' @param useJqIfAvailable Use \code{jq} to obtain the description tooltip of
+#'   each annotationID. If explicitly set to \code{FALSE} (or if \code{jq} is
+#'   not available), then the slower \code{\link{getAnnotations}} is used. This
+#'   can be controlled using the package option
+#'   \code{OmicNavigator.useJqIfAvailable}. The default is \code{TRUE}. To
+#'   disable the use of \code{jq}, add
+#'   \code{options(OmicNavigator.useJqIfAvailable = FALSE)} to your script or to
+#'   your \code{.Rprofile}.
 #' @inherit shared-dropdowns params return
 #' @inherit getInstalledStudies params
 #'
@@ -221,7 +229,12 @@ getEnrichmentsModels <- function(study, libraries = NULL) {
 #'   \code{\link{addAnnotations}}
 #'
 #' @export
-getEnrichmentsAnnotations <- function(study, modelID, libraries = NULL) {
+getEnrichmentsAnnotations <- function(
+    study,
+    modelID,
+    useJqIfAvailable = getOption("OmicNavigator.useJqIfAvailable", default = TRUE),
+    libraries = NULL
+) {
   if (!is.character(study)) {
     stop("Only installed study packages are supported")
   }
@@ -237,11 +250,45 @@ getEnrichmentsAnnotations <- function(study, modelID, libraries = NULL) {
   # Check for available tooltips added via addAnnotations(). If not available,
   # use the annotationID itself for the tooltip
   for (annotationID in modelAnnotations) {
-    annotationDisplay <- getAnnotations(study, annotationID = annotationID, quiet = TRUE, libraries = libraries)
-    annotationDisplay <- annotationDisplay[["description"]]
+    if (useJqIfAvailable && nchar(Sys.which("jq")) > 0) {
+      annotationDisplay <- getAnnotationDisplayJq(
+        onDirectory = onDirectory,
+        annotationID = annotationID
+      )
+    } else {
+      annotationDisplay <- getAnnotations(
+        study = study,
+        annotationID = annotationID,
+        quiet = TRUE,
+        libraries = libraries
+      )
+      annotationDisplay <- annotationDisplay[["description"]]
+    }
     if (isEmpty(annotationDisplay)) annotationDisplay <- annotationID
     dropdown[[annotationID]] <- annotationDisplay
   }
 
   return(dropdown)
 }
+
+# Use jq to efficiently extract "description" from potentially large JSON file
+#
+# onDirectory - path to OmicNavigator directory from getDirectory()
+# annotationID - the annotationID for getting the description
+getAnnotationDisplayJq <- function(onDirectory, annotationID) {
+  executable <- "jq"
+  flags <- "--raw-output"
+  filters <- ".description"
+  jsonfile <- paste0(annotationID, ".json")
+  jsonpath <- file.path(onDirectory, "annotations", jsonfile)
+
+  if (!file.exists(jsonpath)) return(list())
+
+  annotationDisplay <- system2(
+    command = executable,
+    args = c(flags, filters, shQuote(jsonpath)),
+    stdout = TRUE
+  )
+
+  return(annotationDisplay)
+}

R/zzz.R

@@ -39,7 +39,8 @@ appPackages <- c(
 .onLoad <- function(libname, pkgname) {
   # Default options
   onOptions <- list(
-    OmicNavigator.prefix = OmicNavigatorPrefix
+    OmicNavigator.prefix = OmicNavigatorPrefix,
+    OmicNavigator.useJqIfAvailable = TRUE
   )
 
   # Only set defaults for OmicNavigator options that have not been set by user
@@ -94,6 +95,17 @@ appPackages <- c(
 #' options(OmicNavigator.prefix = "OmicNavigatorStudy")
 #' }
 #'
+#' By default OmicNavigator will attempt to use the command-line tool \code{jq}
+#' to obtain the description of each annotationID when the app calls
+#' \code{\link{getEnrichmentsAnnotations}}. If this causes a problem, you can
+#' disable this behavior via the package option
+#' \code{OmicNavigator.useJqIfAvailable}. To do so, add the following line to
+#' your \code{.Rprofile} file.
+#'
+#' \preformatted{
+#' options(OmicNavigator.useJqIfAvailable = FALSE)
+#' }
+#'
 #' @importFrom data.table ":=" "%chin%" .N as.data.table chmatch data.table
 #'   dcast.data.table fread fwrite melt merge.data.table setcolorder setDF setDT
 #'   setnames setorderv

inst/tinytest/testDropdowns.R

@@ -10,6 +10,9 @@ library(OmicNavigator)
 tmplib <- tempfile()
 dir.create(tmplib)
 
+tmplibSpace <- tempfile("a space")
+dir.create(tmplibSpace)
+
 # Minimal study ----------------------------------------------------------------
 
 testStudyMinObj <- OmicNavigator:::testStudyMinimal()
@@ -393,6 +396,82 @@ expect_error_xl(
   "Only installed study packages are supported"
 )
 
+# jq ---------------------------------------------------------------------------
+
+# The results of `getEnrichmentsAnnotations()` should be identical whether or
+# not `jq` is used
+
+expect_equal_xl(
+  getEnrichmentsAnnotations(
+    study = testStudyMinName,
+    modelID = "model_01",
+    useJqIfAvailable = TRUE,
+    libraries = tmplib
+  ),
+  getEnrichmentsAnnotations(
+    study = testStudyMinName,
+    modelID = "model_01",
+    useJqIfAvailable = FALSE,
+    libraries = tmplib
+  )
+)
+
+expect_equal_xl(
+  getEnrichmentsAnnotations(
+    study = testStudyName,
+    modelID = "model_01",
+    useJqIfAvailable = TRUE,
+    libraries = tmplib
+  ),
+  getEnrichmentsAnnotations(
+    study = testStudyName,
+    modelID = "model_01",
+    useJqIfAvailable = FALSE,
+    libraries = tmplib
+  )
+)
+
+expect_identical_xl(
+  getEnrichmentsAnnotations(
+    study = emptyStudyName,
+    modelID = "model_01",
+    useJqIfAvailable = TRUE,
+    libraries = tmplib
+  ),
+  getEnrichmentsAnnotations(
+    study = emptyStudyName,
+    modelID = "model_01",
+    useJqIfAvailable = FALSE,
+    libraries = tmplib
+  )
+)
+
+# getAnnotationDisplayJq() can handle a space in the file path
+
+testStudySpaceName <- "testDropdownsSpace"
+testStudySpaceObj <- OmicNavigator:::testStudy(name = testStudySpaceName)
+suppressMessages(installStudy(testStudySpaceObj, library = tmplibSpace))
+
+expect_equal_xl(
+  getEnrichmentsAnnotations(
+    study = testStudySpaceName,
+    modelID = "model_01",
+    useJqIfAvailable = TRUE,
+    libraries = tmplibSpace
+  ),
+  list(
+    annotation_01 = "Terms from annotation_01",
+    annotation_02 = "Terms from annotation_02",
+    annotation_03 = "Terms from annotation_03"
+  )
+)
+
+# The package option "OmicNavigator.useJqIfAvailable" should be set when the
+# package is loaded
+
+expect_true_xl(is.logical(getOption("OmicNavigator.useJqIfAvailable")))
+
 # Teardown ---------------------------------------------------------------------
 
 unlink(tmplib, recursive = TRUE, force = TRUE)
+unlink(tmplibSpace, recursive = TRUE, force = TRUE)