Skip to main content
Tool Group · ICIR 因子研究

ICIR 因子研究 ICIR Factor Research

ICIR low-level tools 分別負責 factor discovery、pool discovery、statistics、constituents、factor history、level returns 與 historical IC。Agent 必須依問題選擇正確資料類型，不能用 statistics 代替 time series，或用 pool constituents 當成候選股排名。 ICIR Factor Research tools 支援 factor 探索、pool 確認、統計檢查、factor exposure、分層報酬與 historical IC 分析。七個工具皆為 GET、data 為 records 容器。

Permission · standardBilling · x1Method · GETContainer · recordsOutput · data / raw

驗證狀態：artifact-confirmed。範例與 assertions 由 validation/tool_usage_cases.json 管理。

Factor discovery​

ToolAPI Path說明Best for
list_icir_factors/API/module7_factor_list查詢市場可用的 ICIR factor 清單。因子探索、factor name lookup
list_icir_pools/API/module7_pool_list查詢 ICIR 支援的股票池（mc300 / mc200 / mc100 / mc50）。股票池選擇、研究 universe 確認
get_icir_statistics/API/module7_stat查詢 factor 或 pool 的最新 ICIR 統計：IC、IR、return-difference 與 long/short evidence。因子篩選、ICIR evidence
list_icir_pool_stocks/API/module7_pool_stock查詢指定 pool 在某一天的成分股。Pool constituents、選股 universe
get_icir_factor_history/API/module7_factor_history查詢一個或多個股票代碼的歷史 factor values。Factor exposure、候選股排名
get_icir_returns/API/module7_return查詢 factor 在指定 pool 的 level1–level10 historical return series。因子報酬、分層表現
get_icir_history_ic/API/module7_ic查詢 factor 在指定 pool 的 historical IC series。因子穩定性、IC trend

參數 Parameters​

ICIR 工具的參數高度共用，下表為各參數含義；每個工具的必填鍵列於其後。

參數型別預設說明
marketstringtw市場：tw 或 cn。
factorstring*（factor list）factor 名稱、逗號分隔多個，或 * 取全部。
factor_namestring視工具單一 factor 名稱，例如 xt_sum_4_wma(Beta)。
pool_namestring視工具股票池名稱，例如 mc300、mc200。
code_liststring2330 TT Equity（factor history）逗號分隔商品代碼。
datestring (YYYY-MM-DD)2025-07-01（pool stock）成分股計算日；Module 7 每日重算成員，建議用分析迄日。
start_date / end_datestring | null—選用的時間區間。
query / limitstring / integer"" / 100list 類工具的篩選與上限（pool stock 上限 2000，其餘 500）。
output_modestringdatadata / raw。
工具必填
list_icir_factors / list_icir_pools（無；market 有預設）
get_icir_statisticsfactor_name 或 pool_name 至少一個
list_icir_pool_stockspool_name（有預設 mc200）
get_icir_factor_historymarket、code_list、factor_name
get_icir_returns / get_icir_history_icmarket、factor_name、pool_name
研究流程順序

典型順序：list_icir_factors / list_icir_pools 解析名稱 → get_icir_statistics 篩選候選 factor → list_icir_pool_stocks 取 universe → get_icir_factor_history 排名 → 以 get_icir_returns、get_icir_history_ic 補強證據。若要直接取得候選股強弱排序，改用 ICIR 因子候選股排名。

list_icir_factors​

  • 適用：查詢市場可用的 canonical factor names。
  • 必要資訊：market；可使用 factor、query、limit 篩選。
請列出台股市場可用、名稱包含 ar 的 ICIR 因子，最多 20 筆，讓我確認正式因子名稱。

查不到時應請使用者調整 query，不可自行杜撰 factor name。

Pool discovery​

list_icir_pools​

  • 適用：查詢 mc300、mc200、mc100、mc50 等可用股票池。
  • 必要資訊：market；可提供 query 與 limit。
