# 📊 Visual Guide: How Scoring Works

## Complete Flow from Property to Score

```
┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: Property Listing from Properstar                       │
│                                                                 │
│ "Rustic farm, 10 hectares, Spain, €45,000"                    │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: GPT Analysis (via prompt.txt)                          │
│                                                                 │
│ Prompt asks GPT to evaluate:                                   │
│  1. Market Garden → GPT gives: 4/5                            │
│  2. Guest Accommodation → GPT gives: 5/5                      │
│  3. Workshop → GPT gives: 3/5                                 │
│  4. Rental Units → GPT gives: 4/5                             │
│  5. Location → GPT gives: 3/5                                 │
│  6. Local Market → GPT gives: 4/5                             │
│  Risk Profile → GPT gives: "Gemiddeld"                        │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: Score Conversion (analyze_from_urls.py)                │
│                                                                 │
│ Convert GPT scores (1-5) to points:                            │
│  • 5 → +3 points  (excellent)                                  │
│  • 4 → +2 points  (good)                                       │
│  • 3 → +1 point   (average)                                    │
│  • 2 → -1 point   (poor)                                       │
│  • 1 → -2 points  (very poor)                                  │
│                                                                 │
│ Our example becomes:                                            │
│  1. Market Garden: 4 → +2 points                               │
│  2. Guest: 5 → +3 points                                       │
│  3. Workshop: 3 → +1 point                                     │
│  4. Rental: 4 → +2 points                                      │
│  5. Location: 3 → +1 point                                     │
│  6. Market: 4 → +2 points                                      │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 4: Apply Criterion Weights                                │
│                                                                 │
│ Multiply by importance weights:                                 │
│  1. Market Garden: +2 × 2.0 = 4.0                              │
│  2. Guest: +3 × 2.5 = 7.5                                      │
│  3. Workshop: +1 × 2.0 = 2.0                                   │
│  4. Rental: +2 × 1.5 = 3.0                                     │
│  5. Location: +1 × 3.0 = 3.0                                   │
│  6. Market: +2 × 1.5 = 3.0                                     │
│                                                                 │
│ Total weighted points: 22.5                                     │
│ Total weights: 12.5                                             │
│ Average: 22.5 ÷ 12.5 = 1.8                                     │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 5: Apply Risk Factor                                      │
│                                                                 │
│ Risk: "Gemiddeld" → 0.9 multiplier (10% penalty)              │
│                                                                 │
│ Final Score: 1.8 × 0.9 = 1.62                                  │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 6: Save to Database                                       │
│                                                                 │
│ analysis_output.csv:                                            │
│  • Overall Score: 1.62                                          │
│  • Market Garden: 4                                             │
│  • Guest: 5                                                     │
│  • Workshop: 3                                                  │
│  • Rental: 4                                                    │
│  • Location: 3                                                  │
│  • Market: 4                                                    │
│  • Risk: Gemiddeld                                              │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 7: Filter Against Thresholds (config.json)                │
│                                                                 │
│ Thresholds set:                                                 │
│  • Overall Score: ≥ 1.0  → ✅ PASS (1.62 ≥ 1.0)               │
│  • Market Garden: ≥ 3    → ✅ PASS (4 ≥ 3)                    │
│  • Guest: ≥ 3            → ✅ PASS (5 ≥ 3)                    │
│  • Workshop: ≥ 2         → ✅ PASS (3 ≥ 2)                    │
│  • Rental: ≥ 3           → ✅ PASS (4 ≥ 3)                    │
│  • Location: ≥ 3         → ✅ PASS (3 ≥ 3)                    │
│  • Market: ≥ 3           → ✅ PASS (4 ≥ 3)                    │
│  • Max Risk: Gemiddeld   → ✅ PASS                             │
│                                                                 │
│ require_all: false (OR logic)                                   │
│ → At least ONE criterion passes → ✅ KEEP THIS PROPERTY        │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│ RESULT: Property stays in favorites! ✅                         │
└─────────────────────────────────────────────────────────────────┘
```

---

## Example 2: Property That Gets Unfavorited

