🦠 COVID-19 Global Dashboard

Live Site: https://covid19dashboards.com
Status: Historical Archive (Last updated: March 2020)

A data-driven dashboard that automatically visualizes COVID-19 statistics using Jupyter Notebooks. This project leverages the fastpages framework to convert Python notebooks directly into an interactive website, with daily automated updates via GitHub Actions.

📊 Project Overview

This repository contains a collection of Jupyter Notebooks that perform Exploratory Data Analysis (EDA), statistical modeling, and visualization of COVID-19 data. Unlike traditional web apps, no front-end code is required; every chart and table you see on the live site is generated purely from Python code in the _notebooks directory.

Key Capabilities

• Automated Pipeline: GitHub Actions fetch fresh data, executes notebooks, and rebuilds the site daily.
• Notebook-First Architecture: The entire website content is derived from .ipynb files.
• Multi-Source Data Integration: Aggregates data from Johns Hopkins University and The New York Times.
• Advanced Analytics: Includes Bayesian growth modeling, trajectory comparisons, and per-capita analysis.

🗂️ Included Dashboards & Analyses

The _notebooks directory contains the following specific analyses (generated dynamically):

Notebook	Description
Overview	Global, US, and Europe-specific summary dashboards with key metrics.
Growth Analysis	Logarithmic growth charts and curve fitting for confirmed cases.
Trajectory Comparison	Compares outbreak timelines across different countries/states (aligned by "Day 100").
Bayesian Modeling	Probabilistic estimates of case growth and doubling times.
US State Maps	Choropleth visualizations of case density and growth by US state.
Per Capita Stats	Normalized data showing cases and deaths per million people.
Death Trajectories	Comparative analysis of fatality rates over time.
Undercount Estimation	Statistical models estimating the true number of infections vs. reported cases.

🛠️ Technical Architecture

Core Stack

• Framework: fastpages (Fast.ai)
• Language: Python 3.7+ (99.9% of codebase)
• Rendering Engine: Jupyter Notebooks → HTML via nbconvert
• Site Generator: Jekyll (Ruby) with Minima theme
• Containerization: Docker & Docker Compose

Data Sources

The project ingests data directly from public repositories at runtime:

1. Global Data: Johns Hopkins University CSSE
   • Files: time_series_covid19_confirmed_global.csv, deaths, recovered.
2. US Specific Data: The New York Times COVID-19 Data
   • File: us-states.csv
3. Metadata: Country mapping and continent classification (via external CSV).

Key Scripts

• load_covid_data.py: Handles fetching and merging JHU and NYT datasets.
• covid_overview.py: Generates summary statistics and KPI cards.

🚀 Running Locally

Since this project relies on a specific Docker environment to mimic the GitHub Actions workflow, local development requires Docker.

Prerequisites

• Docker & Docker Compose installed
• Git

Installation Steps

1. Clone the Repository

   git clone https://github.com/wissamismail/covid19-dashboard.git
   cd covid19-dashboard

2. Start the Development Server This command builds the Docker images, converts the notebooks, and starts the Jekyll server.

   make server
   # OR explicitly with docker-compose
   docker-compose up

3. View the Site Open your browser to http://localhost:4000.

4. Hot Reloading The watcher service is configured to detect changes in .ipynb files. When you save a notebook in the _notebooks folder, the container will automatically re-convert it and refresh the page.

Manual Notebook Execution

If you only want to run the data analysis without the website:

pip install pandas numpy matplotlib seaborn plotly jupyter
jupyter lab _notebooks

Note: You may need to install specific dependencies found in the notebook headers.

📂 Directory Structure

.
├── _notebooks/             # SOURCE OF TRUTH: All dashboards and logic live here
│   ├── load_covid_data.py  # Data ingestion utilities
│   ├── 2020-03-XX-*.ipynb  # Daily reports and specific analyses
│   └── my_icons/           # Custom assets for plots
├── _pages/                 # Static informational pages (About, Contributing)
├── _action_files/          # GitHub Actions scripts for CI/CD automation
├── assets/                 # Images and static resources
├── docker-compose.yml      # Local development environment config
├── Makefile                # Shortcuts for Docker commands
├── _config.yml             # Jekyll/Fastpages site configuration
└── Gemfile                 # Ruby dependencies for Jekyll

⚙️ Automation Workflow

The site updates automatically via GitHub Actions:

1. Trigger: Scheduled daily or on push to master.
2. Fetch: Python scripts pull the latest CSVs from JHU and NYT.
3. Execute: All notebooks in _notebooks are executed in order.
4. Convert: Outputs (HTML/Charts) are embedded into the site.
5. Deploy: The updated site is pushed to GitHub Pages.

🤝 Contributing

To add a new visualization:

1. Create a new Jupyter Notebook in _notebooks/.
2. Name it strictly as YYYY-MM-DD-Title-Of-Analysis.ipynb.
3. Add the following YAML front-matter to the top of the first cell (as raw markdown):

   ---
   title: "My New Analysis"
   description: "Brief description of the chart"
   image: "thumbnail.png" # Optional
   search_exclude: true   # Set to false if you want it searchable
   ---

4. Commit and push. GitHub Actions will handle the rest.

📄 License

Distributed under the Apache 2.0 License. See LICENSE for details.

🙏 Acknowledgments

• Fastpages Team: For the revolutionary notebook-to-blog framework.
• Data Providers: Johns Hopkins University CSSE and The New York Times for open data access.
• Open Source Contributors: Everyone who contributed notebooks to this historical archive.

---

Note: This repository serves as a historical snapshot of the early pandemic response (March 2020). Data sources may no longer be active or updated.