vaRRI - Visual Annotation of RNA–RNA Interactions

Visualise and annotate RNA–RNA interactions directly in the browser — no backend processing or build tools required.

---

Table of Contents

1. Overview
2. Examples from Literature
3. Project Structure
4. Quick Start
5. npm Package
6. Input Website
7. URL Parameters & Sharing
8. Embedding / Web Integration
9. Input Format Reference
10. JavaScript Library API
11. Release Process
12. License

---

Overview and Objective

vaRRI is a pure JavaScript library to visualize the base pairing of RNA-RNA interactions (RRIs) as 2D diagrams with additional annotation like

• coloring by sequence or loop type,
• highlighting of RRI regions,
• subsequence highlightings,
• point mutation information or
• probability profile representations.

It can be used in web applications or served locally with any static HTTP server, without a build step.

Use cases include

Note

• production of publication-ready RRI figures that can be postprocessed,
• interactive visualizations of RRI data,
  • e.g. forwarded from web applications via URL parameters,
• embedding of RRI visualizations in external web pages, e.g. in documentation, blogs, or web tools, and
• educational purposes, e.g. in online courses or tutorials.

Important

If you like it, please cite it!

Given two sequences and the RRI secondary-structure encoding in dot-bracket notation, vaRRI renders them with a native D3 canvas and applies vaRRI's annotations. RNA layout algorithms extracted from Fornac retain their attribution; the viewer does not load the Fornac runtime.

---

Examples from Literature reproduced with vaRRI

To showcase the capabilities of vaRRI, we provide a collection of examples from the literature that have been reproduced using vaRRI. The examples can be loaded directly in the input website via the Example dropdown.

---

Project Structure

vaRRI/
├── src/
│   ├── main.js             # Native browser entry
│   ├── vaRRI.js            # Public native-module compatibility entry
│   ├── core/
│   │   ├── model/          # DOM-free validation, indexing, annotations, URL state
│   │   ├── canvas/         # Instance-scoped D3 rendering, layout, export
│   │   └── vendor/         # Pinned D3 runtime and license
│   └── ui/                 # Native Vue components, controllers, and plain form state
├── docs/                   # Force graph and architecture documentation
├── tests/                  # Model/UI/force tests and original visual fixtures
├── scripts/                # Distribution and verification tools
├── index.html              # Source viewer and native import map
├── style.css               # Viewer styles
├── fornac/                 # Compatible CSS and retained upstream source/license
└── MIGRATION_PROTOCOL.md   # Phase gates, decisions, and verification evidence

---

Quick Start

Warning

AI-Generated Code Disclaimer: The source code of this project was mainly generated by an AI and may contain errors or inaccuracies. It is recommended to review and test the code thoroughly before using it in a production environment.

The easiest way to use vaRRI is via the GitHub pages website:

• https://BackofenLab.github.io/vaRRI

If you want to run the website locally or use the library in your own HTML page, clone the repository or download a ZIP of the project via the Releases section. Serve the checkout over HTTP and open it in a modern browser. Native ES modules need HTTP; no Node.js environment, compilation, or build step is required:

git clone https://github.com/BackofenLab/vaRRI.git
cd vaRRI
python3 -m http.server 8080
# Open http://localhost:8080/index.html

To use the native library in another served page:

<link rel="stylesheet" href="fornac/fornac.css">
<div id="rna"></div>
<script type="module">
  import { createVaRRI } from './src/core/index.js';
  const viewer = createVaRRI();
  await viewer.render('rna', viewer.validate({ sequence: 'ACGU', structure: '(..)' }));
</script>

The core has no Vue dependency and initializes its D3 runtime only when rendering.

npm Package

Install vaRRI in an application with:

npm install varri-js

The npm package remains varri-js; the GitHub repository and project branding are vaRRI. Version 1.0.2 includes the updated complete viewer as well as the library.

Open index.html in Browser

After installation via npm, you find the vaRRI user interface index.html in the following subfolder

node_modules/varri-js/index.html

Serve this directory over HTTP, then open it with any recent browser.

Local Webserver

Serving the installed viewer requires any static webserver, for example Python 3:

python3 -m http.server 8080 --bind 127.0.0.1 --directory node_modules/varri-js

