Merge pull request #132 from FinMind/feature/institutional-investors-buysell-wide

docs: add TaiwanStockInstitutionalInvestorsBuySellWide (個股三大法人買賣表寬表)

Author: linsamtw

docs/WhatIsNew.en.md

@@ -1,4 +1,5 @@
 #### 2026-06-13
+* Added [Institutional Investors Buy/Sell (Wide) TaiwanStockInstitutionalInvestorsBuySellWide](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockinstitutionalinvestorsbuysellwide): same data as `TaiwanStockInstitutionalInvestorsBuySell` but in wide format — one row per trading day with each institutional investor's buy/sell as its own column, no manual pivot needed. Columns cover all historical investor categories; a category is 0 in eras where it did not exist (dealer split into proprietary/hedging from 2014-12-01; foreign dealer self from 2018-01-15). Data range 2005-01-01 ~ now
 * The FinMind Python package now supports **Python 3.12** (Python 3.8–3.11 remain supported). Starting from this release, dependencies are upgraded to `pandas>=2.0` and `ta>=0.11` (`numpy` and `pydantic` unchanged).
     * **No code changes are required** to call FinMind: the public `DataLoader`, strategy, and plotting interfaces are unchanged.
     * :warning: **Upgrade note**: installing/upgrading also bumps `pandas` to 2.x and `ta` to 0.11 in your environment. If your **own surrounding code** still uses pandas 1.x APIs removed in 2.0, you will need to adjust it — common examples: `df.append()` → `pd.concat([...])`, `df.to_dict("r")` → `df.to_dict("records")`, `df.iteritems()` → `df.items()`. If you cannot adjust yet, pin an older FinMind version for now.

docs/WhatIsNew.md

@@ -1,4 +1,5 @@
 #### 2026-06-13
