# 計算公式與校準方法

## 目錄

1. 賠率與基準
2. 單一事件與選邊
3. 收縮與分數凱利
4. 聯合情境
5. 校準與樣本外評估
6. 設計與檢查摘要

## 賠率與基準

統一以押一單位、贏時淨賺的倍數表示：

\[
b_{contract}=\frac{1-c}{c},\quad b_{decimal}=d-1,\quad
b_{American}=\begin{cases} A/100 & A>0\\100/|A| & A<0.\end{cases}
\]

押 X 淨賺 Y 時為 `Y / X`；Y 含本金時為 `Y / X - 1`。`payout_kind` 必須明確。

\[
c'=c(1+\varphi),\qquad b'=\frac{1-c'}{c'}(1-\kappa).
\]

非合約賠率先以隱含成本 `1 / (1 + b)` 套用成本型費用，等價於把費用計入風險金額。`total_cost` 覆蓋成本型費用；`net_odds` 覆蓋兩種費用，避免重扣。

\[
q_{mid}=\frac{bid_{YES}+ask_{YES}}2,\qquad
q_{devig}=\frac{1/(1+b_{YES})}{1/(1+b_{YES})+1/(1+b_{NO})}.
\]

去抽水採扣費前公開賠率；需要其他口徑時直接提供有來源的 q。沒有買賣價時不自動把單一成交價當基準。

## 單一事件與選邊

\[
f^*(\pi,b)=\pi-\frac{1-\pi}{b},\qquad
g(f)=\pi\ln(1+fb)+(1-\pi)\ln(1-f).
\]

對 g 微分令零即得完整凱利。實際長部位先採 `max(0, f*)` 再套上限；保留帶符號原版值供診斷，不將負值解讀成支援放空。

打平機率為 `1 / (1 + b)`，YES 使用事件機率，NO 使用補數。若雙邊打平點總和不小於一，兩側不可能同時有正比例：兩正會要求事件機率同時高於 YES 打平點、低於一減 NO 打平點，與前提矛盾。

無優勢與套利不給金額。原始雙邊合約價格總和小於一時，即使費用可能抵銷表面套利，仍依規格停止另查；一般賠率也以淨打平點總和偵測套利。

`growth` 採建議所用機率，另列 `growth_under_user_p`。零機率結果的對數項視為零，有正機率的破產不輸出無窮數。日對數成長僅為 `growth / days`，不建模再投資。

## 收縮與分數凱利

\[
p_{adj}=\lambda p+(1-\lambda)q,\quad
f_\lambda=f^*(p_{adj},b),\quad f_k=kf^*(p,b).
\]

因完整凱利對機率為線性：

\[
f_\lambda=\lambda f^*(p,b)+(1-\lambda)f^*(q,b).
\]

q 恰為打平點時第二項為零，兩者等價。價差／費用使 q 低於打平點時第二項為負；任意歷史基準可能高於打平點，不能一概說更小。等價標示在上限與非負裁切前比較，避免兩者剛好都被裁為零就誤稱公式等價。

## 聯合情境

\[
\max_{w\ge0,\ \sum_i(h_i+w_i)\le1-\varepsilon}
\sum_s\pi_s\ln\left(1+\sum_i(h_i+w_i)r_{i,s}\right),
\qquad \varepsilon=10^{-6}.
\]

h 為固定既有長部位，預設零；w 為追加部位。贏的報酬為淨賠率，輸為負一，上限作用於合計。限制使情境財富保持正值；對數凹性與仿射財富讓目標為凹函數。

雙事件 YES 情境按 `00, 01, 10, 11` 排序：

\[
\pi_{11}=P(A)P(B|A),\quad\pi_{10}=P(A)-\pi_{11},\quad
\pi_{01}=P(B)-\pi_{11},\quad\pi_{00}=1-P(A)-P(B)+\pi_{11}.
\]

三事件按 `000` 到 `111`。位元代表原事件發生，選 NO 的贏輸由程式反轉。完整表、總和與邊際都要驗證；除浮點誤差外不裁掉負機率。

\[
\pi_{adj}=\lambda\pi_{user}+(1-\lambda)\pi_{bench}.
\]

