https://github.com/voidful/tw-institutional-stocker

https://github.com/voidful/tw-institutional-stocker

Last synced: 3 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/voidful/tw-institutional-stocker
• Owner: voidful
• Created: 2025-11-11T13:41:44.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2026-03-30T03:45:17.000Z (3 months ago)
• Last Synced: 2026-03-30T06:04:53.668Z (3 months ago)
• Language: Python
• Homepage: https://eric-lam.com/tw-institutional-stocker/
• Size: 154 MB
• Stars: 206
• Watchers: 3
• Forks: 81
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# tw_institutional_stocker

台股三大法人持股比重追蹤（上市 + 上櫃），自動每日更新並發佈到 GitHub Pages。

## 新版重點

- 支援多個變化視窗：`WINDOWS = [5, 20, 60, 120]`

  - 產出：

    - `docs/data/top_three_inst_change_5_up.json` / `..._down.json`

    - `docs/data/top_three_inst_change_20_up.json` / ...

    - `docs/data/top_three_inst_change_60_up.json` / ...

    - `docs/data/top_three_inst_change_120_up.json` / ...

  - 前端可透過下拉選單切換視窗。

- 三大法人模型升級：

  - 外資：仍採官方 `foreign_ratio`。

  - 投信 / 自營商：支援「基準點校正」：

    - 準備 `data/inst_baseline.csv`，格式：

      ```csv

      date,code,trust_shares_base,dealer_shares_base

      2025-01-31,2330,100000000,20000000

      2025-01-31,0050,50000000,0

      ```

    - 模型在每檔股票內以日期排序，若遇到 baseline：

      - 設 `trust_shares_est = baseline_trust + sum(trust_net since baseline)`

      - 設 `dealer_shares_est = baseline_dealer + sum(dealer_net since baseline)`

    - 若完全沒有 baseline，則退化為純 cumsum 模型：

      - `trust_shares_est = cumsum(trust_net)`

      - `dealer_shares_est = cumsum(dealer_net)`

## 結構概覽

- `update_all.py`

  - 從 TWSE / TPEX 抓取：

    - 三大法人每日買賣超（上市 T86 + 上櫃 3itrade_hedge_result）

    - 外資持股統計（上市 MI_QFIIS + 上櫃 QFII）

  - 以 `inst_baseline.csv` 為基準點，搭配日淨買超推估投信 / 自營商持股。

  - 計算三大法人持股比重與多個視窗的變化值。

  - 匯出：

    - `docs/data/timeseries/{code}.json`

    - `docs/data/top_three_inst_change_{w}_up.json` / `..._down.json`

- `docs/`

  - 靜態前端（index.html + script.js + style.css）

  - 提供：

    - 隨輸入代碼動態載入該股三法人持股時序。

    - 以 5 / 20 / 60 / 120 日變化排序的排名表，可點擊列載入該股圖。

    - 市場過濾（全部 / TWSE / TPEX）與 log scale 切換。

- `.github/workflows/update.yml`

  - 每天 00:10 UTC 由 GitHub Actions 執行 `python update_all.py`

  - 若 `data/` 或 `docs/data/` 有變動，會自動 commit + push 回 main 分支。

## 本地開發

```bash

pip install -r requirements.txt

python update_all.py

```

執行完後，`docs/data/` 底下會長出 json 檔，直接用 `python -m http.server` 或 VSCode Live Server 打開 `docs/index.html` 即可預覽。

若要啟用「基準點校正」：

1. 從投信 / 自營商的財報或官方持股統計整理出某幾個日期的「實際持股股數」。

2. 填入 `data/inst_baseline.csv`。

3. 重新跑 `python update_all.py`。之後 GitHub Actions 自動更新也會沿用這些 baseline。