297 lines
7.7 KiB
Markdown
297 lines
7.7 KiB
Markdown
# 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
|