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

# Globe Visualization 6: Global University Rankings & Research Output

**Interactive Filtering & Data-Driven Exploration - Iteration 6**

This is the sixth iteration in a progressive web-enhanced learning series demonstrating advanced Mapbox GL JS techniques with globe projection. This iteration focuses on **interactive filtering and UI controls** for exploring global research data.

## 🌍 Theme: Global University Rankings & Research Output

This visualization showcases the world's top 120 research universities with comprehensive metrics:

- **Rankings**: Global positioning from #1 to #120
- **Research Score**: Composite measure of research excellence (55-99)
- **Publications**: Annual research output (5,500-19,800 papers)
- **Citations**: Total academic citations (122K-456K)
- **Research Funding**: Annual funding in millions ($400M-$4,200M)
- **Nobel Prizes**: Total laureates affiliated with institution (0-161)

## 📚 Learning Progression

### Previous Iterations:
1. **Iteration 1**: Population circles - Basic globe setup
2. **Iteration 2**: Temperature heatmap - Color gradients
3. **Iteration 3**: Economic data - Advanced expressions
4. **Iteration 4**: Digital infrastructure - Multi-layer composition
5. **Iteration 5**: (Educational theme foundation)
6. **Iteration 6** (this): Interactive filtering & UI controls

## 🔬 Web-Enhanced Learning

**Research Source**: Mapbox GL JS Filter Markers Example
**URL**: https://docs.mapbox.com/mapbox-gl-js/example/filter-markers/

### Key Filtering Techniques Learned and Applied:

#### 1. **Layer-Based Filtering with setFilter()**
From the web source, I learned to use `map.setFilter()` to dynamically control which features are rendered:

```javascript
// Apply complex filter expression to layer
map.setFilter('universities-layer', filterExpression);
```

This is the core filtering mechanism that updates the visualization in real-time based on user selections.

#### 2. **Filter Expression Patterns**
The web source demonstrated several filter expression types that I implemented:

**Equality Filtering** (`==`):
```javascript
['==', 'icon', symbol]  // From web source
['==', 'region', selectedRegion]  // My application
```

**Range Filtering** (`<=`, `>=`):
```javascript
// My implementation for ranking and metric thresholds
['<=', ['get', 'ranking'], maxRanking]
['>=', ['get', 'publications'], minPublications]
```

**Compound Filtering** (`all`, `in`):
```javascript
// Combining multiple conditions
filterExpression = ['all',
    ['in', ['get', 'region'], ['literal', selectedRegions]],
    ['<=', ['get', 'ranking'], 120],
    ['>=', ['get', 'publications'], minPubs]
];
```

#### 3. **UI Control Implementation**
The web source showed checkbox-based layer visibility toggling. I expanded this to include:

**Checkbox Filters** (from web source pattern):
```javascript
checkbox.addEventListener('change', () => {
    // Update filter state
    applyFilters();
});
```

**Range Sliders** (my enhancement):
```javascript
slider.addEventListener('input', (e) => {
    currentFilters.minValue = parseInt(e.target.value);
    applyFilters();
});
```

#### 4. **Dynamic Layer Updates**
Learned from web source that filters can be changed without reloading data:
```javascript
// Efficient re-filtering without data reload
map.setFilter('layer-id', newFilterExpression);
```

This enables smooth, real-time filtering as users adjust controls.

#### 5. **Query Rendered Features for Statistics**
Extended the pattern to calculate statistics on filtered data:
```javascript
const features = map.queryRenderedFeatures({
    layers: ['universities-layer']
});
// Calculate aggregate statistics from visible features
```

## 🎯 Advanced Filtering Features

### Multi-Criteria Filtering System

**Region Filters** (Checkbox-based):
- North America (27 universities)
- Europe (25 universities)
- Asia-Pacific (42 universities)
- Middle East (9 universities)
- Africa (6 universities)
- Latin America (11 universities)
- All (default - 120 universities)

**Ranking Range** (Slider):
- Filter by top N universities (10, 20, 30...120)
- Dynamic adjustment from elite tier to broader selection

**Publications Threshold** (Slider):
- Filter by minimum annual research output
- Range: 0 to 20,000 publications
- Step: 1,000 publications

**Citations Threshold** (Slider):
- Filter by minimum total citations
- Range: 0 to 500,000 citations
- Step: 25,000 citations

**Research Funding** (Slider):
- Filter by minimum annual funding
- Range: $0M to $4,500M
- Step: $100M

**Nobel Prizes** (Slider):
- Filter by minimum Nobel laureates
- Range: 0 to 161 prizes
- Step: 5 prizes

### Interactive Controls

**Reset Filters**: One-click restoration of all filters to default state

**Pause/Resume Rotation**: Toggle auto-rotation for detailed examination

## 🎨 Visual Design

### Color-Coded Research Excellence

