Package {BioTooltipR}

Title: Add Bio Tooltips to HTML Reports
Version: 0.1.0
Description: Provides lightweight helpers for adding gene and chemical tooltips to R Markdown, Quarto, Shiny, pkgdown, and other HTML outputs. The package emits small HTML spans with module-specific data attributes and attaches the browser-side 'bio-tooltips' JavaScript and CSS assets through 'htmltools'. Entity lookup and rendering are handled in the browser by 'bio-tooltips'; this package does not query biological databases from R during package checks.
Language: en-US
License: MIT + file LICENSE
URL: https://github.com/mattjmeier/BioTooltipR
BugReports: https://github.com/mattjmeier/BioTooltipR/issues
Encoding: UTF-8
Depends: R (≥ 4.1)
Imports: htmltools, jsonlite, knitr, utils
Suggests: DT, htmlwidgets, plotly, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2026-06-23 15:59:26 UTC; matt
Author: Matthew J. Meier [aut, cre]
Maintainer: Matthew J. Meier <matthew.meier@hc-sc.gc.ca>
Repository: CRAN
Date/Publication: 2026-06-30 10:10:09 UTC

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

See Also

Useful links:

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

genes

Character vector of gene symbols to wrap.

species

Species alias or NCBI taxonomy ID.

selector

CSS selector limiting where wrapping occurs.

include_setup

Include use_bio_tooltips() before the wrapping script.

class

Optional additional CSS class for generated spans.

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

label

Character vector of visible labels.

type

Tooltip type. One of "gene" or "chemical".

query

Optional lookup query. Mostly useful for chemical identifiers.

species

Gene species alias or NCBI taxonomy ID.

scope

Chemical lookup scope, such as "pubchem", "chembl", "chebi", "drugbank", "unii", "inchikey", or "name".

lookup

Optional chemical lookup mode, such as "id" or "best-guess".

class

Optional additional CSS class or full class string. If NULL, the default module class is used.

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 = "1.1.1", local_path = NULL)

Arguments

cdn

Use jsDelivr CDN assets instead of the vendored package assets. If FALSE, the package looks for local assets under ⁠inst/htmltools/bio-tooltips/⁠ or local_path.

version

JavaScript package version. Use a pinned version for reproducible reports.

local_path

Optional path containing bio-tooltips.css and bio-tooltips.global.js.

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

data

A data frame.

...

Passed to DT::datatable(). If callback is supplied, this helper will not override it.

modules

Tooltip modules to initialize.

include_setup

Include use_bio_tooltips() before the widget.

escape

Passed to DT::datatable(). Defaults to FALSE.

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

data

A data frame containing differential-expression results.

gene_col

Gene-symbol column name.

species

Species alias or NCBI taxonomy ID.

sort_by

Optional column name used for sorting.

decreasing

Sort direction.

n

Optional number of rows to keep after sorting.

...

Passed to bt_kable().

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

data

A data frame or object accepted by knitr::kable().

...

Passed to knitr::kable().

modules

Tooltip modules to initialize when include_setup = TRUE.

include_setup

Include use_bio_tooltips() before the table.

format

Table format. Defaults to "html".

escape

Escape HTML? Defaults to FALSE so tooltip spans render.

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

plot

A Plotly htmlwidget.

species

Species alias or NCBI taxonomy ID passed through to the generated gene tooltip span.

gene_source

Plotly point field containing the gene symbol. The default uses key, so build plots with key = ~symbol.

hide_plotly_hover

Suppress Plotly's native hover labels while keeping hover events active.

include_setup

Include use_bio_tooltips() before the widget. Set this to FALSE when the report already calls use_bio_tooltips() once.

class

Optional additional CSS class added to the generated gene span.

Value

An HTML tag list containing the Plotly widget and a cursor-following 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

data

A data frame.

column

Column to transform. May be unquoted or a single string.

query_col

Optional column containing stable lookup values.

scope

Chemical scope or scalar value recycled over rows.

scope_col

Optional column containing chemical scopes.

lookup

Optional chemical lookup mode.

class

Optional additional CSS class.

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

x

Character vector of visible chemical labels.

query

Optional stable lookup value. For example, use a PubChem CID with scope = "pubchem".

scope

Optional lookup scope, such as "pubchem", "chembl", "chebi", "drugbank", "unii", "inchikey", or "name".

lookup

Optional lookup mode, such as "id" or "best-guess".

class

Optional additional CSS class.

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

data

A data frame.

column

Column to transform. May be unquoted or a single string.

species

Species alias or NCBI taxonomy ID.

class

Optional additional CSS class.

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

x

Character vector of gene symbols or labels.

species

Species alias such as "human", "mouse", or a numeric NCBI taxonomy ID. Recycled over x.

class

Optional additional CSS class.

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

data

A data frame.

column

Column to transform. May be unquoted or a single string.

type

Tooltip type: "gene" or "chemical".

species

Species for gene tooltips.

query_col

Optional column containing chemical lookup values.

scope

Chemical scope or scalar value recycled over rows.

scope_col

Optional column containing chemical scopes.

lookup

Optional chemical lookup mode.

class

Optional additional CSS class.

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 = "1.1.1",
  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

modules

Character vector containing "gene", "chemical", or both.

cdn

Use jsDelivr CDN assets instead of the vendored package assets. See bio_tooltips_dependency().

version

JavaScript package version. Use a pinned version for reproducibility.

theme

Tooltip theme passed to Bio Tooltips.

prefetch

Prefetch strategy passed to Bio Tooltips.

gene_selector

CSS selector for gene tooltip elements.

chemical_selector

CSS selector for chemical tooltip elements.

visual_preload

Optional visual dependency warmup strategy for gene visuals. Passed as visualPreload.

debug_timings

Log Bio Tooltips timing diagnostics in the browser.

tooltip_width, tooltip_height

Optional tooltip dimensions.

include_optional_visual_deps

Include dependencies for D3 and Ideogram. The default, "auto", includes them when the gene module is initialized because Bio Tooltips gene visuals use these peer dependencies. Vendored files are used by default and CDN files are used when cdn = TRUE. Use FALSE to opt out, for example when gene visuals are disabled.

d3_version, ideogram_version

Versions used when optional visual dependencies are included.

local_path

Optional local path for vendored Bio Tooltips assets.

Value

An HTML tag list containing dependencies and an initialization script.

Examples

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