Package {BioTooltipR}

BioTooltipR: R helpers for Bio Tooltips in HTML reports

Description

The package provides small R helpers that emit Bio Tooltip HTML spans and attach the browser-side bio-tooltips JavaScript/CSS bundle to HTML documents.

Author(s)

Maintainer: Matthew J. Meier matthew.meier@hc-sc.gc.ca

Authors:

• Matthew J. Meier matthew.meier@hc-sc.gc.ca

See Also

Useful links:

• https://github.com/mattjmeier/BioTooltipR

• Report bugs at https://github.com/mattjmeier/BioTooltipR/issues

Automatically wrap selected gene symbols in rendered HTML

Description

Experimental helper for reports where text has already been rendered. It injects a small browser script that scans selected DOM nodes and wraps a user-supplied vocabulary of gene symbols in Bio Tooltip spans.

Usage

auto_gene_tooltips(
  genes,
  species = "human",
  selector = "p, li, td",
  include_setup = TRUE,
  class = NULL
)

Arguments

Details

This is intentionally opt-in and vocabulary-limited because many gene symbols are ambiguous in prose.

Value

An HTML tag list containing an optional setup tag and wrapping script.

Examples

auto_gene_tooltips(c("TP53", "BRCA1"), selector = ".results")

Create a Bio Tooltip span

Description

Low-level helper used by gene_tt() and chem_tt(). It emits an HTML ⁠<span>⁠ with the classes and ⁠data-*⁠ attributes expected by the JavaScript Bio Tooltips library.

Usage

bio_tooltip_span(
  label,
  type = c("gene", "chemical"),
  query = NULL,
  species = NULL,
  scope = NULL,
  lookup = NULL,
  class = NULL
)

Arguments

Value

An HTML character vector with class html.

Examples

bio_tooltip_span("TP53", type = "gene", species = "human")
bio_tooltip_span("aspirin", type = "chemical", query = "2244", scope = "pubchem")

Bio Tooltips HTML dependency

Description

Creates the htmltools dependency for the browser-side Bio Tooltips bundle.

Usage

bio_tooltips_dependency(cdn = FALSE, version = "2.3.2", local_path = NULL)

Arguments

Value

An htmltools::htmlDependency object.

Render a DT table with Bio Tooltips support

Description

Optional wrapper around DT::datatable() that disables HTML escaping by default and re-initializes tooltips when the table redraws.

Usage

bt_datatable(
  data,
  ...,
  modules = c("gene", "chemical"),
  include_setup = TRUE,
  escape = FALSE
)

Arguments

Value

A DT widget, optionally wrapped in an HTML tag list.

Render a simple differential-expression style table

Description

Convenience helper for common omics reports. It optionally sorts and truncates a results data frame, annotates the gene column, and renders an HTML table.

Usage

bt_deg_table(
  data,
  gene_col = "symbol",
  species = "human",
  sort_by = NULL,
  decreasing = FALSE,
  n = NULL,
  ...
)

Arguments

Value

An HTML table with gene tooltip spans.

Render a kable table with Bio Tooltips support

Description

Wrapper around knitr::kable() that defaults to HTML output with escaping disabled and optionally prepends use_bio_tooltips().

Usage

bt_kable(
  data,
  ...,
  modules = c("gene", "chemical"),
  include_setup = TRUE,
  format = "html",
  escape = FALSE
)

Arguments

Value

An HTML tag list when setup is included; otherwise the result of knitr::kable().

Examples

top_genes <- data.frame(symbol = c("TP53", "BRCA1"))
top_genes <- gene_column(top_genes, symbol)
bt_kable(top_genes)

Add Bio Tooltips gene hover behavior to a Plotly plot

Description

bt_plotly_gene_hover() lets a Plotly widget use Bio Tooltips for gene hover cards. Map the gene symbol into Plotly's key aesthetic, then wrap the widget with this helper.

Usage

bt_plotly_gene_hover(
  plot,
  species = "human",
  gene_source = c("key", "customdata"),
  hide_plotly_hover = TRUE,
  include_setup = TRUE,
  class = NULL
)

Arguments

Details

Hover over a point on desktop, or tap a point on mobile. On screens at or below 600 CSS pixels wide, the tooltip opens as a persistent bottom drawer that stays open until another point is selected, the user taps outside the drawer, drags it closed, or activates its close button.

