Package 'BioTooltipR'

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 = "2.3.2", 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 anchor.
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 and click 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 anchor.

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

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

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

---