infinite-agents-public/mapbox_test/mapbox_globe_2/README.md

# Globe Visualization 2: Global Temperature Anomaly Heatmap

An advanced Mapbox GL JS visualization demonstrating heatmap layers on globe projection to reveal global temperature anomaly patterns.

## Overview

This iteration builds upon Globe Visualization 1 by introducing **heatmap layers** as the primary visualization technique. Instead of discrete circles, the heatmap creates a continuous density-based visualization that reveals warming patterns across the planet.

## Web Learning Source

**Documentation URL**: https://docs.mapbox.com/mapbox-gl-js/example/heatmap-layer/

### Heatmap Techniques Learned

1. **Data-Driven Weight System**
   - Heatmap weight property controls how much each data point contributes to density
   - Applied temperature anomaly values to weight calculation
   - Higher anomalies (more warming) create more intense heat zones
   - Weight interpolation: -1°C (0.1 weight) → +3°C (1.0 weight)

2. **Zoom-Responsive Intensity**
   - Heatmap intensity property multiplies the weight based on zoom level
   - Lower intensity at global view (0.8) for subtle patterns
   - Higher intensity at regional view (1.5) for detailed analysis
   - Creates optimal visibility at all zoom levels

3. **Dynamic Color Gradients**
   - Heatmap color maps density to diverging temperature color scheme
   - Blue tones represent cooling anomalies
   - Yellow/orange/red tones show warming progression
   - Transparency at low density prevents visual clutter

4. **Adaptive Radius Configuration**
   - Heatmap radius controls the spread of each point's influence
   - Larger radius (15-35px) at global view for pattern visibility
   - Smaller radius at closer zoom for precision
   - Balance between smoothness and detail

5. **Multi-Layer Opacity Transitions**
   - Heatmap fades out as zoom increases (opacity 0.9 → 0)
   - Circle layer fades in at higher zoom (opacity 0 → 0.85)
   - Seamless transition from density view to individual stations
   - Optimal visualization technique for each zoom range

## Improvements Over Iteration 1

### Visualization Approach

**Iteration 1** (Population Circles):
- Discrete circles for each city
- Size and color showed individual values
- Good for identifying specific locations
- Patterns required mental aggregation

**Iteration 2** (Temperature Heatmap):
- Continuous density-based visualization
- Heat zones show regional patterns immediately
- Better for understanding global trends
- Natural clustering reveals warming hotspots

### Pattern Recognition

The heatmap excels at revealing:
- **Arctic amplification**: Extreme warming visible in northern regions
- **Continental vs oceanic patterns**: Land warming faster than oceans
- **Regional climate zones**: Natural clustering by latitude and geography
- **Warming intensity gradients**: Smooth transitions show climate complexity

### Technical Advantages

1. **Performance**: Heatmap rendering is GPU-accelerated
2. **Scalability**: Handles 280+ points without visual overcrowding
3. **Context**: Density visualization provides immediate context
4. **Adaptability**: Zoom-responsive layers optimize for any scale

## Dataset

**Global Temperature Anomalies (2023)**
- **Data Points**: 280 weather monitoring stations worldwide
- **Baseline Period**: 1951-1980 average temperatures
- **Anomaly Range**: -0.8°C to +3.6°C
- **Coverage**: All continents, ocean islands, Arctic regions

### Key Patterns Visible

1. **Arctic Amplification**: Arctic regions show +2.5°C to +3.6°C anomalies
2. **Continental Warming**: Europe, Central Asia showing +1.5°C to +2.5°C
3. **North American Heat**: Southwestern USA reaching +2.1°C
4. **Polar Contrast**: Greenland and Svalbard extreme warming
5. **Tropical Moderation**: Equatorial regions showing +0.8°C to +1.2°C

## Features

### Heatmap Layer (Zoom 0-15)
- Density-based visualization using temperature anomaly weights
- Diverging color gradient (blue → green → yellow → red)
- Zoom-responsive intensity and radius
- Reveals global warming patterns at a glance