+* 新增 [個股三大法人買賣表（寬表）TaiwanStockInstitutionalInvestorsBuySellWide](https://finmind.github.io/tutor/TaiwanMarket/Chip/#taiwanstockinstitutionalinvestorsbuysellwide)：與 `TaiwanStockInstitutionalInvestorsBuySell` 相同資料，改為寬表（橫式），每個交易日一列、各法人別買賣攤平成獨立欄位（外資、外資自營商、投信、自營商及其自行買賣／避險），免自行轉置。欄位涵蓋所有歷史法人別分類，尚未存在的年代該欄為 0（自營商於 2014-12-01 由合併拆為自行買賣／避險、外資自營商於 2018-01-15 起提供）；資料區間 2005-01-01 ~ now
 * FinMind Python 套件新增支援 **Python 3.12**（持續支援 Python 3.8–3.11）。本版起套件相依升級為 `pandas>=2.0`、`ta>=0.11`（`numpy`、`pydantic` 維持不變）。
     * 呼叫 FinMind 的程式碼**無需修改**：`DataLoader`、策略 (Strategy)、繪圖等對外介面皆不變。
     * :warning: **升級須知**：安裝／升級會一併將環境中的 `pandas` 升至 2.x、`ta` 升至 0.11。若你**其餘自有程式碼**仍使用 pandas 1.x 在 2.0 已移除的寫法，需自行調整，常見如：`df.append()` → `pd.concat([...])`、`df.to_dict("r")` → `df.to_dict("records")`、`df.iteritems()` → `df.items()`。若暫時無法調整，可先固定安裝舊版 FinMind。

docs/llms-full.txt

@@ -303,6 +303,17 @@ Async batch query is supported by datasets that require `data_id` parameter. Not
 - Params (all stocks, Backer/Sponsor): dataset=TaiwanStockInstitutionalInvestorsBuySell, start_date=2020-04-01 (不帶 data_id，取得該日所有股票資料)
 - Columns: date, stock_id, buy, name, sell
 
+### TaiwanStockInstitutionalInvestorsBuySellWide (個股三大法人買賣表（寬表）)
+- Tier: Free (with data_id) / Backer/Sponsor (all stocks by start_date only)
+- Same data as TaiwanStockInstitutionalInvestorsBuySell but wide format: one row per (date, stock_id), each institutional investor's buy/sell as its own column
+- Data range: 2005-01-01 ~ now
+- Coverage: 上市 (TWSE), 上櫃 (TPEx), 興櫃 (Emerging) 三市場，以 stock_id 區分
+- Update: Mon-Fri 20:00
+- Params: dataset=TaiwanStockInstitutionalInvestorsBuySellWide, data_id=2330, start_date=2020-04-01, end_date=2020-04-12
+- Params (all stocks, Backer/Sponsor): dataset=TaiwanStockInstitutionalInvestorsBuySellWide, start_date=2020-04-01 (不帶 data_id，取得該日所有股票資料)
+- Columns: date, stock_id, Foreign_Investor_buy, Foreign_Investor_sell, Foreign_Dealer_Self_buy, Foreign_Dealer_Self_sell, Investment_Trust_buy, Investment_Trust_sell, Dealer_buy, Dealer_sell, Dealer_self_buy, Dealer_self_sell, Dealer_Hedging_buy, Dealer_Hedging_sell
+- Note: covers all historical investor categories; a category is 0 in eras where it did not exist. Dealer (combined) is pre-2014-12-01 (and Emerging); Dealer_self/Dealer_Hedging from 2014-12-01; Foreign_Dealer_Self from 2018-01-15. For a continuous dealer total, sum Dealer + Dealer_self + Dealer_Hedging.
+
 ### TaiwanStockTotalInstitutionalInvestors (整體三大市場法人買賣表)
 - Tier: Free
 - Data range: 2004-04-01 ~ now

docs/llms.txt

@@ -55,7 +55,7 @@ Async batch query is supported by datasets that require `data_id` parameter. Not
 
 - [Taiwan DataList](https://finmind.github.io/tutor/TaiwanMarket/DataList/): Full list of 78 Taiwan datasets
 - [Technical](https://finmind.github.io/tutor/TaiwanMarket/Technical/): TaiwanStockInfo, TaiwanStockPrice, TaiwanStockPriceAdj, TaiwanStockPriceTick, TaiwanStockPER, TaiwanStockKBar, TaiwanStockWeekPrice, TaiwanStockMonthPrice, TaiwanStockDayTrading, TaiwanStockTotalReturnIndex, TaiwanVariousIndicators5Seconds, TaiwanStockTradingDate, etc.
-- [Chip (Institutional)](https://finmind.github.io/tutor/TaiwanMarket/Chip/): TaiwanStockMarginPurchaseShortSale, TaiwanStockInstitutionalInvestorsBuySell, TaiwanStockShareholding, TaiwanStockHoldingSharesPer, TaiwanStockSecuritiesLending, TaiwanStockTradingDailyReport, TaiwanStockBlockTradingDailyReport, TaiwanStockBlockTrade, TaiwanStockLoanCollateralBalance, TaiwanstockGovernmentBankBuySell, etc.
+- [Chip (Institutional)](https://finmind.github.io/tutor/TaiwanMarket/Chip/): TaiwanStockMarginPurchaseShortSale, TaiwanStockInstitutionalInvestorsBuySell, TaiwanStockInstitutionalInvestorsBuySellWide, TaiwanStockShareholding, TaiwanStockHoldingSharesPer, TaiwanStockSecuritiesLending, TaiwanStockTradingDailyReport, TaiwanStockBlockTradingDailyReport, TaiwanStockBlockTrade, TaiwanStockLoanCollateralBalance, TaiwanstockGovernmentBankBuySell, etc.
 - [Fundamental](https://finmind.github.io/tutor/TaiwanMarket/Fundamental/): TaiwanStockCashFlowsStatement, TaiwanStockFinancialStatements, TaiwanStockBalanceSheet, TaiwanStockDividend, TaiwanStockDividendResult, TaiwanStockMonthRevenue, TaiwanStockMarketValue, etc.
 - [Derivative](https://finmind.github.io/tutor/TaiwanMarket/Derivative/): TaiwanFuturesDaily, TaiwanOptionDaily, TaiwanFuturesTick, TaiwanFuturesSpreadTick, TaiwanOptionTick, TaiwanFuturesInstitutionalInvestors, TaiwanOptionInstitutionalInvestors, TaiwanFuturesDealerTradingVolumeDaily, TaiwanOptionDealerTradingVolumeDaily, TaiwanFuturesSpreadTrading, etc.
 - [Real-Time](https://finmind.github.io/tutor/TaiwanMarket/RealTime/): taiwan_stock_tick_snapshot, TaiwanFutOptTickInfo, taiwan_futures_snapshot, taiwan_options_snapshot

docs/tutor/TaiwanMarket/Chip.en.md

@@ -1,9 +1,10 @@
-In Taiwan stock chip data, we have 20 datasets as follows:
+In Taiwan stock chip data, we have 21 datasets as follows:
 
 
 - [Individual Stock Margin Purchase / Short Sale TaiwanStockMarginPurchaseShortSale](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockmarginpurchaseshortsale)
 - [Total Market Margin Purchase / Short Sale TaiwanStockTotalMarginPurchaseShortSale](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstocktotalmarginpurchaseshortsale)
 - [Individual Stock Institutional Investors Buy/Sell TaiwanStockInstitutionalInvestorsBuySell](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockinstitutionalinvestorsbuysell)
+- [Individual Stock Institutional Investors Buy/Sell (Wide) TaiwanStockInstitutionalInvestorsBuySellWide](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockinstitutionalinvestorsbuysellwide)
 - [Total Market Institutional Investors Buy/Sell TaiwanStockTotalInstitutionalInvestors](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstocktotalinstitutionalinvestors)
 - [Foreign Investor Shareholding TaiwanStockShareholding](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockshareholding)
 - [Shareholders Holding Shares Distribution TaiwanStockHoldingSharesPer](https://finmind.github.io/en/tutor/TaiwanMarket/Chip/#taiwanstockholdingsharesper-backersponsor)
@@ -479,6 +480,112 @@ In Taiwan stock chip data, we have 20 datasets as follows:
         }
         ```
 
+----------------------------------
+#### Institutional Investors Buy/Sell (Wide) TaiwanStockInstitutionalInvestorsBuySellWide
+
+- Same source data as `TaiwanStockInstitutionalInvestorsBuySell`, but in **wide format**: one row per trading day, with each institutional investor's buy/sell flattened into its own column — no manual pivot needed.
+- Data range: 2005-01-01 ~ now
+- Coverage: listed (TWSE), OTC (TPEx) and emerging market companies, distinguished by `stock_id` (use `TaiwanStockInfo` to look up market type)
+- Data update time **Monday to Friday 20:00**, the actual update time is based on the API data.
+
+!!! note "New vs old era columns (important)"
+    The classification of the three institutional investors has changed over the years. This wide table includes **all historical classifications**; a classification is always `0` in eras where it did not yet exist:
+
+    | Column | Available era | Other eras |
+    |--------|---------------|------------|
+    | `Foreign_Investor` (foreign, excl. foreign dealer self) | all | — |
+    | `Investment_Trust` | all | — |
+    | `Dealer` (dealer, combined) | **old era** (before ~2014-12-01) and Emerging | `0` afterwards |
+    | `Dealer_self` (dealer, proprietary) | **new era** (from 2014-12-01) | `0` before |
+    | `Dealer_Hedging` (dealer, hedging) | **new era** (from 2014-12-01) | `0` before |
+    | `Foreign_Dealer_Self` (foreign dealer self) | **new era** (from 2018-01-15) | `0` before |
+
+    - From **2014-12-01**, the combined `Dealer` was split into `Dealer_self` (proprietary) and `Dealer_Hedging` (hedging).
+    - From **2018-01-15**, `Foreign_Dealer_Self` was split out from foreign investors.
+    - For a continuous "dealer total" across eras, sum `Dealer + Dealer_self + Dealer_Hedging` (only one group is non-zero in any era, so there is no double counting).
+
+!!! example
+    === "Package"
+        ```python
+        from FinMind.data import DataLoader
+
+        api = DataLoader()
+        # api.login_by_token(api_token='token')
+        df = api.taiwan_stock_institutional_investors_wide(
+            stock_id="2330",
+            start_date='2020-04-01',
+            end_date='2020-04-12',
+        )
+        ```
+    === "Python-request"
+        ```python
+        import requests
+        import pandas as pd
+        url = "https://api.finmindtrade.com/api/v4/data"
+        token = "" # login to get the token
+        headers = {"Authorization": f"Bearer {token}"}
+        parameter = {
+            "dataset": "TaiwanStockInstitutionalInvestorsBuySellWide",
+            "data_id": "2330",
+            "start_date": "2020-04-01",
+            "end_date": "2020-04-12",
+        }
+        data = requests.get(url, headers=headers, params=parameter)
+        data = data.json()
+        data = pd.DataFrame(data['data'])
+        print(data.head())
+
+        ```
+    === "R"
+        ```R
+        library(httr)
+        library(data.table)
+        library(dplyr)
+        url = 'https://api.finmindtrade.com/api/v4/data'
+        token = "" # login to get the token
+        response = httr::GET(
+            url = url,
+            query = list(
+                dataset="TaiwanStockInstitutionalInvestorsBuySellWide",
+                data_id= "2330",
+                start_date= "2020-04-01",
+                end_date= "2020-04-12"
+            ),
+            add_headers(Authorization = paste("Bearer", token))
+        )
+        data = content(response)
+        df = data$data %>%
+        do.call('rbind',.) %>%
+        data.table
+        head(df)
+
+        ```
+
+!!! output
+    === "DataFrame"
+        |    | date       |   stock_id |   Foreign_Investor_buy |   Foreign_Investor_sell |   Foreign_Dealer_Self_buy |   Foreign_Dealer_Self_sell |   Investment_Trust_buy |   Investment_Trust_sell |   Dealer_buy |   Dealer_sell |   Dealer_self_buy |   Dealer_self_sell |   Dealer_Hedging_buy |   Dealer_Hedging_sell |
+        |---:|:-----------|-----------:|-----------------------:|------------------------:|--------------------------:|---------------------------:|-----------------------:|------------------------:|-------------:|--------------:|------------------:|-------------------:|---------------------:|----------------------:|
+        |  0 | 2020-04-01 |       2330 |               31304729 |                29057663 |                         0 |                          0 |                 900000 |                  239000 |            0 |             0 |             79000 |             807000 |               189000 |                493500 |
+    === "Schema"
+        ```
+        {
+            date: str, # date
+            stock_id: str, # stock id
+            Foreign_Investor_buy: int64, # foreign investor buy
+            Foreign_Investor_sell: int64, # foreign investor sell
+            Foreign_Dealer_Self_buy: int64, # foreign dealer self buy
+            Foreign_Dealer_Self_sell: int64, # foreign dealer self sell
+            Investment_Trust_buy: int64, # investment trust buy
+            Investment_Trust_sell: int64, # investment trust sell
+            Dealer_buy: int64, # dealer buy (combined, old era)
+            Dealer_sell: int64, # dealer sell (combined, old era)
+            Dealer_self_buy: int64, # dealer proprietary buy
+            Dealer_self_sell: int64, # dealer proprietary sell
+            Dealer_Hedging_buy: int64, # dealer hedging buy
+            Dealer_Hedging_sell: int64 # dealer hedging sell
+        }
+        ```
+
 ----------------------------------
 #### Taiwan Total Market Institutional Investors Buy/Sell TaiwanStockTotalInstitutionalInvestors