# CLAUDE.md - Globe Visualization 2: Temperature Heatmap

## Project Context

This is iteration 2 in a progressive Mapbox globe visualization learning series. Each iteration builds upon previous knowledge while introducing new web-learned techniques.

## Learning Methodology: Web-Enhanced Progressive Development

### Research Source
- **URL**: https://docs.mapbox.com/mapbox-gl-js/example/heatmap-layer/
- **Topic**: Heatmap layers for density-based visualization
- **Method**: WebFetch tool used to retrieve and analyze documentation
- **Application**: Heatmap techniques applied to climate data on globe projection

### Techniques Extracted from Documentation

1. **Heatmap Weight System**
   - Documentation showed how to use data properties to drive heatmap density
   - Applied to temperature anomalies: higher anomalies = higher weight
   - Interpolation from -1°C (0.1 weight) to +3°C (1.0 weight)

2. **Zoom-Based Intensity**
   - Learned intensity multiplier varies by zoom level
   - Implemented 0.8 (global) → 1.2 (regional) → 1.5 (local)
   - Ensures visibility at all scales

3. **Color Gradient Configuration**
   - Documentation demonstrated density-to-color mapping
   - Created diverging scheme: blue (cold) → green (neutral) → red (hot)
   - Applied to temperature anomaly visualization

4. **Radius Adaptation**
   - Learned radius controls point influence spread
   - Configured 15-35px range based on zoom
   - Balances smoothness vs precision

5. **Layer Transitions**
   - Documentation showed opacity management for layer switching
   - Implemented heatmap fade-out + circle fade-in
   - Seamless transition from density to detail view

## Improvement Over Iteration 1

### Iteration 1 Recap
- 100 population circles sized/colored by population
- Globe projection with auto-rotation
- Basic circle layer visualization

### Iteration 2 Advancements
- 280 temperature anomaly stations
- Primary heatmap layer for density visualization
- Secondary circle layer for detail
- Multi-scale visualization strategy
- Climate-focused data theme
- Zoom-responsive layer transitions

### Why Heatmap > Circles for This Data

**Circles (Iteration 1)**:
- Good: Precise individual values
- Limited: Pattern recognition requires mental work
- Best for: Discrete entities (cities, points of interest)

**Heatmap (Iteration 2)**:
- Good: Immediate pattern recognition
- Advanced: Shows regional trends and gradients
- Best for: Continuous phenomena (temperature, density, intensity)

## Technical Architecture

### File Structure
```
mapbox_globe_2/
├── index.html              # Main page with UI panels
├── src/
│   ├── index.js           # Map initialization and heatmap configuration
│   └── data/
│       └── temperature-data.js  # 280 stations GeoJSON
├── README.md              # User documentation
└── CLAUDE.md              # This file - development context
```

### Data Design

**GeoJSON Features**: Each station includes:
- `station`: Location name
- `temperature`: 2023 measured temperature
- `anomaly`: Deviation from 1951-1980 baseline
- `baseline`: Historical average temperature
- `year`: Data year (2023)

**Geographic Coverage**:
- North America: 20 stations
- South America: 10 stations
- Europe: 50 stations (showing high warming)
- Asia: 40 stations (mixed patterns)
- Middle East: 12 stations (extreme warming)
- Africa: 30 stations
- Oceania: 18 stations
- Russia/Arctic: 20 stations (extreme warming)
- Additional key locations: 80 stations

### Heatmap Paint Properties Explained

```javascript
// Weight: How much each point contributes
'heatmap-weight': Uses 'anomaly' property
  -1°C anomaly → 0.1 weight (minimal contribution)
  +3°C anomaly → 1.0 weight (maximum contribution)

// Intensity: Global multiplier by zoom
  Zoom 0: 0.8 (subtle at global view)
  Zoom 10: 1.5 (prominent at local view)

// Color: Density mapped to temperature gradient
  0 density: Transparent
  Low density: Blue (cooling)
  Medium density: Yellow (moderate warming)
  High density: Red (extreme warming)

// Radius: Point influence spread
  Zoom 0: 15px (broad patterns)
  Zoom 10: 35px (precise local density)

// Opacity: Layer visibility by zoom
  Zoom 0-7: 0.9 (heatmap dominant)
  Zoom 7-15: 0.9 → 0 (fade to circles)
```