Universities are colored by **Research Score** using an 8-stop gradient:

- **95-99** (Royal Blue `#0066ff`): Exceptional - MIT, Harvard, Oxford, Cambridge
- **90-94** (Deep Sky Blue `#00bfff`): Outstanding - Top 20 institutions
- **85-89** (Lime Green `#32cd32`): Excellent - Top 30-40
- **80-84** (Gold `#ffd700`): Very Good - Top 50
- **75-79** (Orange `#ffa500`): Good - Top 60-70
- **70-74** (Tomato `#ff6347`): Above Average - Top 80
- **65-69** (Crimson `#dc143c`): Average - Top 100
- **55-64** (Deep Red `#8b0000`): Emerging - Top 120

### Size-Coded Rankings

Circle radius inversely proportional to ranking (better rank = larger):
- **Rank 1-10**: 14-18px radius (Largest - most prominent)
- **Rank 11-25**: 11-14px radius
- **Rank 26-50**: 9-11px radius
- **Rank 51-75**: 7-9px radius
- **Rank 76-100**: 5-7px radius
- **Rank 101-120**: 4-5px radius (Smallest)

### Dynamic Labels

Top 30 universities display text labels with:
- Name overlay on hover
- Size scaled by ranking (9-13px)
- White text with black halo for readability
- Smart placement to avoid overlap

## 📊 Comprehensive Data Model

### University Properties

Each of the 120 universities includes:

```javascript
{
    name: "University Name",
    country: "Country",
    region: "Region",
    ranking: 1-120,              // Global position
    publications: 5500-19800,    // Annual research papers
    citations: 122000-456000,    // Total citations
    funding: 400-4200,           // Annual funding ($M)
    nobelPrizes: 0-161,          // Total Nobel laureates
    researchScore: 55-99         // Composite excellence score
}
```

### Regional Distribution

- **Asia-Pacific**: 42 universities (35%)
- **North America**: 27 universities (22.5%)
- **Europe**: 25 universities (21%)
- **Latin America**: 11 universities (9%)
- **Middle East**: 9 universities (7.5%)
- **Africa**: 6 universities (5%)

### Top 10 Universities Highlighted

1. **MIT** (USA) - Research Score: 98
2. **Stanford** (USA) - Research Score: 97
3. **Harvard** (USA) - Research Score: 99 | Nobel Prizes: 161
4. **UC Berkeley** (USA) - Research Score: 96 | Nobel Prizes: 110
5. **Cambridge** (UK) - Research Score: 97 | Nobel Prizes: 121
6. **Oxford** (UK) - Research Score: 98 | Nobel Prizes: 72
7. **Imperial College** (UK) - Research Score: 94
8. **UCLA** (USA) - Research Score: 93
9. **Columbia** (USA) - Research Score: 94 | Nobel Prizes: 101
10. **UCL** (UK) - Research Score: 93

## 🔧 Technical Implementation

### Filter Expression Architecture

The filtering system uses Mapbox's expression syntax with compound conditions:

```javascript
let filterExpression = ['all'];  // AND operator for multiple conditions

// Region filter (OR within selected regions)
if (selectedRegions.length > 0) {
    filterExpression.push([
        'in',
        ['get', 'region'],
        ['literal', selectedRegions]
    ]);
}

// Ranking filter (less than or equal to max)
filterExpression.push(['<=', ['get', 'ranking'], maxRank]);

// Publication threshold (greater than or equal to min)
filterExpression.push(['>=', ['get', 'publications'], minPubs]);

// Apply to layer
map.setFilter('universities-layer', filterExpression);
```

### Real-Time Statistics Calculation

After each filter update, statistics are recalculated from visible features:

```javascript
function updateStatistics() {
    const features = map.queryRenderedFeatures({
        layers: ['universities-layer']
    });

    const count = features.length;
    const avgResearch = features.reduce((sum, f) =>
        sum + f.properties.researchScore, 0) / count;
    const totalPubs = features.reduce((sum, f) =>
        sum + f.properties.publications, 0);
    const totalCitations = features.reduce((sum, f) =>
        sum + f.properties.citations, 0);
    const totalNobel = features.reduce((sum, f) =>
        sum + f.properties.nobelPrizes, 0);

    // Update UI displays
}
```

### Interactive Popup Information

Hover over any university to see detailed metrics:
- University name and location
- Global ranking and research score
- Publications and citations
- Research funding
- Nobel Prize count

## 🎓 Key Improvements Over Previous Iterations

### From Web Research:
1. **Dynamic filtering** using `setFilter()` method
2. **Compound filter expressions** with `all`, `in`, `>=`, `<=` operators
3. **Checkbox-based UI controls** for categorical filtering
4. **Real-time layer updates** without data reloading
5. **Feature querying** for statistics calculation

