A hackathon contribution to VizAvalanche · Built on top of VirJenDB
ViralScope is an interactive web dashboard that visualizes viral sequence distribution across the globe using data from the VirJenDB database — a large-scale viral genome database containing approximately 15 million sequences across 90 metadata fields.
The dashboard transforms raw sequence metadata into an intuitive, explorable interface that allows researchers, epidemiologists, and the public to discover viral diversity patterns worldwide.
- Choropleth map showing sequence counts per country
- Based on 13 million records from
collected_data.csv - 138 countries mapped and color-coded
- Click any country to view detailed statistics
- Shift+click to add countries to comparison
- Full-text search across viral species, families, and titles
- Filter by viral family (52 families available)
- Filter by host species
- Filter by country
- Paginated results with clickable rows that highlight countries on the map
- Select multiple countries via Shift+click on the map
- Side-by-side bar chart comparison of sequence counts
- Color-coded legend with exact figures
- Log-scale visualization for better readability across orders of magnitude
- Real-time summary: 13,049,920 total records, 51,072 species, 263 families, 2,611 genera
- Top 5 genera displayed with counts (Betacoronavirus, Lentivirus, Alphainfluenzavirus, …)
- Save the current map state (selected countries, filters, palette) with a custom name
- Reload any saved state instantly
- Stored locally in the browser (localStorage)
- 10 color palettes including colorblind-safe options (Viridis, Cividis, Plasma, Magma, Inferno)
- Toggle colorblind mode to auto-select accessible palettes
| Layer | Technology |
|---|---|
| Framework | React 19 + TypeScript 5.8 |
| Routing | TanStack Router |
| Data fetching | TanStack Query |
| Map rendering | react-simple-maps + d3-geo |
| Charts | Recharts |
| UI components | shadcn/ui + Radix UI |
| Styling | Tailwind CSS v4 |
| Build tool | Vite 7 + Bun |
| Source | Description | Usage |
|---|---|---|
collected_data.csv |
Full VirJenDB dataset — 13M records | Country aggregation for world map |
sample_5k.csv |
5,000-record sample | Search tab records |
api2.virjendb.org |
VirJenDB REST API | Future live search integration |
The dashboard uses a pre-processed static JSON file (public/virjendb_data.json) generated from collected_data.csv for instant map loading without API dependency.
src/
├── lib/data-sources/
│ └── virjendb.ts ← Data adapter (static JSON + API fallback)
├── components/
│ ├── world-map.tsx ← SVG choropleth map
│ ├── viral-search.tsx ← Search tab with filters
│ ├── compare-chart.tsx ← Bar chart comparison
│ ├── country-detail-panel.tsx ← Country detail sheet
│ ├── db-stats-card.tsx ← Database statistics sidebar card
│ └── snapshot-manager.tsx ← Save/load dashboard states
├── routes/
│ └── index.tsx ← Main dashboard
└── public/
└── virjendb_data.json ← Pre-processed dataset (760 KB)
# Clone the repository
git clone https://github.com/Hziraksaz/virjendb-explorer.git
cd virjendb-explorer
# Install dependencies
bun install
# Start development server
bun run devOpen http://localhost:8080 in your browser.
bun run buildThe included virjendb_data.json is pre-built from the hackathon dataset. To regenerate it from the full collected_data.csv:
python process_full_dataset.py \
--input /path/to/collected_data.csv \
--sample /path/to/sample_5k.csv \
--output public/virjendb_data.jsonRequirements: Python 3.8+ (no external libraries needed — uses only the standard csv and json modules)
Runtime: ~10–15 minutes for 13M records
The dashboard is designed to switch seamlessly to the live VirJenDB API when the server is available. Each component that uses static data has clearly marked comments:
// ── STATIC (active now) ──────────────────────
queryFn: fetchDbSummary, // reads from virjendb_data.json
// ── API (uncomment when server is ready) ─────
// queryFn: () => fetch(`${VIRJENDB_BASE}/v2/statsSummaryChart/`).then(r => r.json()),Files to update when switching:
src/lib/data-sources/virjendb.tssrc/components/db-stats-card.tsxsrc/components/viral-search.tsxsrc/components/country-detail-panel.tsx
This project was built for the VizAvalanche Hackathon organized by VirJenDB / NFDI4Microbiota. The goal was to create informative and visually appealing visualizations of the vOTU dataset for the virjendb.org/stats page.
Key challenge addressed: The /v2/graphs/country_stats API endpoint returned cached Plotly JSON for only the top 10 countries, and the /v2/graphs/recreate endpoint timed out (504) under load. I solved this by building a client-side aggregation pipeline from the raw dataset that maps 138 countries instead of 10, giving a far richer geographic picture.
MIT — see LICENSE for details.
- VirJenDB team for the dataset and API
- VizAvalanche hackathon organizers
- Dataset: cloud.uni-jena.de