quant-factor-naming

name	quant-factor-naming
description	量化金融因子标准化命名与元数据管理skill，自动化批量重命名因子函数、添加结构化docstring、更新配置列表、将元数据入库。遵循三层架构"一级按信号来源分，二级按经济含义分，三级按计算口径分"，坚持"短、稳、可解析、可扩展、尽量唯一"分层命名原则。触发场景：需要整理量化因子库、给大量因子重命名加元数据、批量更新因子配置、因子元数据入库、因子库标准化管理。

量化因子标准化命名与元数据管理 Skill

概述

这个skill用于量化投资研究中，对因子库进行标准化整理：

• 按照统一三层架构分层命名规则批量重命名因子函数
  • 一级：信号来源大类 - 基础面/价量/资金流/高频/事件/组合/风格
  • 二级：经济含义小类 - 按投资逻辑细分
  • 三级：计算口径标签 - 原始/差分/排序/标准化等
• 为每个因子添加结构化docstring元数据
• 自动更新all_alpha列表和settings.py中的配置
• 将所有元数据批量写入PostgreSQL数据库表 mate_factor_info

触发条件

当用户提到以下内容时必须触发本skill：

• "因子重命名"
• "批量重命名因子"
• "因子标准化命名"
• "因子元数据入库"
• "整理alpha101因子"
• "简化因子配置流程"
• "给因子添加docstring"
• "因子命名规范"
• "因子库标准化"
• "整理量化因子库"

命名原则

遵循 "短、稳、可解析、可扩展、尽量唯一" 原则：

三层架构命名体系

推荐命名结构：

{source}_{category}_{family}_{calc}_{freq}_{window}_{neutral}_v{version}

字段说明：

层级	字段	说明	示例
来源	source	因子来源（数据集/论文）	alpha101, alpha158, alpha191, wind, tushare, internal, calendar
一级	category	信号来源大类（一级分类）	fund基本面, pv价量, flow资金流, hf高频, event事件, comp复合, style风格
二级	family	经济含义小类（二级分类，缩写）	mom动量, vol波动率, val价值, size规模
三级	calc	计算口径/形态（三级分类）	raw原始, diff差分, rank排序, zscore标准化
频率	freq	数据频率	1m, 5m, 15m, 1d
窗口	window	回看窗口	5d, 20d, 60d, 250d
中性化	neutral	中性化处理	raw未中性化, ind行业中性化, size市值中性化, full全中性化
版本	version	版本号	v1, v2, v3

简化版（当一级分类已明确时）：

{source}_{family}_{calc}_{freq}_{window}_{neutral}_v{version}

---

完整分类体系

第一层：信号来源大类（一级分类）

一级分类	中文名称	缩写	说明
fundamental	基础面因子	fund	来源于财务报表、公告、预期、股东结构、治理信息
price_volume	价格成交因子	pv	来源于日频/低频 OHLCV、amount、vwap、换手率、涨跌幅、波动、成交额、复权因子等，常见派生字段包括收益率、K线形态、量价关系、均线偏离、波动率和流动性指标
flow	资金流向因子	flow	来源于北向资金、主力资金、融资融券、机构持仓变化等
microstructure	高频微观结构	hf	来源于盘口、逐笔、委托、撤单、成交方向、价差、冲击成本等
event	事件与预期因子	event	来源于业绩预告、公告、研报、新闻、情绪、政策等
composite	复合与组合因子	comp	由多个单因子组合、打分、归一化、中性化后得到
style	风格与风险因子	style	用于描述系统性暴露，如规模、价值、成长、波动等

---

第二层：经济含义小类（二级分类）

1. 基础面因子 (fund)

