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

# Mapbox Globe 11: Measles Vaccination Coverage vs. Disease Outbreaks

## Setup Instructions

### Prerequisites
- A Mapbox account and access token
- Modern web browser with WebGL support
- Local web server (for CORS compatibility)

### Quick Start

1. **Get a Mapbox Access Token**
   - Visit [mapbox.com](https://www.mapbox.com/)
   - Create a free account
   - Navigate to Account → Access Tokens
   - Copy your default public token

2. **Configure the Token**
   - Open `src/index.js`
   - Replace the placeholder token on line 4:
   ```javascript
   mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN_HERE';
   ```

3. **Run a Local Server**

   Using Python 3:
   ```bash
   python -m http.server 8000
   ```

   Using Node.js (http-server):
   ```bash
   npx http-server -p 8000
   ```

   Using PHP:
   ```bash
   php -S localhost:8000
   ```

4. **Open in Browser**
   - Navigate to `http://localhost:8000`
   - The globe should load automatically
   - Allow a few seconds for map tiles to load

## File Structure

```
mapbox_globe_11/
├── index.html              # Main HTML with UI and styles
├── src/
│   ├── index.js           # Mapbox initialization and interaction logic
│   └── data/
│       └── data.js        # GeoJSON data (85+ countries, 50+ outbreaks)
├── README.md              # Detailed analysis and findings
└── CLAUDE.md             # This file (setup guide)
```

## Architecture

### Data Flow
1. `index.html` loads Mapbox GL JS library and stylesheets
2. `src/index.js` imports from `src/data/data.js`
3. GeoJSON features are split into two sources:
   - Countries (Polygon/MultiPolygon) → Coverage choropleth
   - Outbreaks (Point) → Proportional circles
4. Interactive layers render on globe projection
5. Event handlers provide click/hover interactions

### Key Components

**Map Configuration:**
- Projection: `globe` with fog effects
- Initial view: Center [15, 25], Zoom 1.5
- Style: `mapbox://styles/mapbox/dark-v11`
- Auto-rotation enabled (0.15° per frame)

**Data Sources:**
- `measles-countries`: Polygon features for coverage choropleth
- `measles-outbreaks`: Point features for outbreak circles

**Layers:**
1. `coverage-layer` (fill): Vaccination coverage choropleth
2. `borders-layer` (line): Country boundaries
3. `outbreaks-layer` (circle): Outbreak points (main)
4. `outbreaks-pulse` (circle): Animated pulse effect

**Interactive Controls:**
- Toggle buttons for each layer
- Click popups for detailed information
- Hover cursor changes
- Automatic rotation with manual override

### Color Scales

**Coverage Choropleth:**
```javascript
0%   → #ff6f00  (Deep Orange - Critical)
60%  → #ffb74d  (Light Orange - Low)
75%  → #42a5f5  (Light Blue - Moderate)
85%  → #1976d2  (Medium Blue - Good)
95%+ → #1565c0  (Dark Blue - Excellent)
```

**Outbreak Circles:**
- Fill: `rgba(239, 83, 80, 0.7)` (Semi-transparent red)
- Stroke: `#ef5350` (Solid red)
- Size: Interpolated by case count (6px to 32px)

## Data Schema

### Country Features
```javascript
{
  "type": "Feature",
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "properties": {
    "name": "Country Name",
    "coverage_dose1": 83,        // % first dose coverage
    "coverage_dose2": 74,        // % second dose coverage
    "income_level": "middle",    // low | middle | high
    "cases_2023": 15000,        // total cases in 2023
    "deaths_2023": 120          // total deaths in 2023
  }
}
```

### Outbreak Features
```javascript
{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [lng, lat] },
  "properties": {
    "location": "City/Region",
    "country": "Country Name",
    "outbreak_year": 2023,
    "cases": 5000,              // outbreak case count
    "deaths": 45,               // outbreak death toll
    "coverage_local": 68        // local coverage %
  }
}
```

## Customization Guide

### Adjusting Colors

**Change coverage color scheme:**
Edit `src/index.js` around line 45:
```javascript
'fill-color': [
  'interpolate', ['linear'], ['get', 'coverage_dose1'],
  0, '#YOUR_LOW_COLOR',
  50, '#YOUR_MID_COLOR',
  95, '#YOUR_HIGH_COLOR'
]
```

**Change outbreak circle colors:**
Edit `src/index.js` around line 70:
```javascript
'circle-color': 'rgba(R, G, B, opacity)',
'circle-stroke-color': '#HEXCOLOR'
```

### Modifying Circle Sizes

Edit the circle-radius interpolation in `src/index.js`:
```javascript
'circle-radius': [
  'interpolate', ['linear'], ['get', 'cases'],
  MIN_CASES, MIN_RADIUS,
  MAX_CASES, MAX_RADIUS
]
```

### Adding New Countries/Outbreaks

Add features to `src/data/data.js`:
```javascript
export const measlesData = {
  "type": "FeatureCollection",
  "features": [
    // ... existing features
    {
      "type": "Feature",
      "geometry": { ... },
      "properties": { ... }
    }
  ]
};
```

### Disabling Auto-Rotation

In `src/index.js`, set:
```javascript
let spinEnabled = false;
```

Or comment out the `spinGlobe()` function call.

## Performance Optimization

### For Large Datasets
- Use `simplify` on polygon geometries to reduce vertices
- Implement clustering for outbreak points
- Add zoom-based layer visibility
- Use vector tiles instead of inline GeoJSON

### Rendering Improvements
```javascript
// Add to map initialization
map.setRenderWorldCopies(false);  // Disable duplicate globes
map.setMaxBounds([[-180, -90], [180, 90]]);  // Constrain panning
```

## Troubleshooting

### Map Not Loading
1. Check browser console for errors
2. Verify Mapbox token is valid and not expired
3. Ensure local server is running (no `file://` protocol)
4. Check network tab for failed tile requests

### Performance Issues
- Reduce polygon complexity in data
- Disable fog effects on low-end devices
- Remove pulse animation layer
- Increase interpolation steps in color scales

### Data Not Displaying
- Verify GeoJSON syntax in `data.js`
- Check coordinate order (longitude, latitude)
- Ensure property names match layer expressions
- Look for JavaScript errors in console

## Browser Compatibility

**Supported:**
- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

**Requirements:**
- WebGL support
- ES6 module support
- Fetch API

## Deployment

### Static Hosting
Works with any static host:
- GitHub Pages
- Netlify
- Vercel
- AWS S3 + CloudFront

### Build Process
No build step required - vanilla HTML/JS/CSS.

### Environment Variables
Store Mapbox token in environment variable:
```javascript
mapboxgl.accessToken = process.env.MAPBOX_TOKEN || 'fallback-token';
```

## Research Context

This visualization is based on WHO/UNICEF research findings:
- 60 million lives saved through measles vaccination (2000-2023)
- 83% first dose, 74% second dose global coverage (2023)
- 20% increase in cases, outbreaks in 57 countries (2023)
- 95% coverage required for herd immunity
- Stark income-level disparities (64% low-income vs 86% middle-income)

The dual-layer approach clearly demonstrates the correlation between low vaccination coverage and outbreak occurrence, with special emphasis on conflict zones and fragile states.

## License

This visualization uses:
- Mapbox GL JS (BSD-3-Clause)
- Data from public health sources (WHO, UNICEF)

## Support

For issues with:
- **Mapbox**: [docs.mapbox.com](https://docs.mapbox.com/)
- **Data questions**: Refer to WHO measles surveillance reports
- **Visualization bugs**: Check browser console and verify data schema

---

**Generated**: 2025
**Iteration**: 11
**Topic**: Measles Vaccination Coverage vs. Disease Outbreaks
**Technology**: Mapbox GL JS v3.0.1
**Projection**: Globe with atmospheric effects