基準預設各 q 的獨立乘積，可由完整基準聯合表覆蓋；混合後邊際恰好符合逐事件收縮。k 模式縮放原始聯合解；固定持有部位時拒絕 k，以免暗中賣出。

採用 [SciPy SLSQP](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-slsqp.html) 與解析梯度，`ftol=1e-13`、最多 2,000 次迭代。失敗、非有限解、預算違反或比零追加更差時報錯。單事件採解析式，僅全押邊界受現金緩衝限制。完全相關且同賠率時可有多個等價分配，應核對合計。

公式假設共同結算，不處理不同到期順序、資金解鎖、動態再平衡或保證金制度。

## 校準與樣本外評估

\[
\hat\lambda=\arg\min_{\lambda\in\{0,0.01,\ldots,1\}}
-\sum_t[y_t\ln p_{\lambda,t}+(1-y_t)\ln(1-p_{\lambda,t})],
\quad p_{\lambda,t}=\lambda p_t+(1-\lambda)q_t.
\]

候選機率裁在 `[1e-4, 1 - 1e-4]`；平均 loss 差不超過 `1e-12` 視為浮點平手取小。少於 30 筆不估計。

無時間戳用固定 seed 打亂五折；有時間按 UTC 排序，整組同時點一起分割，第一段暖身，後面五段依序測試且只用過去訓練，至少六個不同時間。概念對照 [KFold](https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.KFold.html) 與 [TimeSeriesSplit](https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.TimeSeriesSplit.html)；實作直接以 NumPy 切分，避免為一維網格增加完整機器學習依賴。

固定候選 λ 沒有其他擬合參數，以內層 held-out 列的候選平均 loss 選供未來使用的最終 λ。每個外層折只在該折訓練紀錄內再選 λ，才評外層測試。內層時間點不足時以外層訓練列選參數，仍不碰外層測試。

`scores.calibrated` 評估各折各自選參數的流程；不能把最終 λ 放回用來選它的資料評分，再稱為樣本外。基準與個人預測使用完全相同外層測試列，輸出每折 λ、樣本數與時間邊界。

\[
Brier=\frac1N\sum_t(\hat p_t-y_t)^2.
\]

bootstrap 1,000 次重抽候選評分列並重選 λ，第 5、95 百分位為 90% 區間。無時間逐列抽，有時間抽長度為評分列數平方根向上取整的連續區塊。另重抽已保存的外層分數提供條件式分數區間，不重跑完整巢狀訓練，不能宣稱包含所有選參數不確定性。

預設 seed `20261104`，可明確改值重現。區間不保證未來資訊優勢；重複、同一結果衍生或相關預測須先處理群組與資訊洩漏。

## 設計與檢查摘要

- 目的與輸出：使用者的機率、基準、賠率與本金轉成 JSON 部位、情境財富或校準報告；不取價、不下單。
- 重要相依與替代：NumPy 處理矩陣、SciPy 提供規格允許的 SLSQP。替代 cvxpy 可直接表達凹最佳化，但增加 solver 依賴，最多三事件選 SLSQP。
- 潛在錯誤：缺事件規則、報酬定義、費用、本金或曝險揭露時回待補資料，不設零費用或補數成交價；布林冒充數字、NaN／Inf、越界、維度／邊際衝突、部分時間戳屬錯誤。I/O／求解失敗回傳 JSON，時間須含時區，檔案接受 UTF-8 BOM。
- 詢問設計：共用欄位檢查器只驗證累積 JSON，最多回兩組缺項，資料齊全回零題。替代方案是只靠提示詞約束，程式較短但其他計算入口仍可能把缺費當零；因此在入口與低階報價轉換都檢查。腳本無法證明來源真偽，AI 仍須核對，不能編造資料通關。
- 效能：最多八情境，成本主要在 101 格候選與 1,000 次 bootstrap；NumPy 向量化、不開 GPU。大量歷史應只保留所需預測、基準、結果與時間欄位。
- 測試：全部 16 案例與四項固定 seed 性質測試，另驗證上限、確定性、三事件／NO／既有部位、時間分割、五個 CLI，以及只有 p/q、缺費、多輪不重問、含全費報價、單側未知、聯合缺項與示範不得繞過檢查。比例誤差 `1e-6`，使用精確公式而非表格四捨五入數值。