# CLAUDE.md - Globe Visualization 7 Project Guidelines

## Project Context

This is **Iteration 7** of the Mapbox Globe Progressive Web-Enhanced Learning series. This iteration focuses on timeline animation techniques for temporal data visualization, learning from Mapbox's timeline animation example.

## Quick Start Commands

### Local Development Server
```bash
# Python 3
cd /home/ygg/Workspace/sandbox/infinite-agents/mapbox_test/mapbox_globe_7
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js (if installed)
npx http-server -p 8000
```

Access at: http://localhost:8000

### VS Code Live Server
1. Install "Live Server" extension
2. Right-click `index.html`
3. Select "Open with Live Server"

## File Structure

```
mapbox_globe_7/
├── index.html              # Main HTML with timeline UI
├── src/
│   ├── index.js           # Timeline animation logic
│   └── data/
│       └── data.js        # 80 education platforms, 8 years
├── README.md              # Full documentation
└── CLAUDE.md              # This file
```

## Architecture Overview

### Timeline Animation Pattern (Learned from Web)

**Source:** https://docs.mapbox.com/mapbox-gl-js/example/timeline-animation/

**Key Pattern:**
1. **Preprocess temporal data** → Add year index to each feature
2. **Use setFilter()** → Apply time-based filters efficiently
3. **Range slider control** → Manual timeline scrubbing
4. **Interval-based playback** → Automatic progression
5. **Synchronized updates** → UI state matches map state

### Data Transformation Flow

```javascript
// Input: Nested year data
feature.properties.yearData = {
  "2010": { enrollment, courses, completionRate },
  "2012": { ... }
}

// Processing: Flatten to temporal features
processedFeatures = features × years with yearIndex

// Filtering: Efficient year selection
map.setFilter('layer', ['==', 'yearIndex', selectedYearIndex])
```

## Key Implementation Details

### Timeline Control System
- **Slider Input:** HTML5 range input (0-7 for 8 years)
- **Event Handling:** Input event triggers filterByYear()
- **Auto-pause:** Scrubbing stops playback automatically
- **Play/Pause:** setInterval() for 1.5s per year progression

### Visual Encoding Strategy
- **Size:** Exponential scale based on enrollment
- **Color:** Growth rate gradient (red → yellow → green → blue)
- **Stroke:** White highlight for 10M+ platforms
- **Labels:** Conditional visibility (5M+ threshold)

### Performance Optimizations
1. **Preprocessed data** - Calculations done once at load
2. **Filter-based animation** - No layer recreation
3. **Conditional labeling** - Only major platforms labeled
4. **Efficient expressions** - Interpolate/step for styling

## Mapbox-Specific Patterns

### Globe Projection Setup
```javascript
const map = new mapboxgl.Map({
    projection: 'globe',
    style: 'mapbox://styles/mapbox/dark-v11',
    zoom: 1.8,
    pitch: 20
});
```

### Timeline Filtering
```javascript
map.setFilter('education-circles', ['==', 'yearIndex', yearIndex]);
map.setFilter('education-labels', ['==', 'yearIndex', yearIndex]);
```

### Data-Driven Styling
```javascript
'circle-radius': [
    'interpolate',
    ['exponential', 1.5],
    ['get', 'enrollment'],
    0, 3,
    50000000, 22,
    150000000, 32
]
```

## Code Quality Standards

### JavaScript Style
- ES6+ features (const/let, arrow functions, template literals)
- Clear function names (filterByYear, calculateGrowthRate)
- Comment blocks for major sections
- Error handling for edge cases

### Data Quality
- Realistic enrollment numbers
- Accurate geographic coordinates
- Consistent property naming
- Complete temporal coverage (8 years per platform)

### UI/UX Considerations
- Responsive timeline controls
- Clear year display
- Intuitive slider interaction
- Real-time statistics feedback
- Informative hover popups

## Debugging Tips

