EvoMap 🧬🗺️

Democratizing Access to Evolutionary Pathogen Data Through Interactive Visualizations

EvoMap is a cutting-edge web platform that makes evolutionary viral and bacterial outbreak data accessible to researchers, policymakers, and the general public through intuitive interactive visualizations and open dashboards.

📋 Table of Contents

🎯 Mission
✨ Key Features
🚀 Live Demo
🛠️ Technology Stack
⚡ Quick Start
📁 Project Structure
🧪 Development Workflow
🧬 Supported Data Formats
🗺️ Roadmap
🤝 Contributing
📊 Data Sources
♿ Accessibility
📈 Performance
🔧 Configuration
🎯 Use Cases
🏆 Recognition
🔄 Version History
📄 License
🙏 Acknowledgments
📞 Contact & Support

🎯 Mission

EvoMap aims to transform the way we understand pathogen evolution by providing:

🔴 Real-time access to genomic outbreak data from viral and bacterial pathogens worldwide.
📊 Interactive visualizations of evolutionary trajectories, mutation pathways, and lineage distributions.
🌍 Global accessibility with educational and public health-focused components.
📱 Mobile-first design supporting responsive layouts, touch interactions, and offline capabilities for field research.

Our goal is to democratize pathogen genomic data so that researchers, public health officials, educators, and the general public can engage with complex datasets intuitively.

✨ Key Features

🌍 Interactive Global Map

Live outbreak tracking with automatic geographic clustering
Temporal visualization with adjustable timeline sliders
Severity-based color coding to quickly identify high-risk areas
Mobile-responsive design for touch and pinch interactions
Hover and click events to reveal detailed outbreak metadata

🌳 Phylogenetic Tree Visualization

Fully D3.js-powered trees with interactive zoom and pan
Track mutations and lineage relationships across datasets
Supports multiple tree layout algorithms (radial, rectangular, circular)
Real-time updates from NCBI and Nextstrain APIs
Highlights selected nodes and branches with detailed metadata

📊 Comprehensive Dashboard

Overview of active outbreaks globally and regionally
Trending mutations and variant monitoring
Hotspot identification based on prevalence and transmission metrics
Data freshness indicators for transparency on update frequency
Responsive design for desktop and mobile use

🔍 Advanced Search & Filtering

Full-text search across pathogen genomes and metadata
Filter by geography (country, region, or coordinates)
Filter by temporal range with flexible date selection
Mutation-specific search and filtering for targeted analysis

📤 Data Contribution Platform

Researcher upload interface supporting CSV, JSON, FASTA, Newick, and phyloXML
Automated data validation and quality checks
Collaborative review workflow for curating and approving new datasets
Version-controlled dataset management for reproducibility

🚀 Live Demo

🌐 Try EvoMap Live Demo – fully interactive platform in your browser.

Interface Preview

Screenshots in /docs/screenshots/:

main-interface.png – Dashboard overview with map and analytics
global-map.png – Interactive global outbreak map
phylogenetic-tree.png – Detailed evolutionary tree viewer
data-import.png – Data contribution interface

🛠️ Technology Stack

Frontend

Next.js 14+ – App Router, SSR, and client-side React
TypeScript 5+ – Type-safe and maintainable code
TailwindCSS 3+ – Utility-first responsive styling
D3.js – Advanced phylogenetic tree visualizations
Leaflet – Interactive, mobile-friendly mapping
Plotly.js – Interactive scientific and statistical charts

Backend & Data

MongoDB Atlas – Cloud-hosted genomic data storage
Nextstrain API – Real-time phylogenetic datasets
NCBI GenBank & Virus – Public genomic data
Vercel – Deployment, hosting, and CI/CD

State Management & Utilities

Zustand – Lightweight global state management
SWR – Stale-While-Revalidate data fetching and caching
BioPython – Genomic data processing for local utilities

⚡ Quick Start

Prerequisites

Node.js 18+
npm or yarn
Git

Installation & Development

# Clone the repository
git clone https://github.com/Jonahnki/EvoMap.git
cd EvoMap

# Install dependencies
npm install

# Copy example environment variables
cp .env.example .env.local

# Run development server
npm run dev

Open http://localhost:3000 to view the app.

Environment Variables

# Map Services
NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here
# OR OpenStreetMap (no token required)

# Database
MONGODB_URI=your_mongodb_connection_string

# External APIs
NCBI_API_KEY=your_ncbi_api_key
NEXTSTRAIN_API_URL=https://nextstrain.org/charon/getDataset

