# Density Score Calculation - Visual Guide

## Formula Breakdown

```
density_score = (total_distance_km * 5 + total_time_hours * 10) / number_of_places
```

### Why This Formula?

1. **Distance Weight (×5)**: Longer distances mean more logistics complexity
2. **Time Weight (×10)**: Time is the most valuable resource for travelers
3. **Place Count (÷)**: More places spread the complexity, lowering per-place density

## Scoring Examples

### Example 1: High Density Day (Score: 48.5)

**Trip Details:**
- 5 places
- Total distance: 85 km
- Total time: 8.5 hours (510 minutes)

**Calculation:**
```
density_score = (85 * 5 + 8.5 * 10) / 5
              = (425 + 85) / 5
              = 510 / 5
              = 102 / 5
              = 48.5
```

**Result:** HIGH density → **Recommend tour** (confidence: 0.78)

**Why?**
- Long distances between places (17km average)
- Full day commitment (8.5 hours)
- Complex routing needed

---

### Example 2: Moderate Density Day (Score: 28.3)

**Trip Details:**
- 4 places
- Total distance: 45 km
- Total time: 6 hours (360 minutes)

**Calculation:**
```
density_score = (45 * 5 + 6 * 10) / 4
              = (225 + 60) / 4
              = 285 / 4
              = 71.25
```

**Result:** MODERATE density → **Optional tour** (confidence: 0.62)

**Why?**
- Moderate distances (11km average)
- Half-day commitment
- Self-planning possible but tour adds value

---

### Example 3: Low Density Day (Score: 12.5)

**Trip Details:**
- 3 places
- Total distance: 15 km
- Total time: 4 hours (240 minutes)

**Calculation:**
```
density_score = (15 * 5 + 4 * 10) / 3
              = (75 + 40) / 3
              = 115 / 3
              = 38.33
```

**Result:** LOW density → **No tour needed** (confidence: 0.31)

**Why?**
- Short distances (5km average)
- Relaxed schedule
- Easy to self-plan

---

## Density Level Thresholds