### Circle Layer Strategy

- **Activation**: minzoom 7 (regional scale)
- **Purpose**: Show individual stations when zoomed in
- **Radius**: Based on anomaly magnitude (3-18px)
- **Color**: Matches heatmap gradient for consistency
- **Opacity**: 0 → 0.85 as heatmap fades
- **Stroke**: White outline for visibility

## Climate Data Patterns

The visualization reveals scientifically accurate patterns:

1. **Arctic Amplification**: Polar regions +2.5°C to +3.6°C (documented phenomenon)
2. **Continental vs Oceanic**: Land warming faster (thermal inertia effect)
3. **Latitude Gradient**: Higher latitudes showing greater warming
4. **Regional Hotspots**: Middle East, Central Asia, Mediterranean
5. **Tropical Moderation**: Equatorial regions showing less warming

## Development Notes

### Design Decisions

1. **Dark Theme**: Maximizes data visibility, reduces eye strain
2. **Diverging Colors**: Blue-to-red familiar from climate visualizations
3. **Auto-Rotation**: Reveals global patterns without user effort
4. **Smart Pause**: Rotation stops during interaction, resumes after
5. **Dual Layers**: Heatmap for patterns, circles for precision

### Performance Optimizations

- Heatmap rendering is GPU-accelerated via WebGL
- GeoJSON pre-loaded (no async data fetching)
- Layer visibility controlled by zoom (not rendering unused features)
- Popup generation on-demand (not pre-rendered)

### User Experience Enhancements

- **Legend**: Color scale shows anomaly meaning
- **Statistics**: Aggregate data provides context
- **Info Panel**: Explains methodology and data source
- **Popups**: Detailed station data on interaction
- **Controls**: Easy toggling between views
- **Fullscreen**: Immersive exploration mode

## Learning Outcomes

### Web Documentation Research Skills
- Successfully fetched and analyzed Mapbox heatmap documentation
- Extracted key paint properties and their usage patterns
- Applied documentation examples to novel use case (climate data)

### Mapbox Technique Mastery
- **New**: Heatmap layer type and all paint properties
- **Advanced**: Multi-layer visualization with zoom transitions
- **Refined**: Globe projection styling with atmosphere
- **Maintained**: Auto-rotation from iteration 1

### Climate Data Visualization
- Understood diverging color schemes for anomaly data
- Applied density visualization to continuous phenomena
- Designed multi-scale approach (global patterns → local detail)

## Future Enhancement Ideas

1. **Temporal Animation**: Show anomaly progression over decades
2. **Multiple Variables**: Precipitation, sea level, ice coverage
3. **3D Terrain**: Elevation-aware temperature visualization
4. **Real-time Data**: Integration with climate APIs
5. **Comparison Mode**: Side-by-side historical vs current
6. **Regional Focus**: Drill-down into specific areas
7. **Export Functionality**: Save visualizations as images

## Iteration Success Criteria

✅ **Web Learning**: Fetched and applied heatmap documentation
✅ **Heatmap Implementation**: All key paint properties configured correctly
✅ **Climate Data**: Realistic 280-station global dataset
✅ **Pattern Visibility**: Arctic amplification and regional trends clear
✅ **Multi-Scale**: Heatmap (global) + circles (local) working seamlessly
✅ **Globe Features**: Atmosphere, rotation, controls maintained
✅ **Documentation**: README explains heatmap advantages over circles
✅ **Code Quality**: Well-commented, organized, production-ready

## Connection to Learning Series

This iteration demonstrates:
- **Progressive complexity**: Building on globe 1's foundation
- **Web-enhanced learning**: Real documentation informing development
- **Technique diversity**: Different visualization for different data types
- **Professional quality**: Production-ready implementation

The series showcases how web research + iterative development = rapid skill acquisition in geospatial visualization.