小类名称	英语名称	缩写
盈利能力	Profitability	prof
成长能力	Growth	growth
营运效率	Operating Efficiency	op_eff
盈余质量	Earnings Quality	earn_q
安全性/偿债能力	Solvency/Safety	safety
公司治理	Governance	gov
估值	Valuation	val
分析师预期	Analyst Expectations	analyst
股东结构	Ownership Structure	owner
规模	Size	size
现金流质量	Cash Flow Quality	cf_q
分红能力	Dividend	div
财务杠杆	Leverage	lev
资本结构	Capital Structure	cap_struct
资产质量	Asset Quality	asset_q
商业模式	Business Model	business
复合基本面因子	Composite Fundamental	comp_fund

2. 价格成交因子 (pv)

小类名称	英语名称	缩写
动量	Momentum	mom
反转	Reversal	rev
趋势	Trend	trend
波动率	Volatility	vol
流动性	Liquidity	liq
价量相关性	Price-Volume Correlation	corr
筹码分布	Chip Distribution	chip
资金流向	Capital Flow	cap_flow
北向资金流	Northbound Flow	north_flow
融资融券	Margin Financing	margin
价量复合	Price-Volume Composite	comp_pv
换手率	Turnover	turnover
振幅	Amplitude	amp
跳空	Gap	gap
成交额	Trading Value	value
相对强弱	Relative Strength	rsi
价格压力	Price Pressure	pressure
盘整/突破	Consolidation/Breakout	breakout
日内反转	Intraday Reversal	intra_rev

3. 资金流向因子 (flow)

小类名称	英语名称	缩写
北向资金	Northbound Flow	north
南向资金	Southbound Flow	south
主力资金	Main Capital Flow	main
龙虎榜	Top Traders	longhu
融资融券	Margin Trading	margin
两融余额	Margin Balance	margin_bal
机构持仓	Institutional Holding	inst_hold
持仓变化	Holding Change	hold_chg
陆股通持股	Stock Connect Holding	connect
资金流净额	Net Flow	net
换手率	Turnover	turnover
大小单对比	Large vs Small Order	l_s_diff

4. 高频微观结构因子 (hf)

小类名称	英语名称	缩写
高频动量反转	High-Frequency Momentum/Reversal	hf_mom
高频波动率	High-Frequency Volatility	hf_vol
高阶统计特征	Higher-Order Features	hf_higher
高频流动性	High-Frequency Liquidity	hf_liq
量价相关性	Volume-Price Relation	hf_corr
微观筹码分布	Microstructure Positioning	hf_chip
拥挤度	Crowding	crowd
订单流	Order Flow	order_flow
高频价量复合	HF Composite Price-Volume	hf_comp
买卖盘不平衡	Order Imbalance	imbalance
买卖价差	Bid-Ask Spread	spread
市场深度	Market Depth	depth
撤单率	Cancel Rate	cancel
成交强度	Trade Intensity	intensity
冲击成本	Market Impact	impact
微价格	Microprice	microprice
跳跃风险	Jump Risk	jump
信息流	Information Flow	info_flow
波动聚集	Volatility Clustering	vol_cluster

5. 事件与预期因子 (event)

小类名称	英语名称	缩写
业绩预告	Earnings Guidance	guidance
业绩超预期	Earnings Surprise	surprise
公告冲击	Announcement Effect	announce
研报情绪	Analyst Sentiment	ana_sent
新闻情绪	News Sentiment	news_sent
政策事件	Policy Event	policy
主题热度	Theme Popularity	theme
风险提示	Risk Warning	risk_warn
解禁事件	Lock-up Expiration	lockup
增减持	Insider Trading	insider
回购	Share Repurchase	repurchase

6. 风格与风险因子 (style)

小类名称	英语名称	缩写
价值	Value	val
成长	Growth	growth
质量	Quality	quality
规模	Size	size
动量	Momentum	mom
低波动	Low Volatility	low_vol
低流动性	Illiquidity	illiq
行业暴露	Industry Exposure	ind_exp
市值暴露	Market Cap Exposure	mc_exp
Beta暴露	Beta Exposure	beta
盈利能力	Profitability	prof
投资风格	Investment Style	investment
杠杆	Leverage	lev

