iSEEindex App — iSEEindex • iSEEindex

Generate an iSEE app that includes a landing page enabling users to choose from a custom set of data sets and initial configuration states prepared by the app maintainer.

Usage

iSEEindex(
  bfc,
  FUN.datasets,
  FUN.initial = NULL,
  default.add = TRUE,
  default.position = c("first", "last"),
  app.title = NULL,
  body.header = NULL,
  body.footer = NULL
)

Arguments

bfc: An BiocFileCache() object.
FUN.datasets: A function that returns a list of metadata for available data sets.
FUN.initial: A function that returns a list of metadata for available initial configuration states.
default.add: Logical scalar indicating whether a default initial configuration should be added as a choice in the Shiny selectizeInput(). See iSEEindex().
default.position: Character scalar indicating whether the default initial configuration should be added as the "first" or "last" option in the Shiny selectizeInput().
app.title: Character string to specify the desired title to be displayed in the main window of the dashboard. Defaults to NULL, which displays some info on the versions of the iSEEindex and iSEE packages.
body.header: UI element to display above the main landing page body.
body.footer: UI element to display below the main landing page body.

Value

An iSEE::iSEE() app with a custom landing page using a BiocFileCache() to cache a selection of data sets.

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:

id: A unique identifier for the data set.
title: A short human-readable title for the data set, displayed in the 'Info' panel when the data set is selected.
uri: A Uniform Resource Identifier (URI) that indicates the location of the data file that contains the data set.
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."
  ),
  list(
    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 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 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.

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.).

For each initial configuration, required metadata are:

id: A unique identifier for the initial configuration.
title: A short human-readable title for the initial configuration, representing the initial configuration in the 'Initial settings' dropdown menu.
uri: A Uniform Resource Identifier (URI) that indicates the location of the R script that contains the initial configuration.
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:

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:

list(
  list(
     id = "config01",
     datasets = c("dataset01")
     title = "Configuration 01",
     uri = "https://example.com/1.R",
     description = "My first configuration."
  ),
  list(
     id = "config02",
     title = "Configuration 02",
     uri = "https://example.com/2.R",
     description = "My second configuration."
  )
)

The individual sub-lists may also contain additional optional named metadata specific to individual iSEEindexResource classes (refer to the help page of those classes for details).

Author

Kevin Rue-Albrecht

Examples

library("BiocFileCache")
#> Loading required package: dbplyr
bfc <- BiocFileCache(cache = tempdir())

dataset_fun <- function() {
    x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
    x$datasets
}

initial_fun <- function() {
    x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
    x$initial
}

app <- iSEEindex(bfc, dataset_fun, initial_fun)

if (interactive()) {
    shiny::runApp(app, port = 1234)
}

## 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 loves the 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 loves multiple resource types")

if (interactive()) {
    shiny::runApp(app_mixed, port = 4242)
}