algo-rank-bayesian
用貝氏平均替評論數不一的項目公平排名
中文翻譯
---
name: "algo-rank-bayesian"
description: "用貝氏平均（Bayesian averaging）結合觀察到的評分和先驗期望來排名。當使用者需要替評論數不一的項目排名、建立能公平對待低樣本項目的「最高評分」榜單、或實作 IMDB 風格的加權評分時使用，即使他們說的是「加權平均評分」、「IMDB 公式」或「帶先驗的排名」也一樣。"
metadata:
category: "WP-44 排名演算法"
tags: ["ranking", "bayesian-average", "rating", "prior"]
---
# 貝氏平均評分（Bayesian Average Rating）
## 概述
貝氏平均把項目觀察到的平均評分，和先驗（全域平均）結合起來，用評論數當權重。公式：BR = (C × m + Σrᵢ) / (C + n)，其中 m=全域平均、C=信心參數、n=該項目的評論數、Σrᵢ=該項目評分的總和。評論少的項目會被拉向全域平均。
## 何時使用
**觸發條件：**
- 要用連續評分（1-5 顆星）替評論數不一的項目排名
- IMDB 風格的「Top 250」榜單，要在品質和人氣之間取得平衡
- 任何評分彙總的情境，不想讓只有少數高分的新項目霸榜
**何時不要用：**
- 二元（讚／倒讚）資料（改用 Wilson Score）
- 所有項目的評論數都差不多時（簡單平均就夠了）
## 演算法
```
鐵律：先驗能防止小樣本的極端值
沒有先驗的話，一則 5 星評論就能讓項目變成「最棒的」。
貝氏平均會在全域平均 m 的位置加上 C 張「幽靈票」，
把小樣本的項目往平均值收縮。C 控制收縮的力道：
C 越高 = 越保守（幽靈票越多）。
典型的 C = 所有項目評論數的中位數。
```
### 階段 1：輸入驗證
計算：所有項目的全域平均評分（m）、選定 C（幽靈票數）。每個項目要蒐集：評論數（n）、平均評分或評分總和。
**關卡：** m 已算出、C 已選定、項目資料齊全。
### 階段 2：核心演算法
1. 全域平均：m = Σ(所有評分) / Σ(所有評論數)
2. 每個項目的貝氏平均：BR = (C × m + n × avg_rating) / (C + n)
3. 依 BR 由高到低排名
4. n >> C 的項目，BR ≈ avg_rating（資料主導）。n << C 的項目，BR ≈ m（先驗主導）。
### 階段 3：驗證
檢查：評論很少的項目應該接近全域平均。評論很多的項目應該接近它們實際的平均。排名要符合直覺。
**關卡：** 已確認收縮行為，榜首項目同時具備高評分「和」足夠的評論數。
### 階段 4：輸出
回傳依貝氏分數排好的項目。
## 輸出格式
```json
{
"rankings": [{"item": "Movie_A", "bayesian_avg": 8.7, "raw_avg": 9.1, "reviews": 5000, "shrinkage": 0.04}],
"metadata": {"global_mean": 6.8, "confidence_C": 500, "items_ranked": 10000}
}
```
## 範例
### 輸入輸出範例
**輸入：** m=7.0, C=100。項目 A：avg=9.5, n=5。項目 B：avg=8.5, n=500。
**預期：** BR_A = (100×7 + 5×9.5)/(105) = 7.12。BR_B = (100×7 + 500×8.5)/(600) = 8.25。B 排名較高。
### 邊界情況
| 輸入 | 預期 | 原因 |
|-------|----------|-----|
| n=0 | BR = m（全域平均） | 沒有資料，完全由先驗決定 |
| n=100000 | BR ≈ 原始平均 | 龐大的樣本壓過先驗 |
| 所有項目的 n 相同 | 等同於簡單平均排名 | 收縮是一致的，排序不變 |
## 常見陷阱
- **C 的選擇是主觀的**：常見選法：評論數的中位數、讓評分算「可靠」的最低評論數（IMDB 用的是投票數前 25,000 名的投票者，並設有最低票數）。沒有放諸四海皆準的值。
- **評分尺度很重要**：5 分制的 4.0 和 10 分制的 4.0 意思不同。要正規化，或使用同一個尺度。
- **各類別專屬的先驗**：「恐怖片」的平均 4.0 可能很出色，但「吉卜力」的 4.0 可能低於平均。可以考慮用類別層級的先驗。
- **時間偏誤**：老項目會累積評論。除非你對近期評論加重權重，否則老牌項目會永遠霸佔「top」榜單。
- **刷評論**：貝氏平均擋不住操弄評論，它只能緩解小樣本的極端值。要搭配詐欺偵測。
## 腳本
| 腳本 | 說明 | 用法 |
|--------|-------------|-------|
| `scripts/bayesian_avg.py` | 用貝氏平均替項目排名，處理小樣本的極端值 | `python scripts/bayesian_avg.py --help` |
執行 `python scripts/bayesian_avg.py --verify` 可以跑內建的健全性測試。
## 參考資料
- IMDB 加權評分公式，見 `references/imdb-formula.md`
- 多維度貝氏評分，見 `references/multi-dimensional.md`英文原文
---
name: "algo-rank-bayesian"
description: "Apply Bayesian averaging to rank items by combining observed ratings with prior expectations. Use this skill when the user needs to rank items with varying review counts, build a 'top rated' list that handles low-sample items fairly, or implement IMDB-style weighted rating — even if they say 'weighted average rating', 'IMDB formula', or 'ranking with prior'."
metadata:
category: "WP-44 排名演算法"
tags: ["ranking", "bayesian-average", "rating", "prior"]
---
# Bayesian Average Rating
## Overview
Bayesian average combines an item's observed average rating with a prior (global average), weighted by review count. Formula: BR = (C × m + Σrᵢ) / (C + n) where m=global mean, C=confidence parameter, n=item reviews, Σrᵢ=sum of item ratings. Items with few reviews are pulled toward the global mean.
## When to Use
**Trigger conditions:**
- Ranking items by continuous ratings (1-5 stars) with varying review counts
- IMDB-style "Top 250" lists that balance quality and popularity
- Any rating aggregation where new items shouldn't dominate with few high ratings
**When NOT to use:**
- For binary (upvote/downvote) data (use Wilson Score instead)
- When all items have similar review counts (simple average is sufficient)
## Algorithm
```
IRON LAW: The Prior Protects Against Small-Sample Extremes
Without a prior, a single 5-star review makes an item "the best."
The Bayesian average adds C "phantom votes" at the global mean m,
shrinking small-sample items toward average. C controls shrinkage
strength: higher C = more conservative (more phantom votes).
Typical C = median review count across all items.
```
### Phase 1: Input Validation
Compute: global mean rating (m) across all items, choose C (phantom vote count). Collect per item: review count (n), average rating, or sum of ratings.
**Gate:** m computed, C selected, item data available.
### Phase 2: Core Algorithm
1. Global mean: m = Σ(all ratings) / Σ(all review counts)
2. Bayesian average per item: BR = (C × m + n × avg_rating) / (C + n)
3. Rank items by BR descending
4. For items with n >> C, BR ≈ avg_rating (data dominates). For n << C, BR ≈ m (prior dominates).
### Phase 3: Verification
Check: items with very few reviews should be near global mean. Items with many reviews should be near their actual average. Ranking is intuitive.
**Gate:** Shrinkage behavior confirmed, top items have both high ratings AND sufficient reviews.
### Phase 4: Output
Return ranked items with Bayesian scores.
## Output Format
```json
{
"rankings": [{"item": "Movie_A", "bayesian_avg": 8.7, "raw_avg": 9.1, "reviews": 5000, "shrinkage": 0.04}],
"metadata": {"global_mean": 6.8, "confidence_C": 500, "items_ranked": 10000}
}
```
## Examples
### Sample I/O
**Input:** m=7.0, C=100. Item A: avg=9.5, n=5. Item B: avg=8.5, n=500.
**Expected:** BR_A = (100×7 + 5×9.5)/(105) = 7.12. BR_B = (100×7 + 500×8.5)/(600) = 8.25. B ranks higher.
### Edge Cases
| Input | Expected | Why |
|-------|----------|-----|
| n=0 | BR = m (global mean) | No data, fully prior-driven |
| n=100000 | BR ≈ raw average | Massive sample overwhelms prior |
| All items same n | Equivalent to simple average ranking | Uniform shrinkage, ordering preserved |
## Gotchas
- **C selection is subjective**: Common choices: median review count, minimum reviews for "reliable" rating (IMDB uses top 25,000 voters with min votes). No universally correct value.
- **Rating scale matters**: A 4.0 on a 5-point scale means something different than 4.0 on a 10-point scale. Normalize or use the same scale.
- **Category-specific priors**: A 4.0 average in "horror movies" might be exceptional, while 4.0 in "Studio Ghibli" might be below average. Consider category-level priors.
- **Temporal bias**: Old items accumulate reviews. Unless you weight recent reviews more, established items permanently dominate "top" lists.
- **Review gaming**: Bayesian average doesn't prevent review manipulation — it only mitigates small-sample extremes. Pair with fraud detection.
## Scripts
| Script | Description | Usage |
|--------|-------------|-------|
| `scripts/bayesian_avg.py` | Rank items using Bayesian average to handle small-sample extremes | `python scripts/bayesian_avg.py --help` |
Run `python scripts/bayesian_avg.py --verify` to execute built-in sanity tests.
## References
- For IMDB weighted rating formula, see `references/imdb-formula.md`
- For multi-dimensional Bayesian rating, see `references/multi-dimensional.md`