Open http://localhost:8080/index.html. Applications can serve or copy the whole package directory using their own static-file server, retaining the relative directory layout. The viewer includes example inputs, SVG/PNG export controls, help, citation data and local logos. Use HTTP rather than file:// for native module loading and packaged help/citation data.

The architecture migration is tracked in MIGRATION_PROTOCOL.md.

ESM imports resolve to the native source API. require('varri-js') resolves to the generated CommonJS core bundle; both expose the same library methods. The viewer has a separate public entry:

const viewerPath = require.resolve('varri-js/index.html');

Resolving this path does not start a server; serve its containing directory to make the viewer and its assets available. HTML is a browser document, not a JavaScript module.

Network requirements: the viewer and help page serve Vue, Markdown parsing, D3, and application modules locally. University logos come from www.bioinf.uni-freiburg.de, and the help page uses an external stylesheet and an embedded online example. The citation page can fetch citation data from raw.githubusercontent.com if local files cannot be read. Serve the package over HTTP to load its native modules and local help/citation data.

For classic-script embedding, the distribution includes a standalone core bundle with its own D3 engine. For a page served from an npm-based application:

<link rel="stylesheet" href="node_modules/varri-js/fornac/fornac.css" />
<script src="node_modules/varri-js/dist/varri.min.js"></script>

Applications with a bundler can also consume the API entry point:

const vaRRI = require('varri-js');

The core bundle installs window.vaRRI and includes D3. Serve the compatible fornac/fornac.css stylesheet alongside it; no Fornac runtime is required. The standalone embedding guide explains the downloadable core artifact built by GitHub Actions on every push and release.

Note

The repository does not track node_modules/. If you want to run tests locally, create it after cloning within the project directory using:

npm install
npm test

---

User guides

The viewer guide covers inputs, annotation controls, probability profiles, navigation, and exports. The sharing and input reference covers URL parameters, embedding, dot-bracket notation, and biological indices. Open the complete browser help to read these guides together.

JavaScript Library API

Import src/vaRRI.js as a native ES module, or load dist/varri.min.js as a classic script to expose the global vaRRI API. Both include an independent canvas core; the classic bundle includes D3, and neither entry requires Vue or Fornac scripts.

The src directory provides a detailed vaRRI Library API documentation

---

Release Process

Publishing is automated by .github/workflows/publish-npm.yml. Releases continue to update the existing varri-js npm package. The npm package name is independent of the GitHub repository name; no source files need to be renamed. An owner must configure a GitHub Actions trusted publisher in the varri-js package's npm settings: organization BackofenLab, repository vaRRI, workflow filename publish-npm.yml, no environment name, with direct npm publish allowed. This one-time account action may request 2FA. The workflow uses OIDC and does not require an NPM_TOKEN secret or interactive 2FA for each release. See npm trusted publishing. After the GitHub repository rename, update any existing trusted publisher that still names the old repository to vaRRI. The repository name is case-sensitive.

Merge the workflow changes before creating a release tag on a commit containing them. Every published GitHub release runs the tests, derives the npm version from the release tag, builds and installs a temporary package to verify its contents, and publishes with provenance. Stable releases use the latest npm tag; semantic prerelease versions or GitHub releases marked as prereleases use next. Use npm install varri-js@next to try a prerelease. Use a new, increasing stable version for each stable release: npm versions are immutable, and re-running an already successful publish cannot overwrite that version. Publishing a GitHub release is the trigger; pushing a Git tag alone does not publish the npm package.

Run npm run test:ci and npm run test:package locally before proposing a release. The package check installs the actual tarball in a temporary consumer and checks module exports, viewer asset references, documentation images, and citation data. It also runs in PR CI.

Browser UI checks run in Chromium (npm run test:ui) and Firefox (npm run test:ui:firefox). Install both with npx playwright install --with-deps chromium firefox. To check only PNG export, append -- --png-only. VARRI_BROWSER_PATH and VARRI_BROWSER_CHANNEL can select an installed browser; for stock Firefox use the moz-firefox channel.

Release tags must be valid semantic versions with an optional leading v, for example v1.2.3 or 1.2.3. The workflow changes package.json and package-lock.json only inside the temporary runner, so no release-generated commit is pushed back to main.

---

License

This project is provided under the MIT License, see LICENSE for the licence terms.

The bundled Fornac library (fornac/) is © 2014 Peter Kerpedjiev and is distributed under its own licence.