# COVID-19 Vaccination Timeline - Global Equity Analysis

**Advanced Vaccine Time Series Visualization with Dual-Axis Chart.js Charts**

![Iteration](https://img.shields.io/badge/Iteration-3-blue)
![Level](https://img.shields.io/badge/Level-Advanced-red)
![Disease](https://img.shields.io/badge/Disease-COVID--19-purple)
![Chart Type](https://img.shields.io/badge/Chart-Dual--Axis-green)

## Overview

This visualization tells the story of **COVID-19 vaccination equity** from 2020-2023, revealing stark disparities between high-income and low-income nations. Using dual-axis Chart.js charts, it demonstrates the relationship between vaccination coverage and COVID-19 case reduction across different income levels.

### Key Insights

- **High-Income Nations**: Achieved 75%+ coverage by 2022, early vaccine access
- **Low-Income Nations**: Struggled to reach 25% coverage due to COVAX challenges
- **Equity Gap**: Dramatic difference in vaccine availability between wealthy and poor countries
- **Case Reduction**: Clear correlation between vaccination rates and declining cases in high-income countries

## Technical Features

### 1. Dual-Axis Chart.js Charts (Advanced)

**Implementation based on Chart.js cartesian axes documentation:**

```javascript
// Dual-axis configuration from Chart.js cartesian axes documentation
scales: {
    // LEFT Y-AXIS: Vaccination Coverage (0-100%)
    y: {
        type: 'linear',
        position: 'left',
        title: {
            display: true,
            text: 'Coverage (%)'
        },
        min: 0,
        max: 100
    },
    // RIGHT Y-AXIS: COVID-19 Cases (dynamic range)
    y1: {
        type: 'linear',
        position: 'right',
        grid: {
            drawOnChartArea: false  // Prevent grid overlap
        }
    }
}
```

**Key Technical Details:**
- `yAxisID: 'y'` for coverage dataset (left axis)
- `yAxisID: 'y1'` for cases dataset (right axis)
- Different data ranges: 0-100% vs dynamic case counts
- Prevents grid line overlap with `drawOnChartArea: false`
- Independent scales for optimal data visualization

### 2. Chart Instance Management

**Performance-optimized chart lifecycle:**

```javascript
let activeChart = null;
let chartCounter = 0;
let popupTimeout = null;

// Destroy old chart before creating new one
if (activeChart) {
    activeChart.destroy();
    activeChart = null;
}

// 200ms delay prevents flickering
popupTimeout = setTimeout(() => {
    const ctx = canvas.getContext('2d');
    activeChart = new Chart(ctx, {...});
}, 200);
```

### 3. Full Timeline Controls

- **Play/Pause**: Auto-advance through years
- **Reset**: Jump back to 2020
- **Loop Toggle**: Continuous playback option
- **Manual Slider**: Direct year selection
- **Global Statistics**: Real-time coverage and case counts

### 4. Realistic COVID-19 Data Model

**Income-stratified vaccination rollout:**

```javascript
// High-income: rapid vaccination, early access
coverageByYear = [2, 68, 82, 88];  // 2020: minimal, 2021: rapid rollout

// Low-income: COVAX challenges, minimal early access
coverageByYear = [0, 8, 18, 24];   // Dramatic inequality
```

**Case reduction patterns:**
- High-income: Sharp decline after 2021 vaccination surge
- Low-income: Prolonged case burden due to limited vaccine access

### 5. Shared Architecture Integration

Uses centralized Mapbox configuration:
- `MAPBOX_CONFIG` for token management and validation
- `LayerFactory` for optimized circle layers with data-driven styling
- Medical atmosphere preset for COVID-19 theme

## Data Story

### Timeline Breakdown

**2020: Pandemic Begins**
- Global coverage: ~1%
- No vaccines available yet
- Cases surging worldwide

**2021: Vaccine Rollout (Inequitable)**
- High-income: 68% average coverage
- Low-income: Only 8% coverage
- COVAX struggles to deliver equitable access

**2022: Rich Countries Plateau**
- High-income: 82% coverage, cases declining
- Low-income: Still only 18% coverage
- Equity gap widens

**2023: Ongoing Disparity**
- High-income: 88% coverage, low case counts
- Low-income: 24% coverage, continued health burden
- Lessons about global health equity

### Countries by Income Level

**High-Income** (rapid vaccination):
- United States, United Kingdom, Germany, France, Japan
- Canada, Australia, South Korea, Israel, Singapore

**Upper-Middle Income** (moderate pace):
- Brazil, China, Russia, Mexico, Turkey, South Africa
- Argentina, Thailand

**Lower-Middle Income** (slower rollout):
- India, Indonesia, Egypt, Pakistan, Bangladesh
- Nigeria, Philippines, Vietnam, Kenya

**Low-Income** (COVAX challenges):
- Ethiopia, Tanzania, Uganda, Mozambique
- Madagascar, Malawi, Chad, Haiti

## Web Learning Application

**Assigned URL**: https://www.chartjs.org/docs/latest/axes/cartesian/

**Techniques Learned and Applied:**

1. **Multiple Y-Axes Configuration**
   - Bind datasets to specific axes using `yAxisID`
   - Match `dataset.yAxisID` to scale definitions in options

2. **Axis Positioning**
   - `position: 'left'` for coverage axis
   - `position: 'right'` for cases axis
   - Independent positioning allows side-by-side comparison

3. **Scale Type Declaration**
   - Must explicitly declare `type: 'linear'` for both axes
   - Default types not used in multi-axis scenarios (per documentation)

4. **Grid Overlap Prevention**
   - While `drawOnChartArea` wasn't in the fetched documentation
   - Implementation follows Chart.js best practices to prevent visual clutter

## File Structure

```
vaccine_timeseries_3_covid/
├── index.html          # Complete visualization with dual-axis charts
├── README.md           # This file - COVID-19 equity analysis
└── CLAUDE.md           # Technical documentation and implementation guide
```

## Usage

1. **Open `index.html`** in a modern web browser
2. **Wait for globe to load** with country data points
3. **Hover over any country** to see dual-axis chart popup
4. **Use timeline controls** to explore 2020-2023 progression
5. **Click Play** to auto-advance through years
6. **Observe equity gaps** between high-income and low-income nations

## Technical Stack

- **Mapbox GL JS v3.0.1**: Globe visualization with projection
- **Chart.js v4.4.0**: Dual-axis time series charts
- **Shared Architecture**: Centralized configuration and layer factory
- **ES6 Modules**: Clean imports and code organization

## Key Visualizations

### Dual-Axis Chart Features

- **Line Chart** (Coverage): Smooth line showing vaccination progress with area fill
- **Bar Chart** (Cases): Dramatic visual of case counts by year
- **Color Coding**: Green (coverage) vs Red (cases) for clear distinction
- **Interactive Tooltips**: Hover to see exact values with proper formatting
- **Responsive Legend**: Bottom placement with point style indicators

### Globe Features

- **Color Scale**: Red (0%) → Yellow (50%) → Green (100%)
- **Size Scale**: Proportional to population (6-35px radius)
- **Opacity**: Zoom-responsive for better detail at high zoom
- **Atmosphere**: Medical theme with subtle blue glow
- **Rotation**: Gentle auto-spin when not interacting

## Performance Optimizations

1. **Chart Cleanup**: Destroy previous chart instances before creating new ones
2. **Popup Delay**: 200ms timeout prevents flickering on rapid mouse movement
3. **Timeout Clearing**: Cancel pending popups when leaving features
4. **Unique Canvas IDs**: Counter-based IDs prevent DOM conflicts
5. **RequestAnimationFrame**: Ensures canvas is ready before chart creation

## Health Equity Insights

This visualization reveals critical lessons about **global health equity**:

- **Wealth Determines Health**: High-income countries secured vaccines first through bilateral deals
- **COVAX Limitations**: Initiative to ensure equitable access faced funding and supply challenges
- **Ongoing Disparities**: Even in 2023, low-income countries lag far behind in coverage
- **Public Health Impact**: Lower vaccination rates correlate with prolonged case burden

## Future Enhancements

Potential additions for deeper analysis:

1. **Deaths Data**: Add third axis or overlay for COVID-19 mortality
2. **Vaccine Types**: Show different vaccines (Pfizer, Moderna, AstraZeneca, etc.)
3. **Booster Doses**: Track additional doses beyond primary series
4. **Regional Comparisons**: Compare continents or WHO regions
5. **Supply Chain Data**: Visualize vaccine shipments and donations

## Credits

**Web Learning Source**: Chart.js Cartesian Axes Documentation
**Architecture**: Shared Mapbox configuration and LayerFactory
**Data Model**: Realistic COVID-19 vaccination patterns by income level
**Visualization**: Advanced dual-axis Chart.js implementation

---

**Generated with Advanced Web Learning**
Part of the Infinite Agentic Loop demonstration project showcasing progressive web-based learning and sophisticated data visualization techniques.