The helper attaches one bio-tooltips anchor with the programmatic GeneTooltip.attach() API and reuses it as the selected point changes, so repeated renders of the widget do not accumulate listeners.

Value

An HTML tag list containing the Plotly widget and a hidden, fixed-position Bio Tooltip anchor.

Examples

if (requireNamespace("plotly", quietly = TRUE)) {
  genes <- data.frame(symbol = c("TP53", "BRCA1"), x = 1:2, y = 2:3)
  plot <- plotly::plot_ly(
    genes,
    x = ~x,
    y = ~y,
    key = ~symbol,
    type = "scatter",
    mode = "markers"
  )
  bt_plotly_gene_hover(plot, include_setup = FALSE)
}

Add chemical tooltip markup to a data-frame column

Description

Convenience wrapper around tooltip_column() for chemical labels.

Usage

chem_column(
  data,
  column,
  query_col = NULL,
  scope = NULL,
  scope_col = NULL,
  lookup = NULL,
  class = NULL
)

Arguments

Value

data, with the selected column replaced by chemical tooltip HTML.

Examples

chemicals <- data.frame(name = "aspirin", cid = "2244")
chem_column(chemicals, name, query_col = "cid", scope = "pubchem")

Create chemical tooltip spans

Description

chem_tt() vectorizes over chemical labels and emits HTML spans understood by the Bio Tooltips MyChem.info module.

Usage

chem_tt(x, query = NULL, scope = NULL, lookup = NULL, class = NULL)

chemical_tt(x, query = NULL, scope = NULL, lookup = NULL, class = NULL)

chemical_tooltip(x, query = NULL, scope = NULL, lookup = NULL, class = NULL)

Arguments

Value

An HTML character vector with class html.

Examples

chem_tt("aspirin", query = "2244", scope = "pubchem")
chem_tt("caffeine", lookup = "best-guess")

Add gene tooltip markup to a data-frame column

Description

Convenience wrapper around tooltip_column() for gene symbols.

Usage

gene_column(data, column, species = "human", class = NULL)

Arguments

Value

data, with the selected column replaced by gene tooltip HTML.

Examples

top_genes <- data.frame(symbol = c("TP53", "BRCA1"))
gene_column(top_genes, symbol)

Create gene tooltip spans

Description

gene_tt() vectorizes over gene symbols and emits HTML spans understood by the Bio Tooltips MyGene.info module.

Usage

gene_tt(x, species = "human", class = NULL)

gene_tooltip(x, species = "human", class = NULL)

Arguments

Value

An HTML character vector with class html.

Examples

gene_tt("TP53")
gene_tt(c("TP53", "BRCA1"), species = "human")

Add Bio Tooltip markup to a data-frame column

Description

Replaces a selected column with HTML tooltip spans. This is useful before rendering with knitr::kable(escape = FALSE), bt_kable(), or another HTML table system that can render unescaped HTML.

Usage

tooltip_column(
  data,
  column,
  type = c("gene", "chemical"),
  species = "human",
  query_col = NULL,
  scope = NULL,
  scope_col = NULL,
  lookup = NULL,
  class = NULL
)

Arguments

Value

data, with the selected column replaced by HTML strings.

Examples

top_genes <- data.frame(symbol = c("TP53", "BRCA1"), padj = c(0.001, 0.02))
tooltip_column(top_genes, symbol, type = "gene")

Attach and initialize Bio Tooltips

Description

Use this once in an R Markdown, Quarto, Shiny UI, or other HTML-producing context. It attaches the Bio Tooltips CSS/JS dependency and initializes the selected modules after the DOM is ready.

Usage

use_bio_tooltips(
  modules = c("gene", "chemical"),
  cdn = FALSE,
  version = "2.3.2",
  theme = "auto",
  prefetch = "smart",
  gene_selector = ".gene-tooltip",
  chemical_selector = ".chemical-tooltip",
  visual_preload = NULL,
  debug_timings = FALSE,
  tooltip_width = NULL,
  tooltip_height = NULL,
  include_optional_visual_deps = "auto",
  d3_version = "7.9.0",
  ideogram_version = "1.53.0",
  local_path = NULL
)

Arguments

Value

An HTML tag list containing dependencies and an initialization script.

Examples

use_bio_tooltips()
use_bio_tooltips(modules = "gene", theme = "light")