hoodini-viz

v0.2.20

Published

10 days ago

Interactive phylogenetic and genomic visualization library

0High
0Medium
0Low

pentamorfico

visualization genomics phylogenetic tree bioinformatics gene-neighborhood deckgl react

GPU-powered visualization for comparative genomics

🎮 Live Demo · 📦 npm · 📖 Docs

🧬 What is this?

Hoodini-viz is a React library for interactive visualization of comparative genomics data at scale.

It displays phylogenetic trees alongside aligned gene neighborhood tracks, connecting homologous proteins across genomes with curved Bézier links colored by cluster or identity. Syntenic regions are highlighted with nucleotide-level alignments rendered as translucent polygons between tracks.

Each gene is drawn as a directional arrow showing strand orientation, with protein domains overlaid as colored boxes. Click any gene to view its metadata, predict its 3D protein structure on-demand, or explore ncRNA secondary structures with an embedded interactive viewer.

A virtualized data table lets you browse and filter millions of genes, domains, and links. All visual parameters (colors, dimensions, opacities, scales) are adjustable in real-time through the sidebar controls.

💡 Tip
Looking to visualize your own genomes? Use Hoodini — the comparative genomics toolkit that fetches assemblies from NCBI, extracts gene neighborhoods, runs protein/nucleotide comparisons, annotates defense systems, builds trees, and generates ready-to-use visualizations. This library is the visualization engine that powers Hoodini's output.

📦 Install

npm / yarn / pnpm

npm install hoodini-viz

CDN

<link href="https://unpkg.com/hoodini-viz/dist/hoodini-viz.css" rel="stylesheet">
<script src="https://unpkg.com/hoodini-viz/dist/hoodini-viz.umd.js"></script>

🚀 Usage

NPM / React

import { HoodiniDashboard } from 'hoodini-viz';
import 'hoodini-viz/style.css';

// With Parquet (recommended - 3-10x faster)
<HoodiniDashboard
  dataPaths={{
    newick: '/data/tree.nwk',
    gffParquet: '/data/genes.parquet',
    hoodsParquet: '/data/hoods.parquet',
    proteinLinksParquet: '/data/links.parquet',
  }}
/>

// With TSV
<HoodiniDashboard
  dataPaths={{
    newick: '/data/tree.nwk',
    gff: '/data/genes.tsv',
    hoods: '/data/hoods.tsv',
    proteinLinks: '/data/links.tsv',
  }}
/>

import { HoodiniViz } from 'hoodini-viz';

<HoodiniViz
  newickStr={newick}
  gffFeatures={genes}
  proteinLinks={links}
  domainsByGene={domains}
  hoods={hoods}
  showTreeLayer={true}
  showGeneLayer={true}
  showProteinLinkLayer={true}
/>

CDN / Standalone

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/hoodini-viz/dist/hoodini-viz.css">
</head>
<body>
  <div id="root"></div>
  <script src="https://unpkg.com/hoodini-viz/dist/hoodini-viz.umd.js"></script>
  <script>
    // With Parquet (recommended - 3-10x faster)
    HoodiniViz.createDashboard({
      container: 'root',
      dataPaths: {
        newick: 'https://example.com/tree.nwk',
        gffParquet: 'https://example.com/genes.parquet',
        hoodsParquet: 'https://example.com/hoods.parquet',
      }
    });
  </script>
</body>
</html>

<script>
  // With TSV
  HoodiniViz.createDashboard({
    container: 'root',
    dataPaths: {
      newick: 'https://example.com/tree.nwk',
      gff: 'https://example.com/genes.tsv',
      hoods: 'https://example.com/hoods.tsv',
    }
  });
</script>

<script>
  // No sidebar, no data loading - you provide pre-processed data
  HoodiniViz.createViz({
    container: 'root',
    newickStr: '((A:0.1,B:0.2):0.3,C:0.4);',
    gffFeatures: [...],
    hoods: [...],
    proteinLinks: [...],
  });
</script>

<script>
  const { HoodiniDashboard, React, ReactDOM } = HoodiniViz;
  
  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(React.createElement(HoodiniDashboard, { 
    dataPaths: { newick: '...', gffParquet: '...' }
  }));
</script>

📁 Data Formats

ℹ️ Note
Parquet files load 3-10x faster than TSV.

| File | Format | Description | |:-----|:------:|:------------| | genes | .parquet .tsv | GFF3-style gene annotations | | hoods | .parquet .tsv | Genomic windows to display | | tree | .nwk | Newick phylogenetic tree | | links | .parquet .tsv | Protein homology relationships | | domains | .parquet .tsv | Protein domain annotations (optional) |

genes — Standard GFF3 with ID, Name, product in attributes
hoods — Columns: hood_id, seqid, start, end, align_gene (optional)
links — Columns: gene1, gene2, identity
domains — Columns: gene_id, domain_name, start, end, source

✨ Features

🎯 Visualization

WebGL/GPU rendering
Phylogenetic tree display
Gene neighborhood tracks
Protein & nucleotide links
Domain annotations
ncRNA secondary structures

🎛️ Interaction

Smooth zoom & pan
Click to select genes
Flip track orientation
Shift genomic windows
Align by gene cluster
Hover tooltips

🔧 Tools

Virtualized data table
50+ color palettes
Structure prediction
Real-time customization
SVG/PNG export

| Feature | Description | |:--------|:------------| | Protein links | Curved Bézier connections showing homology between proteins across tracks | | Nucleotide links | Polygonal overlays displaying synteny blocks between genomic regions | | ncRNA structures | Interactive 2D secondary structure viewer for non-coding RNAs (NAView layout) | | Data table | Virtualized grid browser for genes, domains, links, and metadata — handles millions of rows | | 3D structures | On-demand protein structure prediction via ESMFold (≤400aa) or Boltz2 |

🛠️ Development

npm run dev          # 🔥 Dev server at localhost:5173
npm run build        # 📦 Build library
npm run build:html   # 📄 Self-contained HTML

📜 License

⬆ Back to top

Made with 🦉 by pentamorfico