说明：质量因子 (quality) 包含以下子维度：

• 盈利能力 (profitability)
• 成长能力 (growth)
• 营运效率 (operating efficiency)
• 盈余质量 (earnings quality)
• 安全性 (safety/solvency)
• 公司治理 (governance)

7. 复合与组合因子 (comp)

小类名称	英语名称	缩写
多因子打分	Multi-Factor Score	score
风格中性组合	Style-Neutral Composite	neu_style
行业中性组合	Industry-Neutral Composite	neu_ind
残差因子	Residual Factor	resid
机器学习合成	ML Composite	ml
因子正交化	Orthogonal Factor	ortho

---

第三层：计算口径/形态标签

很多因子名称冲突，不是因为经济含义冲突，而是因为计算口径不同。所以每个因子必须加一个计算形态维度：

计算形态	说明	缩写
原始值	原始计算结果	raw
差分	一阶差分	diff
环比	环比增长率	pct
同比	同比增长率	yoy
对数	对数变换	log
百分比	百分比	pct
截面排序	截面排序	rank
标准化	Z-score标准化	zscore
中性化	中性化处理	neutral
滚动窗口	滚动窗口计算	rolling
滞后	滞后一期/多期	lag
移动平均	简单移动平均	sma
指数平均	指数移动平均	ema
加权平均	加权平均	wma
相关性	相关系数	corr
协方差	协方差	cov
残差	回归残差	resid
标准差	标准差	std
累积和	累积和	cumsum
最大值	时间序列最大值	max
最小值	时间序列最小值	min
组合复合	多因子复合	comp

---

缩写对照表（简洁版）

二级分类（family）缩写速查：

全称	缩写	大类
momentum	mom	pv/style
reversal	rev	pv
volatility	vol	pv/hf/style
value	val	fund/style
size	size	fund/style
liquidity	liq	pv/hf
quality	quality	style
growth	growth	fund/style
leverage	lev	fund/style
profitability	prof	fund/style
correlation	corr	pv/hf
chip	chip	pv/hf
alpha101	alpha101	source

计算口径（calc）缩写速查：

全称	缩写
raw	raw
difference / diff	diff
ratio / pct	pct
rank	rank
zscore	zscore
exponential moving average	ema
simple moving average	sma
correlation	corr
covariance	cov
residual	resid
stddev	std

中性化（neutral）缩写：

类型	缩写
未中性化	raw
行业中性化	ind
市值中性化	size
beta中性化	beta
全中性化	full

---

命名示例

原始描述	标准化命名
alpha101中，20日波动率，条件选股，日频，未中性化	alpha101_pv_vol_raw_1d_20d_raw_v1
alpha101中，量价相关性，排序，日频，6日窗口	alpha101_pv_corr_rank_1d_6d_raw_v1
财务报表，净资产收益率，盈利能力，原始值，季频	fund_prof_raw_qfq_raw_v1
北向资金净流入，截面排序，日频	flow_net_rank_1d_raw_v1
买卖价差，高频，原始值，1分钟	hf_spread_raw_1m_raw_v1
业绩超预期，事件，日频	event_surprise_raw_1d_raw_v1
Beta暴露，风格因子，日频	style_beta_raw_1d_250d_raw_v1
行业中性化后的价值因子，复合	comp_val_neutral_1d_raw_ind_v1

---

工作流程

输入

1. 因子文件路径：例如 seagull/technical/alpha101.py
2. 配置列表名称：例如 ALPHA101_COLS 在 seagull/settings.py 中
3. 因子来源：例如 alpha101（用于source字段和元数据）
4. 默认频率：例如 1d（日频）

步骤

