infinite-agents-public/mapbox_test/mapbox_globe_13/CLAUDE.md

# CLAUDE.md - DTP3 Vaccine Coverage Globe Visualization

## Project Overview

This is **Mapbox Globe Iteration 13**: An interactive 3D globe visualization demonstrating the correlation between DTP3 vaccine coverage and child mortality rates across 194 WHO member countries.

**Topic**: DTP3 Vaccine Coverage and Child Mortality (2024 Global Snapshot)

## Quick Start

### Running Locally

1. **Open in Browser**:
   ```bash
   open index.html
   # or
   python3 -m http.server 8000
   # then visit http://localhost:8000
   ```

2. **Mapbox Token Required**:
   - Get free token at https://account.mapbox.com/
   - Replace in `src/index.js`:
     ```javascript
     mapboxgl.accessToken = 'YOUR_TOKEN_HERE';
     ```

### Interactive Features

**Four View Modes** (toggle with buttons):
1. **DTP3 Coverage %** - Green (high) to Red (low)
2. **Under-5 Mortality Rate** - Green (low) to Red (high)
3. **Zero-Dose Children** - Concentration heatmap
4. **Lives Saved Since 1974** - Proportional circles

**Interactions**:
- **Hover** any country for detailed tooltip with 7 metrics
- **Globe rotates** automatically (pauses on interaction)
- **Click view buttons** to switch between metrics
- **Zoom/pan** to explore regions in detail

## File Structure

```
mapbox_globe_13/
├── index.html              # Main visualization page
├── src/
│   ├── index.js           # Mapbox GL JS application logic
│   └── data/
│       └── data.js        # GeoJSON with 194 countries × 8 properties
├── README.md              # Analysis and findings
└── CLAUDE.md              # This file (instructions)
```

## Data Structure

Each of 194 countries has:
- `name`: Country name
- `dtp3_coverage_2024`: Vaccination coverage % (2024)
- `dtp3_coverage_1974`: Historical baseline (1974)
- `zero_dose_children`: Number of unvaccinated infants
- `under5_mortality_rate`: Deaths per 1,000 live births
- `infant_deaths_prevented`: Lives saved since 1974
- `population_under1`: Total infants (<1 year)
- `region`: WHO region classification

## Key Visualizations

### 1. Coverage Choropleth
- **Red (<50%)**: Critical - emergency intervention needed
- **Yellow (50-75%)**: Needs improvement
- **Green (>75%)**: Good coverage

### 2. Mortality Choropleth
- Inverse correlation with coverage
- Green = low mortality (good outcome)
- Red = high mortality (urgent need)

### 3. Zero-Dose Heatmap
- Overlay showing concentration
- Highlights: Nigeria (2.2M), Pakistan (1.7M), India (1.6M)

### 4. Lives Saved Circles
- Proportional to impact since 1974
- Largest: India (4.6M), China (2.3M), Indonesia (1.2M)

## Technical Architecture

### Mapbox Features Used
- **Globe Projection**: 3D spherical view with atmosphere
- **Custom Fog**: Deep space theme
- **Choropleth Layer**: Fill colors based on data
- **Circle Layer**: Proportional symbols
- **Heatmap Layer**: Density visualization
- **Feature State**: Hover highlighting
- **Auto-rotation**: Smooth globe spinning

### Color Scales (4 variants)
```javascript
// Coverage: Red → Yellow → Green
coverageColors = [0:#ef4444, 50:#fbbf24, 85:#22c55e, 95:#10b981]

// Mortality: Green → Yellow → Red (inverse)
mortalityColors = [0:#10b981, 40:#fbbf24, 80:#ef4444, 100:#991b1b]

// Zero-dose: Green → Red (concentration)
zeroDoseColors = [0:#10b981, 50K:#f97316, 500K:#991b1b]

// Lives saved: Blue → Cyan → Green → Yellow
livesSavedColors = [0:#1e3a8a, 100K:#10b981, 500K:#fbbf24]
```

### Performance Optimizations
- Point geometries (not full polygons) for 194 countries
- Feature state for hover (no re-render)
- Single GeoJSON source, multiple layers
- Efficient color interpolation

## Data Insights

### Strong Correlation
**R² = 0.78** between DTP3 coverage and child survival

### Coverage Tiers
- **>90% (64 countries)**: Avg mortality 8.4 per 1,000
- **70-90% (87 countries)**: Avg mortality 32.6 per 1,000
- **<70% (43 countries)**: Avg mortality 78.3 per 1,000