```
Property: "Old barn, small plot, remote location, €35,000"

GPT Scores:
  1. Market Garden: 2/5  (small plot)
  2. Guest: 2/5  (poor accessibility)
  3. Workshop: 3/5  (barn exists)
  4. Rental: 2/5  (too remote)
  5. Location: 2/5  (far from everything)
  6. Market: 2/5  (no local market)
  Risk: Hoog

Converted Points:
  1. Market Garden: 2 → -1 point
  2. Guest: 2 → -1 point
  3. Workshop: 3 → +1 point
  4. Rental: 2 → -1 point
  5. Location: 2 → -1 point
  6. Market: 2 → -1 point

Weighted:
  1. Market Garden: -1 × 2.0 = -2.0
  2. Guest: -1 × 2.5 = -2.5
  3. Workshop: +1 × 2.0 = +2.0
  4. Rental: -1 × 1.5 = -1.5
  5. Location: -1 × 3.0 = -3.0
  6. Market: -1 × 1.5 = -1.5

Total: -8.5 / 12.5 = -0.68

Risk penalty: -0.68 × 0.7 (high risk) = -0.48

Final Score: -0.48

Filter Check (thresholds from config.json):
  • Overall Score: -0.48 < 1.0  → ❌ FAIL
  • Market Garden: 2 < 3         → ❌ FAIL
  • Guest: 2 < 3                 → ❌ FAIL
  • Workshop: 3 ≥ 2              → ✅ PASS
  • Rental: 2 < 3                → ❌ FAIL
  • Location: 2 < 3              → ❌ FAIL
  • Market: 2 < 3                → ❌ FAIL
  • Risk: Hoog > Gemiddeld       → ❌ FAIL

require_all: false (OR logic)
→ Only Workshop passes
→ BUT Overall Score < 1.0 → ❌ UNFAVORITE THIS PROPERTY
```

---

## Key Decision Points

### Where to Intervene:

```
┌──────────────────────┬────────────────┬──────────┬────────────┐
│ What You Want        │ Edit           │ Cost     │ Effort     │
├──────────────────────┼────────────────┼──────────┼────────────┤
│ Different evaluation │ prompt.txt     │ $3-5     │ Easy       │
│ Different importance │ analyze...py   │ $3-5     │ Medium     │
│ Different filtering  │ config.json    │ Free     │ Very Easy  │
│ Different penalties  │ analyze...py   │ $3-5     │ Medium     │
│ Visual changes       │ map_viewer.html│ Free     │ Medium     │
└──────────────────────┴────────────────┴──────────┴────────────┘
```

---

## Weight Impact Visualization

**Current weights (Location is most important):**

```
Location         ████████████████ 3.0 (24%)
Guest            ████████████     2.5 (20%)
Market Garden    ████████         2.0 (16%)
Workshop         ████████         2.0 (16%)
Rental Units     ██████           1.5 (12%)
Local Market     ██████           1.5 (12%)
                 ─────────────────────────
                 Total: 12.5 (100%)
```

**If you change to prioritize farming:**

```
Market Garden    ████████████████ 4.0 (28%)
Location         ████████████     3.0 (21%)
Workshop         ████████         2.5 (18%)
Guest            ██████           2.0 (14%)
Local Market     ██████           2.0 (14%)
Rental Units     ████             1.0 (7%)
                 ─────────────────────────
                 Total: 14.5 (100%)
```

Impact:
- Properties good for farming get much higher scores
- Properties good for tourism get lower scores
- Overall score range shifts

---

## Score Ranges Explained

```
Score Range │ Meaning              │ Action
────────────┼──────────────────────┼─────────────────────
 2.0 - 3.0  │ Outstanding          │ Top priority
 1.5 - 2.0  │ Excellent            │ Strong candidate
 1.0 - 1.5  │ Good                 │ Promising
 0.0 - 1.0  │ Average              │ Consider carefully
-1.0 - 0.0  │ Below average        │ Likely skip
-2.0 - -1.0 │ Poor                 │ Definitely skip
-3.0 - -2.0 │ Very poor            │ Auto-unfavorite
```

**Your current threshold: 0.0**
- Keeps properties that are "average" or better
- Removes "below average" and "poor"

**If you set threshold to 1.5:**
- Only keeps "excellent" properties
- Much more selective

---

## Testing Your Changes

### Before making changes:
```bash
# Check current distribution
cd scraper
/usr/bin/python3 -c "
import pandas as pd
df = pd.read_csv('analysis_output.csv')
print(df['Gewogen Score'].describe())
"
```

Output shows:
```
count    186.000000
mean       0.450000
std        0.850000
min       -1.200000
25%       -0.100000
50%        0.400000   ← Median
75%        0.950000
max        2.300000
```

### After changing weights/prompt:
Re-analyze and check distribution again to see impact.

---

**Need more help? See [CRITERIA_CUSTOMIZATION_GUIDE.md](CRITERIA_CUSTOMIZATION_GUIDE.md) for detailed examples!**