# Development flags
NEXT_PUBLIC_DEMO_MODE=true
NEXT_PUBLIC_ANALYTICS=false

📁 Project Structure

EvoMap/
├── src/
│   ├── app/
│   │   ├── map/                    # Interactive map pages
│   │   ├── dashboard/              # Analytics dashboards
│   │   ├── tree/                   # Phylogenetic tree viewer
│   │   └── api/                    # API routes
│   ├── components/
│   │   ├── maps/                   # Map components
│   │   ├── charts/                 # Chart components
│   │   ├── dashboard/              # Dashboard widgets
│   │   ├── trees/                  # Tree visualization components
│   │   └── ui/                     # Base UI elements
│   ├── lib/
│   │   ├── data/                    # Mock & real data handling
│   │   ├── algorithms/              # Tree layout algorithms
│   │   ├── parsers/                 # Data parsers (Newick, phyloXML, JSON)
│   │   ├── utils/                   # Helper functions
│   │   └── types.ts                 # TypeScript type definitions
│   └── hooks/                        # Custom React hooks
├── public/
│   ├── data/                        # Static datasets
│   └── datasets/                     # Demo phylogenetic data
├── docs/
│   ├── screenshots/                 # Interface screenshots
│   ├── api/                         # API documentation
│   └── examples/                    # Usage examples
└── tests/                             # Unit and integration tests

🧪 Development Workflow

Available Scripts

npm run dev          # Start development server
npm run build        # Build production version
npm run start        # Run production server
npm test             # Run unit tests
npm run test:e2e     # Run end-to-end tests
npm run test:a11y    # Run accessibility tests
npm run lint         # Lint code
npm run type-check   # TypeScript type checking
npm run format       # Format code
npm run analyze      # Analyze bundle size

Code Quality

npm run lint:fix    # Lint & fix
npm run format      # Format all files
npm run type-check  # Check types
npm run check-all   # Run all validations

Testing

npm test
npm run test:coverage
npm run test:watch

🧬 Supported Data Formats

Newick Format

((Human:0.006,Chimp:0.006):0.012,Gorilla:0.018);

phyloXML Format

<phyloxml>
  <phylogeny rooted="true">
    <clade>
      <name>Primates</name>
      <clade>
        <name>Human</name>
        <branch_length>0.006</branch_length>
      </clade>
    </clade>
  </phylogeny>
</phyloxml>

JSON Format

{
  "name": "root",
  "children": [
    { "name": "Human", "branch_length": 0.006 }
  ]
}

🗺️ Roadmap

Phase 1: Foundation (✅ Current)

Interactive global outbreak map
Basic phylogenetic tree visualization
Responsive dashboards
Search and filtering functionality
Mobile-first design
Multiple tree layout algorithms

Phase 2: Enhanced Features (🚧 In Progress)

Real-time data synchronization
Advanced analytics and predictions
Data export (PDF, CSV, SVG)
User authentication and personalization
Offline PWA capabilities
Collaborative features

Phase 3: Advanced Platform (🔮 Planned)

ML-powered outbreak predictions
Public API
Multi-language support
Advanced collaboration tools
Mobile native apps
Real-time collaborative editing

🤝 Contributing

We welcome contributions from researchers, developers, and public health professionals! Join our mission to democratize pathogen evolution data visualization.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow Conventional Commits specification
Use TypeScript best practices
Add comprehensive tests for new features
Update documentation as needed
Ensure mobile responsiveness and accessibility
Maintain high code coverage (90%+)

Areas We Need Help

🧬 Bioinformatics expertise for data validation and algorithms
🎨 UI/UX design for improved accessibility and user experience
⚡ Performance optimization for large genomic datasets
📚 Documentation and educational content creation
🧪 Testing and quality assurance
🌍 Internationalization for global accessibility
📱 Mobile development and touch interactions
🔒 Security and data privacy compliance

📊 Data Sources

EvoMap integrates with leading genomic and epidemiological databases to provide comprehensive pathogen evolution tracking:

Nextstrain - Real-time pathogen evolution tracking
NCBI Virus - Comprehensive viral genome database
GISAID - Global genomic data sharing platform
WHO Disease Outbreaks - Global outbreak monitoring
Our World in Data - Epidemiological statistics
CDC - Public health surveillance data

🔧 Configuration

Environment Variables

# Required
MONGODB_URI=mongodb://localhost:27017/evomap
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# Optional - Map Services
NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_google_maps_key

