Gene Tooltips JS

Appearance

Framework Integration ​

Gene Tooltips JS is framework-agnostic. Here's how to correctly initialize it in popular frameworks. The key is to call GeneTooltip.init() after the component has mounted and the DOM elements are available.

WARNING

Some examples are hypothetical and untested. Future releases may include working example files for all, but any that are absent from the examples folder on GitHub should be considered untested and experimental for the time being.

React ​

Use the useEffect hook to initialize the tooltip when the component mounts.

jsx
import React, { useEffect } from 'react';
import GeneTooltip from 'gene-tooltips';
import 'gene-tooltips/dist/css/main.css';

function MyComponent() {
  useEffect(() => {
    // Initialize tooltips on elements with the class '.gene'
    const tooltip = GeneTooltip.init({
        selector: '.gene'
    });
    
    // It's good practice to have a cleanup function,
    // though this library doesn't currently provide a destroy method.
    // return () => tooltip.destroy(); 
  }, []); // Empty dependency array ensures this runs only once

  return (
    <div>
      <p>
        Here is a human gene: <span className="gene" data-species="human">TP53</span>.
      </p>
      <p>
        And a mouse gene: <span className="gene" data-species="mouse">Trp53</span>.
      </p>
    </div>
  );
}

Vue ​

Use the onMounted lifecycle hook in the Composition API.

js
<template>
  <div>
    <p>
      Here is a human gene: <span class="gene" data-species="human">TP53</span>.
    </p>
    <p>
      And a fruitfly gene: <span class="gene" data-species="7227">CycE</span>.
    </p>
  </div>
</template>

<script setup>
import { onMounted } from 'vue';
import GeneTooltip from 'gene-tooltips';
import 'gene-tooltips/dist/gene-tooltips.css';

onMounted(() => {
  GeneTooltip.init({
    selector: '.gene'
  });
});
</script>

Other HTML integrations ​

Gene-Tooltips is framework-agnostic and can be easily integrated into static reports generated by popular data science tools like RMarkdown, Jupyter, and MyST (for Sphinx). The general approach is to load the necessary CSS and JavaScript files from a CDN and then initialize the library.

We'll use the UMD (Universal Module Definition) build, which is designed for this type of browser usage.

Required Files from CDN:

  1. Main CSS: https://cdn.jsdelivr.net/npm/gene-tooltips@latest/dist/gene-tooltips.css
  2. Library JS (UMD): https://cdn.jsdelivr.net/npm/gene-tooltips@latest/dist/gene-tooltips.global.js
  3. Peer Dependency (Ideogram): https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js
  4. Peer Dependency (D3): https://cdn.jsdelivr.net/npm/d3@7

RMarkdown ​

In RMarkdown, you can include raw HTML content in the final document's <head> section using the includes option in the YAML front matter.

  1. Create a file named header.html: Place this file in the same directory as your .Rmd file. It will contain all the CDN links.

    html
    <!-- header.html -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gene-tooltips@latest/dist/gene-tooltips.css">
<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script src="https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gene-tooltips@latest/dist/gene-tooltips.global.js"></script>

  2. Modify your .Rmd file:

    • Add the includes option to your YAML header.
    • Add your gene elements with the correct class and data-species attributes.
    • Add JavaScript at the end of your document to initialize the library as shown in the init_tooltips code chunk below.
    markdown
    ---
title: "Gene Analysis Report"
output:
  html_document:
    includes:
      in_header: header.html
---

Our analysis identified several key genes, including <span class="gene-tooltip" data-species="human">TP53</span> and <span class="gene-tooltip" data-species="mouse">KRAS</span>.

```{r setup, include=FALSE}
# This chunk is just for setup, no output
library(htmltools)
```

```{r init_tooltips, echo=FALSE, results='asis'}
# This is the key chunk. 'results="asis"' tells knitr to treat the
# output as raw HTML/JS and pass it through directly.

tags$script(HTML("
  document.addEventListener('DOMContentLoaded', function() {
    console.log('Initializing GeneTooltip from RMarkdown...');
    GeneTooltip.init({
      selector: '.gene-tooltip',
      theme: 'light',
      prefetch: 'all'
    });
  });
"))
```

TIP

The R Markdown example is available in examples/RMarkdown.

Jupyter Notebooks / JupyterLab ​

In Jupyter, you can use the IPython.display.HTML module to inject CSS and JavaScript directly into the notebook's output.

  1. Create a setup cell: Place this Python code in a cell at the top of your notebook. Running this cell will load all necessary libraries for the entire session.

    python
    from IPython.display import display, HTML

# You can pin to a specific version instead of "latest"
LIB_VERSION = "latest"

# Use doubled curly braces inside JS to avoid f-string syntax errors
html_setup = f"""
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gene-tooltips@{LIB_VERSION}/dist/gene-tooltips.css">

<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script src="https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gene-tooltips@{LIB_VERSION}/dist/gene-tooltips.global.js"></script>

<script>
document.addEventListener('DOMContentLoaded', function() {{
    console.log('GeneTooltip library loaded and ready.');
    if (window.GeneTooltip) {{
        console.log('Initializing GeneTooltip...');
        GeneTooltip.init({{
            selector: '.gene-tooltip',
            theme: 'light'
        }});
    }} else {{
        console.warn('GeneTooltip not found on window.');
    }}
}});
</script>
"""

display(HTML(html_setup))

  2. Use Markdown cells for content and a final cell for initialization: You can now write your gene content in standard Markdown cells. In a final code cell, use a "magic" command %%html or %%javascript to run the initialization script.

    Markdown Cell:

    markdown
    ### Analysis Results

The primary gene of interest is **<span class="gene-tooltip" data-species="human">BRCA1</span>**. We also investigated related genes in mouse models, such as **<span class="gene-tooltip" data-species="10090">Brca1</span>**.

    Final Code Cell (JavaScript):

    javascript
    %%javascript
require(['gene-tooltips'], function() {
    GeneTooltip.init({
        selector: '.gene-tooltip',
        theme: 'light'
    });
});

  3. Render the HTML Finally, run jupyter nbconvert --to html ./examples/Jupyter/example.ipynb to render the HTML document.

WARNING

This Jupyter notebook example is available in examples/Jupyter. However, the rendered HTML is full of JavaScript and CSS issues. Consider this a proof of principle that requires more work to implement.

MyST (for Sphinx) ​

MyST provides a {raw} directive that allows you to pass raw HTML directly to the output. This is the easiest way to add the library.

  1. Add a {raw} block to your .md or .myst file: It's best to place this block at the end of the page where you need the tooltips. It will load the libraries and initialize them.

    markdown
    # My Document with Gene Tooltips

Here we discuss the zebrafish gene <span class="gene-tooltip" data-species="zebrafish">sox2</span> and its human ortholog <span class="gene-tooltip" data-species="9606">SOX2</span>.

(other content...)

```{raw} html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gene-tooltips/dist/gene-tooltips.css">
<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script src="https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gene-tooltips/dist/gene-tooltips.global.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', function() {
    GeneTooltip.init({
      selector: '.gene-tooltip',
      theme: 'light',
      // Customize any other options here
    });
  });
</script>
```

    For larger Sphinx projects, the "proper" way is to add the assets to your _static folder and configure them in conf.py, but the {raw} directive is perfect for quick and direct integration.

Vanilla HTML ​

See the simple, minimal example in examples/HTML.