### Circle Layer (Zoom 7+)
- Individual station markers appear at higher zoom
- Size based on anomaly magnitude
- Color matches heatmap gradient for consistency
- Interactive popups with detailed station data

### Globe Features
- Professional dark theme optimized for data visibility
- Atmospheric shell with star field background
- Auto-rotation with smart pause on user interaction
- Smooth transitions between visualization modes

### Interactive Controls
- **Auto-Rotate Toggle**: Enable/disable globe rotation
- **Layer Toggle**: Switch between global heatmap and detail views
- **Reset View**: Return to initial globe position and state
- **Navigation**: Pan, zoom, rotate controls
- **Fullscreen**: Immersive viewing mode

### Information Panels
- **Legend**: Color gradient scale showing anomaly ranges
- **Statistics**: Global aggregate data (avg, max, min anomalies)
- **Info Panel**: Methodology and data period explanation
- **Station Popups**: Detailed temperature data on hover

## Technical Implementation

### Heatmap Configuration

```javascript
'heatmap-weight': Based on temperature anomaly value
'heatmap-intensity': Zoom-responsive multiplier (0.8 → 1.5)
'heatmap-color': Diverging gradient for temperature
'heatmap-radius': Adaptive spread (15px → 35px)
'heatmap-opacity': Fade out at high zoom (0.9 → 0)
```

### Layer Strategy

- **Heatmap layer**: maxzoom 15 (global to regional)
- **Circle layer**: minzoom 7 (regional to local)
- **Overlapping range**: Smooth opacity transitions
- **Optimal technique**: Right visualization for each scale

## Usage

1. Replace `mapboxgl.accessToken` in `src/index.js` with your Mapbox token
2. Open `index.html` in a modern web browser
3. View the global temperature heatmap on the rotating globe
4. Zoom in to see individual station circles emerge
5. Hover over stations for detailed temperature data
6. Use controls to customize viewing experience

## Climate Data Insights

The heatmap visualization clearly reveals:

- **Arctic Crisis**: Polar regions warming 2-3x faster than global average
- **Land-Ocean Contrast**: Continental warming exceeds oceanic warming
- **Regional Variation**: Middle East and Central Asia showing intense warming
- **Southern Moderation**: Antarctica and Southern Ocean showing less warming
- **Urban Heat Islands**: Major cities showing elevated anomalies

## Why Heatmap for Climate Data?

Heatmaps are particularly effective for temperature anomaly visualization because:

1. **Continuous phenomenon**: Temperature varies smoothly across geography
2. **Pattern recognition**: Density reveals warming trends immediately
3. **Visual impact**: Heat zones communicate severity intuitively
4. **Scale flexibility**: Works from global view to regional detail
5. **Scientific convention**: Familiar visualization in climate science

## Learning Progression

**Globe 1 → Globe 2 Evolution**:
- Discrete points → Continuous density
- Individual values → Regional patterns
- Manual interpretation → Immediate insights
- Single technique → Multi-scale visualization

## Next Steps

Future iterations could explore:
- 3D terrain with elevation-aware temperature data
- Time-series animation showing anomaly progression
- Multiple heatmap layers for different climate variables
- Custom interpolation for seasonal variations
- Real-time climate data integration

## Technologies

- **Mapbox GL JS v3.0.1**: Web mapping framework
- **Globe projection**: Spherical view of Earth
- **Heatmap layers**: GPU-accelerated density visualization
- **GeoJSON**: Geographic data format
- **WebGL**: Hardware-accelerated rendering

## Credits

- **Visualization**: Custom Mapbox GL JS implementation
- **Heatmap Technique**: Learned from Mapbox documentation
- **Climate Data**: Synthesized from global monitoring networks
- **Baseline Period**: 1951-1980 temperature averages
- **Data Year**: 2023 annual anomalies

---

**Part of**: Mapbox Globe Learning Series - Progressive visualization mastery through web-enhanced learning