請列出台股 ICIR 可用、名稱包含 mc 的股票池，最多 20 筆，並解釋各池代表什麼。

Pool 是研究 universe，不是因子候選股排名結果。

最新 ICIR statistics​

get_icir_statistics​

  • 適用：取得 factor 或 pool 的 IC、IR、return difference 與 long/short evidence。
  • 必要資訊：market，並提供 canonical factor_name 或 pool_name 其中一項。需要 factor × pool 研究時，先以 pool 取得可用統計，再用回傳的 factor 名稱查後續 history、return 與 IC。
請查詢台股 mc200 股票池的最新 ICIR 統計，包含各因子的 IC、IR、return difference 與資料日期。

回答應標示實際統計日期、factor、pool 與缺值，不能把歷史 statistics 描述為未來保證。

Pool constituents​

list_icir_pool_stocks​

  • 適用：查詢特定 market、pool 與 date 的 constituents。
  • 必要資訊：market、pool_name、date；可用 query、limit 篩選。
請列出台股 mc200 股票池在 2025-07-01 的成分股，最多 50 筆，並標示資料日期。

回答必須區分 requested date 與 returned data date；成分股本身不是因子排名結果。

Stock-level factor history​

get_icir_factor_history​

  • 適用：查詢一個或多個股票的 factor values time series。
  • 必要資訊：market、逗號分隔的 code_list、canonical factor_name；日期範圍選填。
請查詢台股 2330 TT Equity 的 ar_3y 因子在 2025-06-01 到 2025-07-01 的歷史值與資料日期。

回答應保留 code、factor、日期、factor value 與 null 狀態。

Level returns​

get_icir_returns​

  • 適用：查詢 factor 在指定 pool 的 level1 到 level10 historical return series。
  • 必要資訊：market、factor_name、pool_name；日期範圍選填。
請查詢台股 ar_3y 因子在 mc200 股票池、2025-06-01 到 2025-07-01 的 level1 到 level10 歷史報酬與資料日期。

回答應說明 level 定義、實際日期範圍與 missing levels；不可把 historical return 當作保證報酬。

Historical IC​

get_icir_history_ic​

  • 適用：檢查 factor 在指定 pool 的 historical IC series 與穩定性。
  • 必要資訊：market、factor_name、pool_name；日期範圍選填。
請查詢台股 ar_3y 因子在 mc200 股票池、2025-06-01 到 2025-07-01 的 historical IC 序列與資料日期。

共用失敗判讀​

症狀處理方式
Factor 或 pool 查不到先使用 discovery tool 解析 canonical name。
Requested date 沒有資料顯示 requested / returned dates，不可靜默改用其他日期。
Records 為空或 value 為 null回報 unavailable 與 warnings，不產生排名或績效結論。
混淆 statistics、returns 與 IC回到使用者問題，選擇對應資料 contract。

回傳格式 Response​

共用 envelope 見 工具總覽。所有 ICIR 工具的 data 為 records 容器：data.records（factor / pool / 統計 / 報酬 / IC 的逐列資料）、data.columns、data.total_count、data.available_count。

待 live 校正

各工具 records 的實際欄位名（IC、IR、return-difference、level1–level10 等）以 /API/module7_* 回傳為準，將以 dev 端實打結果補上。

AI 回應示意​

使用者拿到的是 AI 依統計與序列整理後的研究摘要，而非原始 JSON。示意（內容依 factor / pool 與當日資料而定）：

ICIR 因子研究 · mc300（近 60 天）｜資料日：依回傳 data_date

  • 篩選出的候選 factor 與其 IC / IR / return-difference 表現
  • 分層報酬（level1–level10）與 historical IC 的穩定度觀察
  • 適用的 pool、區間與資料限制
  • ⚠️ 歷史統計研究證據，不代表未來報酬保證

每段回應都會標示 factor、pool、date range 與 資料限制 / 非投資建議聲明。