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

# Globe Visualization 3: Global Economic Dashboard

## Overview

An advanced Mapbox GL JS globe visualization demonstrating sophisticated data-driven styling with multi-dimensional economic indicators. This iteration builds upon previous globe examples by implementing complex expression-based styling that encodes multiple data properties simultaneously.

## Learning Source

**URL:** [Mapbox Data-Driven Circle Colors Example](https://docs.mapbox.com/mapbox-gl-js/example/data-driven-circle-colors/)

**Key Concepts Learned:**
1. **Interpolate Expressions** - Smooth, continuous value mapping for gradients and proportional sizing
2. **Match Expressions** - Categorical data mapping (studied but applied interpolate for continuous data)
3. **Multi-Property Styling** - Encoding multiple metrics in a single layer (size + color)
4. **Data Access Patterns** - Using `['get', 'property']` to dynamically access feature properties

## Expression Techniques Implemented

### 1. Interpolate for Continuous Color Mapping
```javascript
'circle-color': [
  'interpolate',
  ['linear'],
  ['get', 'growthRate'],
  -25, '#b2182b',   // Deep red for severe contraction
  -10, '#ef8a62',   // Light red
  0, '#f7f7f7',     // White for zero growth
  4, '#67a9cf',     // Light blue for moderate growth
  8, '#2166ac'      // Deep blue for strong growth
]
```

This creates a **diverging color scheme** where negative growth appears red, zero is neutral white, and positive growth is blue—perfect for economic growth data.

### 2. Interpolate for Proportional Sizing
```javascript
'circle-radius': [
  'interpolate',
  ['linear'],
  ['get', 'gdpPerCapita'],
  0, 3,          // Minimum size for low GDP
  10000, 8,
  30000, 15,
  70000, 25      // Maximum size for high GDP
]
```

Circle size scales proportionally with GDP per capita, making wealthier nations visually prominent.

### 3. Zoom-Based Dynamic Adjustments
```javascript
'circle-opacity': [
  'interpolate',
  ['linear'],
  ['zoom'],
  1, 0.7,    // Lower opacity at global view
  4, 0.8,
  8, 0.9     // Higher opacity when zoomed in
]
```

Visual properties adapt to zoom level, ensuring clarity at all scales.

## Dataset

**Economic Indicators for 120 Countries:**
- **GDP per Capita** - Economic output per person (USD)
- **Growth Rate** - Annual GDP growth percentage (-25% to +12%)
- **Development Index** - Human Development Index (0.35 to 0.96)
- **Trade Volume** - Total trade in billions USD

**Geographic Coverage:**
- North America (3 countries)
- South America (10 countries)
- Europe (30 countries)
- Middle East (12 countries)
- Africa (35 countries)
- Asia (25 countries)
- Oceania (6 countries)
- Caribbean & Central America (12 countries)

## Features

### Multi-Dimensional Data Encoding
- **Size Channel**: Encodes one metric (default: GDP per capita)
- **Color Channel**: Encodes another metric (default: Growth rate)
- **Interactive Toggle**: Switch metrics dynamically to explore different relationships

### Expression-Based Styling Benefits
1. **Performance**: Client-side rendering without re-fetching data
2. **Smooth Transitions**: Interpolated values create seamless gradients
3. **Dynamic Updates**: Change metrics without reloading data
4. **Zoom Responsiveness**: Styles adapt to interaction context

### Advanced Color Schemes
- **Diverging Scale** (Growth Rate): Red → White → Blue for negative/zero/positive
- **Sequential Scales**: Single-hue progressions for GDP, Development, Trade
- **Perceptually Uniform**: ColorBrewer-inspired palettes for accurate data perception

### Interactive Controls
- **Dual Metric Selection**: Independent control of size and color encoding
- **Preset Views**: Four recommended metric combinations
  - Economic Performance (Wealth vs Growth)
  - Trade & Development (Trade vs HDI)
  - Development Momentum (HDI vs Growth)
  - Growth Leaders (Growth vs GDP)
- **Detailed Popups**: All four metrics displayed on hover

### Professional Design
- Globe projection with atmospheric effects
- Continuous rotation for cinematic presentation
- Zoom-adaptive labels and stroke widths
- Dynamic legend generation based on active metrics

## Technical Implementation

### Expression Architecture
The visualization leverages three core Mapbox expression types:

1. **Data Property Access**: `['get', 'propertyName']`
2. **Linear Interpolation**: `['interpolate', ['linear'], input, ...stops]`
3. **Conditional Logic**: Implemented through stop arrays with threshold values

### Performance Optimizations
- Single GeoJSON source with all data
- Client-side expression evaluation
- Minimal layer count (2 layers: circles + labels)
- Efficient zoom-based rendering

### Code Organization
```
mapbox_globe_3/
├── index.html           # Main application shell
├── src/
│   ├── index.js         # Map initialization and expression logic
│   └── data/
│       └── economic-data.js   # 120-country GeoJSON dataset
├── README.md            # This file
└── CLAUDE.md           # Development documentation
```

## Improvement Over Previous Iterations

**Iteration 1 (Population Circles):**
- Single metric visualization
- Basic circle styling
- Static color scheme

**Iteration 2 (Temperature Heatmap):**
- Density visualization
- Heatmap layer type
- Single data dimension

**Iteration 3 (Economic Dashboard):**
- ✅ **Multi-dimensional encoding** (2 metrics simultaneously)
- ✅ **Advanced expressions** (interpolate with multiple stops)
- ✅ **Dynamic metric switching** (4x4 = 16 possible combinations)
- ✅ **Sophisticated color theory** (diverging + sequential schemes)
- ✅ **Professional UI/UX** (preset views, dynamic legends)
- ✅ **Complex real-world data** (4 properties × 120 countries)

## How Multi-Property Styling Reveals Insights

### Example Analysis: GDP vs Growth
When sizing by GDP and coloring by growth:
- **Large blue circles** = Wealthy, growing economies (Ireland, Poland)
- **Large red circles** = Wealthy, contracting economies (Venezuela, Lebanon)
- **Small blue circles** = Poor but fast-growing (Rwanda, Ethiopia)
- **Small red circles** = Poor and struggling (Afghanistan, Syria)

This single view reveals economic patterns impossible to see with single-metric visualizations.

### Example Analysis: Development vs Trade
When sizing by Development Index and coloring by Trade Volume:
- Countries with high development but low trade (Norway, Switzerland)
- Emerging trade hubs (Vietnam, Poland)
- Trade giants (China, Germany, USA)
- Development-trade imbalances

## Usage

1. **Install**: No build required—open `index.html` in a modern browser
2. **Configure**: Add your Mapbox access token to `src/index.js`:
   ```javascript
   mapboxgl.accessToken = 'YOUR_TOKEN_HERE';
   ```
3. **Explore**: Use dropdown menus to select different metric combinations
4. **Interact**: Hover over countries for detailed data, zoom to explore regions

## Learning Outcomes

### Mapbox Expression Mastery
- Understanding interpolate vs step vs match expressions
- Building complex data-driven styles
- Optimizing expression performance

### Data Visualization Principles
- Multi-dimensional encoding strategies
- Color theory for diverging/sequential data
- Interactive exploration design patterns

### Economic Data Insights
- Global wealth distribution patterns
- Growth vs development relationships
- Trade volume geographic clustering

## Future Enhancement Ideas

1. **Time Series**: Animate economic changes over years
2. **Filtering**: Add data range sliders for subset exploration
3. **Additional Metrics**: Employment, inflation, debt-to-GDP
4. **Comparison Mode**: Side-by-side globes with different metrics
5. **Case Expressions**: Add categorical classifications (developed/developing/frontier)
6. **Step Expressions**: Create discrete economic tiers
7. **Statistical Overlays**: Add mean/median lines to legends

## Resources

- [Mapbox Expressions Documentation](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/)
- [Data-Driven Styling Examples](https://docs.mapbox.com/mapbox-gl-js/example/)
- [ColorBrewer Color Schemes](https://colorbrewer2.org/)
- [Human Development Index Data](https://hdr.undp.org/)

## License

Educational demonstration project. Economic data sourced from World Bank, IMF, and UN databases (representative values for demonstration purposes).