### My Enhancements:
1. **Multi-dimensional filtering** (6 independent criteria)
2. **Range sliders** for continuous metrics
3. **Coordinated filter state** management
4. **Live statistics dashboard** updating with filters
5. **Mutual exclusivity** for "All" vs specific region selection
6. **Reset functionality** for user convenience
7. **Comprehensive research dataset** (120 universities, 6 metrics each)

### Progressive Learning Synthesis:
- **Iteration 1-3 foundations**: Circle styling, color gradients, expressions
- **Iteration 4 multi-layer**: Layer composition techniques
- **Iteration 6 innovation**: Interactive filtering and exploration UI

## 🚀 Usage

1. **Open** `index.html` in a modern web browser
2. **Explore** the globe - drag, zoom, rotate to navigate
3. **Filter by Region** - Select one or more geographic regions
4. **Adjust Ranking** - Use slider to focus on top N universities
5. **Filter by Metrics** - Set minimum thresholds for publications, citations, funding, Nobel prizes
6. **View Statistics** - Live dashboard shows aggregate metrics for filtered selection
7. **Hover Universities** - Detailed popup with all metrics
8. **Reset** - Clear all filters with one click
9. **Control Rotation** - Pause/resume auto-rotation as needed

## 📁 Project Structure

```
mapbox_globe_6/
├── index.html              # Main visualization with UI controls
├── src/
│   ├── index.js           # Filtering logic and interactivity
│   └── data/
│       └── data.js        # 120 universities with 6 metrics each
├── README.md              # This documentation
└── CLAUDE.md             # Development context
```

## 🎯 Web Research Integration Quality

### Source Attribution
- **Technique**: Filter markers/features by property values
- **Original Example**: Checkbox toggles for icon-based filtering
- **Adaptation**: Extended to multi-criteria, multi-type filtering system
- **Novel Synthesis**: Combined checkbox, slider, and compound expression patterns

### Progressive Learning Demonstrated
- **Previous**: Static visualizations, pre-filtered data
- **This Iteration**: Dynamic, user-controlled exploration
- **Improvement**: Interactive filtering enables data-driven discovery
- **Innovation**: 6-dimensional filtering space for research data

### Mapbox Best Practices Applied
✅ Efficient filter expressions (no data reloading)
✅ Feature querying for dynamic statistics
✅ Proper use of `all`, `in`, `>=`, `<=` operators
✅ UI responsiveness with live updates
✅ Layer-based filtering with `setFilter()`
✅ Clean separation of data, logic, and presentation

## 🔍 Use Cases

**Research Policy Makers**: Identify universities meeting specific funding and output criteria

**Prospective Students**: Explore institutions by region and research strength

**Academic Collaborators**: Find universities with strong citation impact

**Funding Agencies**: Analyze research output patterns by geographic distribution

**University Administrators**: Benchmark against peer institutions across multiple metrics

## 📈 Statistics Dashboard

Real-time metrics update with every filter adjustment:

- **Universities**: Count of currently visible institutions
- **Avg Research Score**: Mean excellence score of filtered set
- **Total Publications**: Sum of annual research output
- **Total Citations**: Aggregate citation impact
- **Total Nobel Prizes**: Sum of laureates across filtered universities

## 🌟 Key Takeaways

### Technical Mastery:
- Complex filter expression composition
- Multi-criteria filtering architecture
- Real-time feature querying and aggregation
- Coordinated UI state management
- Dynamic statistics calculation

### Visual Excellence:
- 8-stop color gradient for research scores
- Inverse size scaling for rankings
- Professional dark theme with glassmorphism
- Responsive layout for mobile and desktop
- Clear legends and intuitive controls

### Educational Value:
- Demonstrates practical filtering patterns from Mapbox docs
- Shows extension from simple to complex filtering
- Illustrates data-driven exploration workflows
- Provides reusable filtering architecture

### Progressive Learning:
- **Wave 1 (Iter 1-5)**: Foundation building
- **Wave 2 (Iter 6-12)**: Enhancement & styling ← **We are here**
- Next: More sophisticated interactions, animations, advanced UI patterns

---

*This iteration demonstrates mastery of interactive filtering techniques from Mapbox documentation, applied to a rich educational research dataset with multi-dimensional exploration capabilities.*

## 🔗 Web Source Reference

**Mapbox GL JS Filter Markers Example**
https://docs.mapbox.com/mapbox-gl-js/example/filter-markers/

**Key Concepts Learned:**
- Filter expressions syntax
- Dynamic layer filtering with `setFilter()`
- Checkbox-based UI controls
- Real-time visibility updates
- Feature property access with `['get', 'property']`

**Applied & Extended:**
- Multiple filter types (checkbox, slider)
- Compound expressions with `all` operator
- Range-based filtering (`>=`, `<=`)
- Multi-value filtering with `in` operator
- Statistics calculation on filtered data
- Coordinated filter state management