# Optional - External APIs
NCBI_API_KEY=your_ncbi_api_key
GISAID_API_KEY=your_gisaid_api_key

# Development
NEXT_PUBLIC_DEMO_MODE=true
NEXT_PUBLIC_ANALYTICS=false
NODE_ENV=development

Build Configuration

TypeScript strict mode enabled
ESLint with accessibility and security rules
Prettier for consistent code formatting
Bundle optimization and tree shaking
Progressive Web App capabilities
Service worker for offline functionality

🎯 Use Cases

Research Applications

Phylogenetic Analysis: Visualize evolutionary relationships between pathogen strains
Outbreak Investigation: Track pathogen spread and mutation patterns
Comparative Genomics: Compare viral and bacterial strains across regions
Publication Figures: Generate publication-ready visualizations and exports

Educational Applications

Teaching Evolution: Interactive demonstrations for students and educators
Public Health Training: Outbreak response simulation and case studies
Data Literacy: Learn to interpret genomic and epidemiological data
Curriculum Development: Educational resource creation for institutions

Public Health Applications

Surveillance: Real-time outbreak monitoring and alert systems
Decision Support: Evidence-based policy making and resource allocation
Risk Assessment: Evaluate outbreak severity and transmission patterns
Communication: Public-facing outbreak dashboards and reports

🏆 Recognition

EvoMap builds upon the excellent work of similar platforms in the phylogeographic visualization space:

EvoLaps - Continuous phylogeographic reconstructions
Nextstrain - Real-time pathogen evolution tracking
Empress - Interactive phylogenetic tree viewer
ggtree - Grammar of graphics for tree visualization in R

EvoMap focuses specifically on democratizing access through user-friendly design and real-time outbreak tracking capabilities.

🔄 Version History

v0.1.0 (Current) - Initial development with core visualization components
v0.2.0 (Next) - Enhanced data import and tree algorithms
v1.0.0 (Planned Q3 2025) - MVP release with full map integration and dashboard
v2.0.0 (Planned Q1 2026) - Advanced analytics and machine learning integration

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Nextstrain team for pioneering real-time pathogen tracking
NCBI for providing open access to genomic data
D3.js community for powerful visualization primitives
React and Next.js teams for excellent development frameworks
Research community worldwide for open data sharing and collaboration
Public health organizations for outbreak surveillance and data transparency

📞 Contact & Support

Community

💬 Discussions: GitHub Discussions
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Issues

Direct Contact

📧 General: evomap.project@gmail.com
🔒 Security: security@evomap.project
📊 Research Partnerships: research@evomap.project

Social Media

🐦 Twitter: @EvoMapProject
💼 LinkedIn: EvoMap Project
📺 YouTube: EvoMap Tutorials

Built with ❤️ for global health and open science

Making pathogen evolution data accessible to everyone, everywhere.

⭐ Star this repository if you find EvoMap useful for your research or public health work!

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.github		.github
app		app
assets		assets
docs		docs
evomap		evomap
public		public
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmrc		.npmrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vercel.json		vercel.json

License

Jonahnki/EvoMap

Folders and files

Latest commit

History

Repository files navigation

EvoMap 🧬🗺️

📋 Table of Contents

🎯 Mission

✨ Key Features

🌍 Interactive Global Map

🌳 Phylogenetic Tree Visualization

📊 Comprehensive Dashboard

🔍 Advanced Search & Filtering

📤 Data Contribution Platform

🚀 Live Demo

Interface Preview

🛠️ Technology Stack

Frontend

Backend & Data

State Management & Utilities

⚡ Quick Start

Prerequisites

Installation & Development

Environment Variables

📁 Project Structure

🧪 Development Workflow

Available Scripts

Code Quality

Testing

🧬 Supported Data Formats

Newick Format

phyloXML Format

JSON Format

🗺️ Roadmap

Phase 1: Foundation (✅ Current)

Phase 2: Enhanced Features (🚧 In Progress)

Phase 3: Advanced Platform (🔮 Planned)

🤝 Contributing

How to Contribute

Development Guidelines

Areas We Need Help

📊 Data Sources

🔧 Configuration

Environment Variables

Build Configuration

🎯 Use Cases

Research Applications

Educational Applications

Public Health Applications

🏆 Recognition

🔄 Version History

📄 License

🙏 Acknowledgments

📞 Contact & Support

Community

Direct Contact

Social Media

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages