refactor: update terminology from "optimal" to "model-suggested" for shelter locations across documentation and codebase

Author: noamjgal

CITATION.cff

@@ -7,7 +7,7 @@ date-released: 2026-07-17
 abstract: >-
   A real-time, browser-based interactive map for analyzing bomb shelter
   accessibility for Bedouin communities in the Eastern Negev. The tool
-  identifies underserved areas and proposes optimal new shelter locations
+  identifies underserved areas and proposes model-suggested new shelter locations
   using precomputed DBSCAN and K-means spatial clustering, with a static
   web frontend (deck.gl) and offline Python analysis scripts.
 authors:

README.md

@@ -1,6 +1,6 @@
 # Negev Shelter Access Analysis
 
-Interactive map for analyzing bomb shelter accessibility for Bedouin communities in the Eastern Negev. The app identifies underserved areas and proposes optimal new shelter locations using precomputed DBSCAN + K-means clustering. Covered in [Yediot Ahronot / Ynet](https://www.ynet.co.il/architecture/article/ry9tp9gtxe).
+Interactive map for analyzing bomb shelter accessibility for Bedouin communities in the Eastern Negev. The app identifies underserved areas and proposes model-suggested new shelter locations using precomputed DBSCAN + K-means clustering. Covered in [Yediot Ahronot / Ynet](https://www.ynet.co.il/architecture/article/ry9tp9gtxe).
 
 **Live demo:** [negevurbanresearch.github.io/shelter_access](https://negevurbanresearch.github.io/shelter_access/)
 

index.html

@@ -329,15 +329,15 @@ <h2>Data Layers</h2>
                     src="data/proposed.svg"
                     width="16"
                     height="16"
-                    alt="Optimal shelter icon"
+                    alt="Model-suggested shelter icon"
                   />
                 </div>
                 <label class="toggle-switch">
                   <input type="checkbox" id="optimalSheltersLayer" checked />
                   <span class="toggle-slider"></span>
                 </label>
                 <div class="layer-info">
-                  <span class="layer-label">Optimal Shelters</span>
+                  <span class="layer-label">Model-Suggested Shelters</span>
                   <span class="layer-description"
                     >Green plus icons • Algorithm sites</span
                   >
@@ -445,7 +445,7 @@ <h1 data-i18n="modal.title">The Right to Shelter</h1>
                   <p>
                     This analysis evaluates bomb shelter accessibility for
                     Bedouin communities in the Eastern Negev, identifying
-                    underserved areas and proposing optimal new shelter
+                    underserved areas and proposing model-suggested new shelter
                     locations using spatial data analysis and machine learning
                     methods.
                   </p>
@@ -481,7 +481,7 @@ <h3>Background & Context</h3>
                         formal and informal efforts have aimed to construct bomb
                         shelters for the widely dispersed Bedouin communities
                         living in unrecognized villages with a dangerous lack of
-                        shelter. However, identifying optimal locations has been
+                        shelter. However, identifying suitable locations has been
                         challenging due to the absence of formal data on
                         population distribution and density, as well as the
                         condition and location of local roads.
@@ -501,7 +501,7 @@ <h3>What This Analysis Shows</h3>
                       <p>
                         This tool analyzes bomb shelter accessibility within the
                         Negev's informal Bedouin settlements and proposes
-                        optimal locations for new shelters to broaden coverage.
+                        model-suggested locations for new shelters to broaden coverage.
                         On the accessibility grid,
                         <strong style="color: #14b814">green areas</strong>
                         signify neighborhoods with adequate shelter access under

js/app.js

@@ -198,7 +198,7 @@ class ShelterAccessApp {
             return precomputedCoverage;
         }
 
-        // Fallback to calculation for optimal shelters or missing data
+        // Fallback to calculation for model-suggested shelters or missing data
         return this.calculateShelterCoverage(shelter);
     }
 
@@ -242,7 +242,7 @@ class ShelterAccessApp {
             await this.initializeMap();
             this.updateAttribution();
 
-            // Initial load of optimal locations and coverage analysis
+            // Initial load of model-suggested locations and coverage analysis
             await this.updateOptimalLocations();
 
 
@@ -452,7 +452,7 @@ class ShelterAccessApp {
                         // Update visualization to refresh the heatmap
                         this.updateVisualization();
                     } else {
-                        // Otherwise just update optimal locations
+                        // Otherwise just update model-suggested locations
                         await this.updateOptimalLocations();
                     }
                 }
@@ -511,7 +511,7 @@ class ShelterAccessApp {
                         await this.loadAccessibilityData();
                     }
                 } else {
-                    // Update optimal locations when disabling heatmap
+                    // Update model-suggested locations when disabling heatmap
                     await this.updateOptimalLocations();
                 }
 
@@ -1232,7 +1232,7 @@ class ShelterAccessApp {
             }
         }
 
-        // === OPTIMAL ADDED SHELTERS (Green Squares) ===
+        // === MODEL-SUGGESTED ADDED SHELTERS (Green Squares) ===
         if (this.layerVisibility.optimalShelters && this.proposedShelters.length > 0 && !this.layerVisibility.accessibilityHeatmap) {
             // Added shelter squares with quality-based coloring
             layers.push(new deck.IconLayer({
@@ -1308,7 +1308,7 @@ class ShelterAccessApp {
             legendItems.push({
                 type: 'svg-icon',
                 className: 'optimal-shelter',
-                label: 'Optimal Shelters',
+                label: 'Model-Suggested Shelters',
                 iconSrc: 'data/proposed.svg',
                 description: 'Algorithm-generated sites'
             });
@@ -1751,15 +1751,15 @@ class ShelterAccessApp {
     }
 
     /**
-     * Update optimal locations in real-time
+     * Update model-suggested locations in real-time
      */
     async updateOptimalLocations() {
         if (this.isAnalyzing) return;
 
         try {
             this.isAnalyzing = true;
 
-            // Load optimal locations from precomputed data
+            // Load model-suggested locations from precomputed data
             const optimalLocations = await this.spatialAnalyzer.getOptimalLocations(this.numNewShelters);
 
             // Store directly - they're already in the right format
@@ -1772,7 +1772,7 @@ class ShelterAccessApp {
             this.updateCoverageAnalysis();
 
         } catch (error) {
-            console.error('Loading optimal locations failed:', error);
+            console.error('Loading model-suggested locations failed:', error);
         } finally {
             this.isAnalyzing = false;
         }
@@ -1792,7 +1792,7 @@ class ShelterAccessApp {
         const stats = data.statistics;
         const newSheltersSelected = this.proposedShelters.length;
 
-        // Calculate coverage from selected optimal shelters
+        // Calculate coverage from selected model-suggested shelters
         let newBuildingsCovered = 0;
         if (newSheltersSelected > 0) {
             newBuildingsCovered = this.proposedShelters.reduce((sum, shelter) => sum + (shelter.buildings_covered || 0), 0);

js/spatial-analysis-simple.js

@@ -1,5 +1,5 @@
 /**
- * Simple Spatial Analysis Module - Loads Precomputed Optimal Shelter Locations
+ * Simple Spatial Analysis Module - Loads Precomputed Model-Suggested Shelter Locations
  * Uses precalculated data from shelter_optimizer.py DBSCAN + Greedy algorithm
  */
 
@@ -41,7 +41,7 @@ class SimpleSpatialAnalyzer {
       // Load pre-filtered polygon layers
       await this.loadPolygonLayers();
 
-      // Load default optimal data
+      // Load default model-suggested data
       await this.loadOptimalData(this.coverageRadius);
 
       return true;
@@ -180,24 +180,24 @@ class SimpleSpatialAnalyzer {
   }
 
   /**
-   * Load precomputed optimal shelter data
+   * Load precomputed model-suggested shelter data
    */
   async loadOptimalData(radius) {
-    // Only support 'optimal_shelters' scenario
+    // Only support the model-suggested shelter scenario
     const cacheKey = `optimal_shelters_${radius}m`;
     if (this.optimalData.has(cacheKey)) {
       return this.optimalData.get(cacheKey);
     }
     try {
-      console.log(`Loading optimal data: ${cacheKey}...`);
+      console.log(`Loading model-suggested data: ${cacheKey}...`);
       const response = await fetch(`data/optimal_locations/${cacheKey}.json`);
       if (!response.ok) {
         throw new Error(`Failed to load: ${response.status}`);
       }
       const data = await response.json();
       this.optimalData.set(cacheKey, data);
       console.log(
-        `✓ Loaded ${data.optimal_locations.length} optimal locations for ${cacheKey}`
+        `✓ Loaded ${data.optimal_locations.length} model-suggested locations for ${cacheKey}`
       );
       return data;
     } catch (error) {
@@ -226,7 +226,7 @@ class SimpleSpatialAnalyzer {
   }
 
   /**
-   * Get top N optimal shelter locations
+   * Get top N model-suggested shelter locations
    */
   async getOptimalLocations(numShelters) {
     const data = await this.loadOptimalData(this.coverageRadius);
@@ -239,7 +239,7 @@ class SimpleSpatialAnalyzer {
   }
 
   /**
-   * Get requested shelter evaluation with specific pairing to optimal locations
+   * Get requested shelter evaluation with specific pairing to model-suggested locations
    */
   getRequestedShelterEvaluation(numNewShelters = 0) {
     const cacheKey = `optimal_shelters_${this.coverageRadius}m`;
@@ -271,10 +271,10 @@ class SimpleSpatialAnalyzer {
       (a, b) => (a.buildings_covered || 0) * 7 - (b.buildings_covered || 0) * 7
     );
 
-    // Get the top N optimal locations we're actually building
+    // Get the top N model-suggested locations we're actually building
     const optimalLocations = data.optimal_locations.slice(0, numNewShelters);
 
-    // Pair worst requested with best optimal, but only up to the number we're building
+    // Pair worst requested with best model suggestion, up to the number being built
     const pairedShelters = [];
     for (let i = 0; i < maxReplacements; i++) {
       const requested = sortedRequested[i];
@@ -292,7 +292,7 @@ class SimpleSpatialAnalyzer {
           requestedCoverage: requestedCoverage,
           optimalCoverage: optimalCoverage,
           requestedRank: i + 1, // Rank among worst requested (1 = worst)
-          optimalRank: i + 1, // Rank among selected optimal (1 = best)
+          optimalRank: i + 1, // Rank among selected model suggestions (1 = best)
         });
       }
     }
@@ -344,7 +344,7 @@ class SimpleSpatialAnalyzer {
       0
     );
 
-    // Existing coverage (total - new from all optimal locations)
+    // Existing coverage (total - new from all model-suggested locations)
     const existingCoverage =
       (stats.total_people_covered || 0) - (stats.new_people_covered || 0);
     const totalCoverage = existingCoverage + newPeopleCovered;

scripts/generate_shelter_statistics.py

@@ -252,7 +252,7 @@ def create_coverage_analysis(theme):
 
         ax.text(radii[-1] + 8, existing_coverage[-1], 'Existing',
                 va='center', fontsize=12, color=existing_line_color)
-        ax.text(radii[-1] + 8, total_coverage[-1], '+500 Optimal',
+        ax.text(radii[-1] + 8, total_coverage[-1], '+500 Model-Suggested',
                 va='center', fontsize=12, color=theme['optimal_color'])
 
         ax.set_xlabel('Coverage Radius (m)', fontsize=14)
@@ -297,7 +297,7 @@ def create_coverage_analysis(theme):
 
         ax.text(x[0] - width/2, buildings_existing[0] + 300, 'Existing',
                 ha='center', fontsize=10, color='#000000')
-        ax.text(x[0] + width/2, buildings_total[0] + 300, '+500 Optimal',
+        ax.text(x[0] + width/2, buildings_total[0] + 300, '+500 Model-Suggested',
                 ha='center', fontsize=10, color='#000000')
 
         ax.text(bars1[-1].get_x() + bars1[-1].get_width()/2., bars1[-1].get_height() + 100,
@@ -354,7 +354,7 @@ def calculate_incremental_coverage(building_coords, existing_shelters, optimal_s
     initial_coverage = np.sum(covered_mask) / total_buildings * 100
     coverage_percentages = [initial_coverage]
 
-    # Add optimal shelters one by one
+    # Add model-suggested shelters one by one
     for shelter in optimal_shelters:
         # Vectorized distance calculation for uncovered buildings only
         uncovered_indices = np.where(~covered_mask)[0]
@@ -477,10 +477,10 @@ def load_accessibility_data():
                     'num_shelters': len(optimal_shelters)
                 }
 
-                print(f"  {radius}m: {len(optimal_shelters)} optimal shelters, "
+                print(f"  {radius}m: {len(optimal_shelters)} model-suggested shelters, "
                       f"final coverage: {coverage_progression[-1]:.1f}%")
         except FileNotFoundError:
-            print(f"Optimal locations data for {radius}m not found")
+            print(f"Model-suggested locations data for {radius}m not found")
             continue
 
     return radius_data, coverage_radii
@@ -491,7 +491,7 @@ def print_coverage_statistics():
     coverage_radii = [100, 150, 200, 250, 300]
 
     print("\n=== SHELTER COVERAGE STATISTICS ===\n")
-    print(f"{'Radius':<10} {'Existing Coverage':<20} {'With +500 Optimal':<20} {'Improvement':<15}")
+    print(f"{'Radius':<10} {'Existing Coverage':<20} {'With +500 Model-Suggested':<26} {'Improvement':<15}")
     print("-" * 65)
 
     total_buildings = None
@@ -532,7 +532,7 @@ def load_buildings_per_shelter_data():
         print("Shelter coverage precomputed data not found, skipping comparison chart")
         return None, None, None
 
-    # Load building coordinates for recalculating optimal coverage
+    # Load building coordinates for recalculating model-suggested coverage
     try:
         with open('data/buildings.geojson', 'r') as f:
             buildings_data = json.load(f)
@@ -573,11 +573,11 @@ def load_buildings_per_shelter_data():
                 optimal_avg.append(avg_coverage)
                 radii.append(radius)
         except FileNotFoundError:
-            print(f"Optimal locations data for {radius}m not found")
+            print(f"Model-suggested locations data for {radius}m not found")
             continue
 
     if not radii:
-        print("No optimal location data found, skipping comparison chart")
+        print("No model-suggested location data found, skipping comparison chart")
         return None, None, None
 
     existing_avg = [existing_stats[f'{r}m']['average_buildings_per_shelter'] for r in radii]
@@ -586,7 +586,7 @@ def load_buildings_per_shelter_data():
 
 
 def create_buildings_per_shelter_comparison(theme, radii, existing_avg, optimal_avg):
-    """Compare buildings per shelter: existing vs optimal locations"""
+    """Compare buildings per shelter: existing vs model-suggested locations"""
     if radii is None:
         return
 
@@ -601,14 +601,14 @@ def create_buildings_per_shelter_comparison(theme, radii, existing_avg, optimal_
 
     ax.set_xlabel('Coverage Radius (meters)')
     ax.set_ylabel('Average Buildings per Shelter')
-    ax.set_title('Shelter Efficiency: Existing vs Optimal Locations', pad=15)
+    ax.set_title('Shelter Efficiency: Existing vs Model-Suggested Locations', pad=15)
     ax.set_xticks(x)
     ax.set_xticklabels([f'{r}m' for r in radii])
 
     # Direct labeling on first bar group
     ax.text(x[0] - width/2, existing_avg[0] + 0.8, 'Existing',
             ha='center', fontsize=8, color=theme['existing_color'])
-    ax.text(x[0] + width/2, optimal_avg[0] + 0.8, '+500 Optimal',
+    ax.text(x[0] + width/2, optimal_avg[0] + 0.8, '+500 Model-Suggested',
             ha='center', fontsize=8, color=theme['optimal_color'])
 
     setup_tufte_axis(ax)

scripts/shelter_optimizer_ensemble.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
 Enhanced DBSCAN + K-means Shelter Optimizer
-Finds optimal shelter locations using two complementary methods:
+Finds model-optimized shelter locations using two complementary methods:
 1. DBSCAN variants (24 configurations) to find density-based clusters  
 2. K-means clustering (k=750, 1500) for systematic space coverage
 Then uses advanced selection strategies.
@@ -26,7 +26,7 @@ def __init__(self):
         self.N_RUNS_PER_RADIUS = 1  # Single run since DBSCAN is deterministic
         self.N_KMEANS_SEEDS = 2  # Multiple K-means random seeds
 
-        # DBSCAN parameters to test (eps should be <= coverage radius for optimal results)
+        # DBSCAN parameters to test (eps should be <= coverage radius for model-optimized results)
         self.DBSCAN_EPS_MULTIPLIERS = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]  # 10 multipliers from 0.1 to 1.0
         self.DBSCAN_MIN_SAMPLES = [10]  # Single min_samples parameter
 
@@ -927,7 +927,7 @@ def run_full_optimization(self, buildings_file, shelters_file, output_dir='data/
         print(f"Target: {self.TARGET_SHELTERS} shelters per radius")
         print(f"Radii: {self.RADII_TO_TEST} meters")
         print(f"Methods: Original DBSCAN + Enhanced DBSCAN (24 configs) + K-means (k=750,1500 × {self.N_KMEANS_SEEDS} seeds)")
-        print(f"Strategy: Generate diverse candidates, then optimal non-overlapping selection")
+        print(f"Strategy: Generate diverse candidates, then model-optimized non-overlapping selection")
         print(f"Multithreading: {'Enabled' if self.USE_MULTITHREADING else 'Disabled'} ({self.MAX_WORKERS} workers)" if self.USE_MULTITHREADING else "Multithreading: Disabled")
         print("=" * 70)
         print("📁 Loading data...")