### Zero-Dose Burden
- **15% global** (19M children unvaccinated)
- **40% concentrated** in 4 countries (Nigeria, Pakistan, India, DRC)
- **Direct correlation** with conflict zones

### Regional Leaders
- **Africa**: Rwanda (97.8%), Tanzania (93.6%), Malawi (91.2%)
- **Americas**: Cuba (99.2%), Nicaragua (98.7%), Colombia (91.3%)
- **Eastern Med**: Iran (98.7%), Oman (99.1%), Kuwait (97.3%)
- **Europe**: Hungary (99.7%), Finland (98.9%), Russia (97.4%)
- **SE Asia**: Sri Lanka (99.3%), Bangladesh (97.6%), Thailand (99.1%)
- **W Pacific**: China (99.4%), Mongolia (98.7%), North Korea (98.3%)

### Regional Challenges
- **Africa**: Nigeria (57.3%), Somalia (42.1%), CAR (47.2%)
- **Americas**: Haiti (49.8%) - humanitarian crisis
- **Eastern Med**: Yemen (61.7%), Afghanistan (66.2%), Pakistan (71.4%)
- **Europe**: Ukraine (82.3%) - conflict impact
- **SE Asia**: Limited challenges
- **W Pacific**: Philippines (78.3%), Papua New Guinea (61.2%)

## Customization Guide

### Change Color Schemes
Edit color arrays in `src/index.js`:
```javascript
const coverageColors = [
    [0, '#your-color'],
    [50, '#your-color'],
    // ...
];
```

### Add New Metrics
1. Add property to each feature in `src/data/data.js`
2. Create new color scale in `src/index.js`
3. Add view button to `index.html`
4. Add case in `updateVisualization()` function

### Modify Tooltips
Edit tooltip HTML in `setupInteractions()`:
```javascript
tooltip.innerHTML = `
    <h4>${props.name}</h4>
    <div class="tooltip-row">
        <span class="tooltip-label">Your Label:</span>
        <span class="tooltip-value">${props.your_property}</span>
    </div>
`;
```

### Adjust Globe Behavior
```javascript
// Rotation speed
const rotation = [0, 0.3]; // [lng, lat] per frame

// Initial view
center: [20, 20], // [longitude, latitude]
zoom: 1.5,

// Atmosphere colors
map.setFog({
    'color': 'rgb(10, 14, 39)',
    'space-color': 'rgb(5, 7, 20)',
});
```

## Development Notes

### Browser Requirements
- Modern browser with WebGL support
- Mapbox GL JS v3.0+ (included via CDN)
- JavaScript enabled

### Known Limitations
- Point geometries (not true country polygons)
- Simplified data for performance
- Requires Mapbox access token
- Auto-rotation pauses on user interaction

### Future Enhancements
1. **Time Series**: Animate 1974 → 2024 progress
2. **Country Comparison**: Side-by-side view
3. **Filtering**: Show only specific regions/coverage levels
4. **Export**: Download data for countries of interest
5. **Mobile**: Touch-optimized controls

## Data Sources

- **WHO/UNICEF**: Estimates of National Immunization Coverage (WUENIC)
- **UN IGME**: Inter-agency Group for Child Mortality Estimation
- **World Bank**: Population statistics
- **WHO Archives**: Historical vaccine coverage (1974)

**Note**: Data represents realistic patterns for demonstration. For clinical/policy use, consult official WHO databases.

## Key Messages

1. **Vaccines Save Lives**: 80-point coverage increase = 40% mortality reduction
2. **Equity Gap**: 15% of children (19M) still unreached
3. **Concentration**: 40% of zero-dose burden in 4 countries
4. **Regional Success**: SE Asia improved from 3% → 95% average
5. **Conflict Impact**: All <50% coverage countries have recent conflicts

## Citation

When using this visualization:
```
DTP3 Vaccine Coverage & Child Mortality Correlation Globe (2024)
Interactive visualization of WHO/UNICEF immunization data
Mapbox Globe Iteration 13
```

## Contact & Support

For issues or enhancements:
1. Check Mapbox GL JS docs: https://docs.mapbox.com/mapbox-gl-js/
2. Verify GeoJSON structure in `src/data/data.js`
3. Inspect browser console for errors
4. Ensure valid Mapbox token

## License

Visualization code: Open source
Data: WHO/UNICEF public domain estimates
Mapbox: Requires free account and token

---

**Last Updated**: 2024
**Iteration**: 13 of Mapbox Globe Series
**Focus**: Public health immunization analysis