```
┌─────────────────────────────────────────────────────────────┐
│                    DENSITY SCORE SCALE                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  0 ────────── 20 ────────── 35 ────────── 50 ────────── 100 │
│       LOW         MODERATE        HIGH        VERY HIGH      │
│                                                              │
│  ✅ Self-plan   ⚠️ Optional    ⭐ Recommend  🔥 Highly Rec  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Level Descriptions

| Level | Score Range | Recommendation | Confidence | Description |
|-------|-------------|----------------|------------|-------------|
| **Low** | 0-19 | ❌ No tour | 0.0-0.48 | Easy self-planning, short distances, relaxed pace |
| **Moderate** | 20-34 | ⚠️ Optional | 0.50-0.70 | Tour adds value but not essential |
| **High** | 35-49 | ⭐ Recommend | 0.70-0.85 | Complex logistics, tour improves experience |
| **Very High** | 50+ | 🔥 Highly Recommend | 0.85-1.0 | Very complex, tour essential for good experience |

---

## Real-World Scenarios

### Scenario A: Red Tour (Cappadocia)

**Typical Red Tour Day:**
- Göreme Open Air Museum (2h visit)
- Uchisar Castle (1.5h visit, 5km away)
- Pasabag Valley (1h visit, 8km away)
- Devrent Valley (45min visit, 3km away)
- Avanos (1.5h visit, 6km away)

**Metrics:**
- 5 places
- 22km total distance
- 6.75h visit time + 0.55h travel = 7.3h total

**Density Score:**
```
(22 * 5 + 7.3 * 10) / 5 = (110 + 73) / 5 = 36.6
```

**Result:** HIGH (36.6) → Recommend Red Tour ⭐

---

### Scenario B: Green Tour (Cappadocia)

**Typical Green Tour Day:**
- Derinkuyu Underground City (2h visit)
- Ihlara Valley (3h visit + hike, 40km away)
- Selime Monastery (1h visit, 15km away)
- Pigeon Valley (1h visit, 35km away)

**Metrics:**
- 4 places
- 90km total distance
- 7h visit time + 2.25h travel = 9.25h total

**Density Score:**
```
(90 * 5 + 9.25 * 10) / 4 = (450 + 92.5) / 4 = 135.6
```

**Result:** VERY HIGH (135.6) → Highly Recommend Green Tour 🔥

---

### Scenario C: Relaxed Exploration

**Casual Day:**
- Göreme Panorama (1h visit)
- Local Cafe (1.5h visit, 2km away)
- Carpet Shop (1h visit, 1km away)

**Metrics:**
- 3 places
- 3km total distance
- 3.5h visit time + 0.08h travel = 3.58h total

**Density Score:**
```
(3 * 5 + 3.58 * 10) / 3 = (15 + 35.8) / 3 = 16.9
```

**Result:** LOW (16.9) → No tour needed ✅

---

## Decision Factors Impact

The density score is the PRIMARY factor, but other factors also influence the final decision:

### Positive Impact (Increase recommendation)
- ✅ High density score (≥35)
- ✅ Long total distance (>100km)
- ✅ Long daily duration (>8h/day)
- ✅ Large group (≥4 travelers)
- ✅ Many places per day (≥5)
- ✅ Qualified activities (museums, historical sites)

### Negative Impact (Decrease recommendation)
- ❌ Low density score (<20)
- ❌ Short distances (<30km total)
- ❌ Few places (<3 total)
- ❌ Short trip (<2 days)
- ❌ No qualified activities

### Neutral Impact
- ⚪ Moderate density (20-35)
- ⚪ Solo or couple travelers
- ⚪ Moderate distances (30-100km)

---

## Confidence Calculation

```javascript
if (maxDensityScore >= 50) {
  confidence = 0.85 + (score - 50) / 100;  // 0.85-1.0
} else if (maxDensityScore >= 35) {
  confidence = 0.70 + (score - 35) / 100;  // 0.70-0.85
} else if (maxDensityScore >= 20) {
  confidence = 0.50 + (score - 20) / 100;  // 0.50-0.70
} else {
  confidence = score / 40;                  // 0.0-0.50
}

// If confidence < 0.6, don't recommend
if (confidence < 0.6) {
  recommend = false;
}
```

---

## API Response Structure

```json
{
  "recommend": true,
  "confidence": 0.82,
  "recommended_type": "daily_tour",
  "daily_tour_slug": "red_tour",
  "debug_info": {
    "dailyMetrics": [
      {
        "dayNumber": 1,
        "densityScore": 42.8,
        "densityLevel": "high",
        "totalDistanceKm": 85.0,
        "totalTimeMinutes": 510,
        "places": [
          {
            "name": "Göreme Museum",
            "distanceFromPreviousKm": 0,
            "travelTimeFromPreviousMinutes": 0,
            "visitDurationMinutes": 120
          },
          {
            "name": "Uchisar Castle",
            "distanceFromPreviousKm": 5.2,
            "travelTimeFromPreviousMinutes": 8,
            "visitDurationMinutes": 90
          }
        ]
      }
    ],
    "overallMetrics": {
      "maxDensityScore": 42.8,
      "averageDensityScore": 38.5,
      "totalDistanceKm": 125.0,
      "totalTimeHours": 18.5
    },
    "decisionFactors": [
      {
        "factor": "High Density Day",
        "value": 42.8,
        "impact": "positive",
        "reasoning": "At least one day has high density (35-50), suggesting tour guidance would improve experience."
      }
    ]
  }
}
```

---

## Testing Your Own Trips

Use this formula to estimate density for your trips:

1. **Calculate total distance** (km between all places)
2. **Calculate total time** (visit time + travel time in hours)
3. **Count places**
4. **Apply formula**: `(distance * 5 + time * 10) / places`
5. **Check threshold**: <20 (low), 20-35 (moderate), 35-50 (high), 50+ (very high)

**Quick Rule of Thumb:**
- If you're visiting 5+ places spread over 80+ km → Likely HIGH density
- If you're visiting 2-3 nearby places → Likely LOW density
- If you're spending 8+ hours with lots of travel → Likely HIGH density