1. 读取因子文件，解析所有因子函数
2. 对于每个因子：
   • 根据公式内容，分析其一级信号来源、二级经济含义、三级计算口径
   • 按照三层架构命名规则生成新的函数名
   • 添加结构化docstring包含：一级分类、二级分类、计算方式、计算公式（大白话）、收益来源、因子来源
   • 保留原有计算逻辑不变
3. 更新文件末尾的 all_alpha 列表，用新函数名
4. 更新 settings.py 中的对应配置列表
5. 生成DDL：ddl/mete_factor_info.sql 创建表结构（如果不存在）
6. 生成插入语句，通过 seagull/data/meta/factor_info.py 批量插入到数据库 mate_factor_info

输出

• 重命名后的因子文件（所有因子函数名规范化，带docstring）
• 更新后的 settings.py 配置列表
• ddl/mete_factor_info.sql DDL文件
• seagull/data/meta/factor_info.py 数据入库脚本
• 数据库中包含所有因子的元数据（含一级/二级/三级分类信息）

使用示例

用户输入：

参考doc/03_因子分析与挖掘/02_因子挖掘/因子重命名.md，我希望批量重命名seagull/technical/alpha101.py中的因子，更新settings.py中的ALPHA101_COLS，并将元数据写入数据库mate_factor_info

skill执行：

1. 读取 alpha101.py
2. 逐个分析每个因子，确定一级分类→二级分类→计算口径，重命名 + 添加docstring
3. 更新文件末尾 all_alpha
4. 更新 settings.py 中 ALPHA101_COLS
5. 创建/更新 ddl/mete_factor_info.sql
6. 生成 data/meta/factor_info.py 插入脚本

Docstring格式要求

每个因子函数必须包含以下结构化docstring：

def alpha101_pv_vol_raw_1d_20d_raw_v1(d: AllData):
    """
    一级分类: 价格成交因子
    二级分类: 波动率
    计算方式: 条件选择
    计算公式: 如果收益<0，取20日收益波动率，否则取收盘价，然后平方，取5日时间最大值排序
    大白话解释: 下跌日的波动率越高，给予越低评分
    收益来源: 捕捉下跌波动异象，认为高波动下跌预示继续下跌
    因子来源: alpha101
    """

约束与要求

• 保留原有计算逻辑：只修改函数名和添加docstring，不改变计算代码
• 向后兼容：如果用户不想立刻删除旧名称，可以保留旧名称作为别名
• 交互式确认：对于分析不确定的因子分类，询问用户确认
• 事务性：修改前自动备份原文件，方便回滚

备份机制

修改前自动备份：

cp {file_path} {file_path}.bak.{timestamp}

用户可以随时恢复备份。

数据库表结构

表名 mate_factor_info 扩展字段（增加一级二级分类）：

字段	类型	说明
id	SERIAL PRIMARY KEY	自增ID
factor_code	VARCHAR(100) NOT NULL	因子标准化编码（新名称）
original_name	VARCHAR(100)	原始函数名
source	VARCHAR(50)	因子来源
category_l1	VARCHAR(50)	一级分类（信号来源大类）
category_l1_code	VARCHAR(20)	一级分类编码
category_l2	VARCHAR(50)	二级分类（经济含义小类）
category_l2_code	VARCHAR(20)	二级分类编码
calc	VARCHAR(50)	计算口径描述
calc_code	VARCHAR(20)	计算口径编码
freq	VARCHAR(10)	数据频率
window_days	INT	窗口天数
neutral	VARCHAR(20)	中性化处理
version	INT	版本号
formula_plain	TEXT	大白话计算公式
return_source	TEXT	收益来源解释
formula_code	TEXT	公式代码
file_path	VARCHAR(200)	所在文件
enabled	BOOLEAN DEFAULT TRUE	是否启用
insert_timestamp	TIMESTAMP DEFAULT CURRENT_TIMESTAMP	插入时间
update_timestamp	TIMESTAMP DEFAULT CURRENT_TIMESTAMP	更新时间