### Timeline Not Updating
1. Check yearIndex assignment in preprocessing
2. Verify filter expression syntax
3. Confirm slider value range (0-7)
4. Test filterByYear() function in console

### Visual Encoding Issues
1. Inspect feature properties in console
2. Check Mapbox expression syntax
3. Verify data ranges for interpolation
4. Test with simplified expressions

### Performance Problems
1. Check feature count (should be ~640)
2. Verify filter efficiency
3. Monitor frame rate during animation
4. Simplify visual expressions if needed

## Browser Console Testing

```javascript
// Check processed data
console.log(processedData.features.length); // Should be ~640

// Test filtering manually
filterByYear(3); // Jump to 2016

// Inspect current year
console.log(currentYearIndex, years[currentYearIndex]);

// Toggle playback
togglePlayback();
```

## Extension Ideas

### Easy Additions
1. Speed control for playback (0.5x, 1x, 2x)
2. Year range selector (start/end)
3. Platform type filter (MOOC, University, etc.)
4. Keyboard shortcuts (space = play/pause, arrows = navigate)

### Medium Complexity
1. Multi-metric visualization (enrollment vs courses)
2. Regional comparison mode
3. Growth trend charts
4. Search functionality for platforms

### Advanced Features
1. Export timeline as video/GIF
2. Custom data upload
3. Side-by-side year comparison
4. 3D bar charts for enrollment

## Web Learning Application

### What Was Learned
1. **Timeline preprocessing pattern** - Transform nested temporal data
2. **Filter-based animation** - Efficient layer updates
3. **Range slider integration** - Map state synchronization
4. **Playback control system** - setInterval management
5. **Aggregate calculation** - Real-time statistics

### How It Was Applied
- Transformed 80 platforms with nested yearData into 640 flat features
- Implemented year-based filtering with yearIndex property
- Built play/pause system with auto-pause on scrubbing
- Created synchronized UI (slider, year display, statistics)
- Added growth rate calculation for temporal analysis

### Innovation Beyond Source
- Multi-metric temporal data (enrollment, courses, completion)
- Growth rate calculation and visualization
- Aggregate statistics panel
- Exponential size scaling for better hierarchy
- Auto-rotation with interaction detection

## Mapbox Token

**Working Token:** `pk.eyJ1IjoibGludXhpc2Nvb2wiLCJhIjoiY2w3ajM1MnliMDV4NDNvb2J5c3V5dzRxZyJ9.wJukH5hVSiO74GM_VSJR3Q`

This token is included in the source code and works for this visualization.

## Related Documentation

- [Mapbox Timeline Animation Example](https://docs.mapbox.com/mapbox-gl-js/example/timeline-animation/)
- [Mapbox Expressions](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/)
- [Mapbox Globe Projection](https://docs.mapbox.com/mapbox-gl-js/example/globe/)
- [Mapbox setFilter API](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#setfilter)

## Success Metrics

This iteration successfully demonstrates:
- ✓ Timeline animation learned from web source
- ✓ Temporal data preprocessing pattern
- ✓ Filter-based animation approach
- ✓ Manual timeline scrubbing control
- ✓ Automatic playback functionality
- ✓ Real-time aggregate statistics
- ✓ Multi-year growth visualization
- ✓ 80+ education platforms worldwide
- ✓ Globe-appropriate temporal visualization

## Iteration Evolution

**Previous Focus (Iterations 1-6):**
- Basic globe setup and styling
- Single-layer visualizations
- Static data snapshots
- Simple interactivity

**This Iteration (7):**
- Timeline animation system
- Temporal data exploration
- Multi-year data processing
- Playback controls
- Growth rate analysis

**Future Directions (8+):**
- 3D extrusions for temporal depth
- Custom animations and transitions
- Real-time data integration
- Advanced temporal analysis
- Multi-view coordination

---

**Generated by:** Sub Agent 3
**Date:** 2025-10-09
**Web Source:** Mapbox Timeline Animation Example
**Iteration:** 7 of Progressive Mapbox Globe Series