Merge pull request #62 from iSEE/runr_full_implementation_draft

Runr full implementation draft

.Rbuildignore

@@ -10,3 +10,4 @@
 ^docs$
 ^doc$
 ^Meta$
+^TODO\.md$

DESCRIPTION

@@ -1,18 +1,18 @@
 Package: iSEEindex
 Title: iSEE extension for a landing page to a custom collection of data sets
-Version: 1.3.1
-Date: 2024-10-01
+Version: 1.3.2
+Date: 2024-10-03
 Authors@R: 
     c(person("Kevin", "Rue-Albrecht", email = "[email protected]",
              role = c("aut", "cre"),
              comment = c(ORCID = "0000-0003-3899-3872")),
-    person("Thomas", "Sandmann", email = "[email protected]",
+      person("Thomas", "Sandmann", email = "[email protected]",
              role = c("ctb"),
              comment = c(ORCID = "0000-0002-6601-8890")),
-    person("Federico", "Marini", email="[email protected]",
-             role="aut",
+      person("Federico", "Marini", email = "[email protected]",
+             role = "aut",
              comment = c(ORCID = '0000-0003-3252-7758')),
-    person("Denali Therapeutics", role = c("fnd")))
+      person("Denali Therapeutics", role = c("fnd")))
 Description: This package provides an interface to any collection of data sets
     within a single iSEE web-application. The main functionality of this package is
     to define a custom landing page allowing app maintainers to list a custom
@@ -25,7 +25,7 @@ biocViews: Software,
     Infrastructure
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Depends:
     SummarizedExperiment,
     SingleCellExperiment
@@ -48,6 +48,8 @@ Suggests:
     knitr,
     RefManageR,
     rmarkdown,
+    markdown,
+    scRNAseq,
     sessioninfo,
     testthat (>= 3.0.0),
     yaml

NAMESPACE

@@ -4,12 +4,14 @@ export(iSEEindex)
 export(iSEEindexHttpsResource)
 export(iSEEindexLocalhostResource)
 export(iSEEindexRcallResource)
+export(iSEEindexRunrResource)
 export(iSEEindexS3Resource)
 export(precache)
 exportClasses(iSEEindexHttpsResource)
 exportClasses(iSEEindexLocalhostResource)
 exportClasses(iSEEindexRcallResource)
 exportClasses(iSEEindexResource)
+exportClasses(iSEEindexRunrResource)
 exportClasses(iSEEindexS3Resource)
 exportMethods(precache)
 exportMethods(show)

NEWS.md

@@ -1,3 +1,8 @@
+# iSEEindex 1.3.2
+
+* Added a full implementation of the `runr` resource class, defining its behavior with simple heuristics based on the fact that users can now also provide not just a path but the call to the command of R to be run (therefore, the name `runr`) to obtain an object to explore.
+  A typical use case would be to deploy a collection of datasets from a data package.
+
 # iSEEindex 1.3.1
 
 * Version bump to rebuild classes derived from `DotPlot`.

R/iSEEindex.R

@@ -6,56 +6,74 @@
 #' states prepared by the app maintainer.
 #'
 #' @section Data Sets:
-#' The function passed to the argument `FUN.datasets` must return a `list` that contains metadata about the available data sets.
+#' The function passed to the argument `FUN.datasets` must return a `list` that
+#' contains metadata about the available data sets.
 #'
 #' For each data set, required metadata are:
 #'
 #' \describe{
 #' \item{id}{A unique identifier for the data set.}
-#' \item{title}{A short human-readable title for the data set, displayed in the 'Info' panel when the data set is selected.}
-#' \item{uri}{A Uniform Resource Identifier (URI) that indicates the location of the data file that contains the data set.}
-#' \item{description}{A more detailed description of the data set, displayed in the 'Info' panel when the data set is selected.}
+#' \item{title}{A short human-readable title for the data set, displayed in the
+#' 'Info' panel when the data set is selected.}
+#' \item{uri}{A Uniform Resource Identifier (URI) that indicates the location of
+#' the data file that contains the data set.}
+#' \item{description}{A more detailed description of the data set, displayed in
+#' the 'Info' panel when the data set is selected.}
 #' }
 #'
 #' Example:
 #'
 #' ```
 #' list(
 #'   list(
-#'      id = "dataset01",
-#'      title = "Dataset 01",
-#'      uri = "https://example.com/1.rds",
-#'      description = "My first data set."
+#'     id = "dataset01",
+#'     title = "Dataset 01",
+#'     uri = "https://example.com/1.rds",
+#'     description = "My first data set."
 #'   ),
 #'   list(
-#'      id = "dataset02",
-#'      title = "Dataset 02",
-#'      uri = "https://example.com/1.rds",
-#'      description = "My second data set."
+#'     id = "dataset02",
+#'     title = "Dataset 02",
+#'     uri = "https://example.com/1.rds",
+#'     description = "My second data set."
 #'   )
 #' )
 #' ```
 #'
-#' The individual sub-lists may also contain optional named metadata specific to individual [`iSEEindexResource-class`] classes (refer to the help page of those classes for details).
+#' The individual sub-lists may also contain optional named metadata specific to
+#' individual [`iSEEindexResource-class`] classes (refer to the help page of
+#' those classes for details).
 #'
-#' **Important**: The `id` value is used to identify the data set file in the \pkg{BiocFileCache}.
-#' Thus, we recommend using a dedicated `BiocFileCache()` for the app, using the `BiocFileCache(cache)` argument to specify an on-disk location (directory path) for the dedicated cache.
+#' **Important**: The `id` value is used to identify the data set file in the
+#' \pkg{BiocFileCache}.
+#' Thus, we recommend using a dedicated `BiocFileCache()` for the app, using the
+#' `BiocFileCache(cache)` argument to specify an on-disk location (directory
+#' path) for the dedicated cache.
 #'
 #' @section Initial Configurations:
-#' The function passed to the argument `FUN.initial` must return a `list` that contains metadata about the available initial configurations, or `NULL` in the absence of any custom initial configuration (default settings will be applied to all data sets.).
+#' The function passed to the argument `FUN.initial` must return a `list` that
+#' contains metadata about the available initial configurations, or `NULL` in
+#' the absence of any custom initial configuration (default settings will be
+#' applied to all data sets.).
 #'
 #' For each initial configuration, required metadata are:
 #'
 #' \describe{
 #' \item{id}{A unique identifier for the initial configuration.}
-#' \item{title}{A short human-readable title for the initial configuration, representing the initial configuration in the 'Initial settings' dropdown menu.}
-#' \item{uri}{A Uniform Resource Identifier (URI) that indicates the location of the R script that contains the initial configuration.}
-#' \item{description}{A more detailed description of the initial configuration, displayed in the 'Configure and launch' panel when the initial configuration is selected.}
+#' \item{title}{A short human-readable title for the initial configuration,
+#' representing the initial configuration in the 'Initial settings' dropdown menu.}
+#' \item{uri}{A Uniform Resource Identifier (URI) that indicates the location of
+#' the R script that contains the initial configuration.}
+#' \item{description}{A more detailed description of the initial configuration,
+#' displayed in the 'Configure and launch' panel when the initial configuration
+#' is selected.}
 #' }
-#' 
+#'
 #' For each initial configuration, optional metadata are:
 #' \describe{
-#' \item{datasets}{A series of data set identifiers for which the configuration should be made available. If missing, the configuration will be available for all data sets.}
+#' \item{datasets}{A series of data set identifiers for which the configuration
+#' should be made available. If missing, the configuration will be available for
+#' all data sets.}
 #' }
 #'
 #' Example:
@@ -78,7 +96,9 @@
 #' )
 #' ```
 #'
-#' The individual sub-lists may also contain additional optional named metadata specific to individual [`iSEEindexResource-class`] classes (refer to the help page of those classes for details).
+#' The individual sub-lists may also contain additional optional named metadata
+#' specific to individual [`iSEEindexResource-class`] classes (refer to the help
+#' page of those classes for details).
 #'
 #' @param bfc An [BiocFileCache()] object.
 #' @param FUN.datasets A function that returns a `list` of metadata for
@@ -97,7 +117,8 @@
 #' @param body.header UI element to display \emph{above} the main landing page body.
 #' @param body.footer UI element to display \emph{below} the main landing page body.
 #'
-#' @return An [iSEE::iSEE()] app with a custom landing page using a [BiocFileCache()] to cache a selection of data sets.
+#' @return An [iSEE::iSEE()] app with a custom landing page using a
+#' [BiocFileCache()] to cache a selection of data sets.
 #'
 #' @author Kevin Rue-Albrecht
 #'
@@ -107,17 +128,9 @@
 #' @importFrom utils packageVersion
 #'
 #' @examples
-#' ##
-#' # BiocFileCache ----
-#' ##
-#' 
-#' library(BiocFileCache)
+#' library("BiocFileCache")
 #' bfc <- BiocFileCache(cache = tempdir())
 #'
-#' ##
-#' # iSEEindex ----
-#' ##
-#'
 #' dataset_fun <- function() {
 #'     x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
 #'     x$datasets
@@ -133,7 +146,90 @@
 #' if (interactive()) {
 #'     shiny::runApp(app, port = 1234)
 #' }
-iSEEindex <- function(bfc, FUN.datasets, FUN.initial = NULL, default.add = TRUE, default.position = c("first", "last"), app.title = NULL, body.header = NULL, body.footer = NULL) {
+#'
+#' ## Alternatively, with the example based on using runr calls
+#'
+#' dataset_fun_tonsils <- function() {
+#'     x <- yaml::read_yaml(
+#'         system.file("tonsils_example", "tonsil_package.yml", package = "iSEEindex")
+#'     )
+#'     x$datasets
+#' }
+#' initial_fun_tonsils <- function() {
+#'     x <- yaml::read_yaml(
+#'         system.file("tonsils_example", "tonsil_package.yml", package = "iSEEindex")
+#'     )
+#'     x$initial
+#' }
+#'
+#' library("shiny")
+#' header_tonsils <- fluidRow(
+#'   shinydashboard::box(
+#'     width = 12, collapsible = TRUE, collapsed = TRUE,
+#'     title = "How to explore the Tonsil Atlas datasets",
+#'     includeMarkdown(
+#'       system.file("tonsils_example", "header_tonsils.md", package = "iSEEindex")
+#'     )
+#'   )
+#' )
+#' footer_tonsils <- fluidRow(
+#'   shinydashboard::box(
+#'     width = 12,
+#'     includeMarkdown(
+#'       system.file("tonsils_example", "footer_tonsils.md", package = "iSEEindex")
+#'     )
+#'   )
+#' )
+#'
+#' app_tonsils <- iSEEindex(bfc,
+#'     dataset_fun_tonsils,
+#'     initial_fun_tonsils,
+#'     default.add = TRUE,
+#'     default.position = "last",
+#'     app.title = "iSEE ❤️ Tonsil Data Atlas",
+#'     body.header = header_tonsils,
+#'     body.footer = footer_tonsils)
+#'
+#' if (interactive()) {
+#'     shiny::runApp(app_tonsils, port = 5678)
+#' }
+#'
+#'
+#' ## This example shows that it is possible to mix different types of resources
+#' ## Some provide the path, some directly the object
+#'
+#' dataset_fun_mix <- function() {
+#'     x <- yaml::read_yaml(
+#'         system.file("mixed_resources.yml", package = "iSEEindex")
+#'     )
+#'     x$datasets
+#' }
+#' initial_fun_mix <- function() {
+#'     x <- yaml::read_yaml(
+#'         system.file("mixed_resources.yml", package = "iSEEindex")
+#'     )
+#'     x$initial
+#' }
+#'
+#' app_mixed <- iSEEindex(bfc,
+#'     dataset_fun_mix,
+#'     initial_fun_mix,
+#'     default.add = TRUE,
+#'     default.position = "last",
+#'     app.title = "iSEE ❤ multiple resource types")
+#'
+#' if (interactive()) {
+#'     shiny::runApp(app_mixed, port = 4242)
+#' }
+#'
+iSEEindex <- function(bfc,
+                      FUN.datasets,
+                      FUN.initial = NULL,
+                      default.add = TRUE,
+                      default.position = c("first", "last"),
+                      app.title = NULL,
+                      body.header = NULL,
+                      body.footer = NULL) {
     stopifnot(is(bfc, "BiocFileCache"))
     if (is.null(FUN.initial)) {
         FUN.initial <- function() NULL
@@ -146,13 +242,20 @@ iSEEindex <- function(bfc, FUN.datasets, FUN.initial = NULL, default.add = TRUE,
     }
 
     iSEE(
-        landingPage=.landing_page(bfc, FUN.datasets, FUN.initial, default.add, default.position, body.header, body.footer),
+        landingPage = .landing_page(
+            bfc,
+            FUN.datasets,
+            FUN.initial,
+            default.add,
+            default.position,
+            body.header,
+            body.footer
+        ),
         appTitle = app.title
-        )
+    )
 }
 
 
-
 #' Prepare and Launch the Main App.
 #'
 #' Invokes a function that replaces the landing page by the \pkg{iSEE}
@@ -170,7 +273,7 @@ iSEEindex <- function(bfc, FUN.datasets, FUN.initial = NULL, default.add = TRUE,
 #'
 #' @param FUN A function to initialize the \pkg{iSEE} observer
 #' architecture. Refer to [iSEE::createLandingPage()] for more details.
-#' @param bfc An [BiocFileCache()] object.
+#' @param bfc A [BiocFileCache()] object.
 #' @param session The Shiny session object from the server function.
 #' @param pObjects An environment containing global parameters generated in the
 #' landing page.
@@ -207,7 +310,7 @@ iSEEindex <- function(bfc, FUN.datasets, FUN.initial = NULL, default.add = TRUE,
             } else {
                 initial_id <- pObjects[[.ui_initial]]
                 which_initial <- which(
-                  pObjects$initial_table[[.initial_config_id]] == initial_id & 
+                  pObjects$initial_table[[.initial_config_id]] == initial_id &
                   pObjects$initial_table[[.initial_datasets_id]] == dataset_id
                   )
                 initial_metadata <- as.list(pObjects$initial_table[which_initial, , drop = FALSE])
@@ -244,3 +347,4 @@ iSEEindex <- function(bfc, FUN.datasets, FUN.initial = NULL, default.add = TRUE,
     invisible(NULL)
     # nocov end
 }
+