Metadata-Version: 2.4
Name: jh-factors
Version: 0.1.9
Summary: jiuhuang factors calculation package
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: jh-fin-data>=0.1.4
Requires-Dist: joblib>=1.4.0
Requires-Dist: polars>=1.0.0
Requires-Dist: scipy>=1.15.3
Dynamic: license-file

# jh_factors
A股市场因子收益与个股因子暴露计算框架。

## 功能特性

- **多因子模型支持**: CAPM、FF3、FF5、CARHART、NOVY_MARX、HOU_XUE_ZHANG、DHS、CH3、SY4、REVERSAL、LOW_VOL
- **因子收益计算**: 独立排序，支持多种加权方案
- **个股暴露计算**: 通过OLS回归估计滚动和混合beta
- **因子验证**: 截距检验、Fama-MacBeth两步法回归
- **数据校验**: 因子计算前进行数据预处理和质量校验
- **并行计算**: 使用joblib实现并发计算

## 安装

```bash
uv add jh-factors
```

## 快速开始

### 计算因子收益

```python
from jh_factors import calculate_factor_returns, FactorType

# 为A股所有股票计算Fama-French三因子收益
ff3_monthly = calculate_factor_returns(
    factor_type=FactorType.FF3,
    start_date='2020-01-01',
    end_date='2024-12-31',
    period='M',
)
print(ff3_monthly.head())
```

### 计算个股因子暴露

```python
from jh_factors import calculate_exposures, FactorType

stock_returns = your_stock_returns_data  # DataFrame，含 [symbol, date, return] 列

# 计算滚动beta
exposures = calculate_exposures(
    stock_returns=stock_returns,
    factor_returns=ff3_monthly,
    period='M',
    lookback=36  # 36个月滚动窗口
)
```

### 验证因子有效性

```python
from jh_factors import validate_factor, calculate_exposures

stock_returns = your_stock_returns_data  # DataFrame，含 [symbol, date, return] 列

exposures = calculate_exposures(
    stock_returns=stock_returns,
    factor_returns=ff3_monthly,
)

# 截距检验：检验因子收益是否显著不为零
intercept_result = validate_factor(
    factor_returns=factor_returns,
    stock_returns=stock_returns,
    method='intercept',
    alpha=0.05
)

# Fama-MacBeth回归：因子风险溢价的横截面检验
fama_result = validate_factor(
    factor_returns=factor_returns,
    stock_returns=stock_returns,
    factor_exposures=exposures,
    method='fama_macbeth',
    alpha=0.05
)
```

## 支持的因子模型

| 模型              | 因子                              | 说明                              |
| ----------------- | --------------------------------- | -------------------------------- |
| **CAPM**          | MKT                               | CAPM单因子（市场超额收益）        |
| **FF3**           | MKT, SMB, HML                     | Fama-French三因子模型             |
| **FF5**           | MKT, SMB, HML, RMW, CMA           | Fama-French五因子模型             |
| **CARHART**       | MKT, SMB, HML, UMD                | Carhart四因子（加入动量）         |
| **NOVY_MARX**     | MKT, SMB, HML_ADJ, UMD, GP/A      | Novy-Marx四因子                   |
| **HOU_XUE_ZHANG** | MKT, ME, IA, ROE                  | Hou-Xue-Zhang q-factor模型        |
| **DHS**           | MKT, PEAD, FIN                    | Daniel-Hirshleifer-Sun行为三因子  |
| **CH3**           | MKT, SMB, VMG                     | 中国三因子模型（剔除壳价值干扰）  |
| **SY4**           | MKT, SMB, MGMT, PERF              | Stambaugh-Yuan四因子（误定价）    |
| **REVERSAL**      | MKT, SMB, REV                     | 短期反转模型                       |
| **LOW_VOL**       | MKT, SMB, IVOL                    | 低波动模型（波动率悖论）          |

## 因子计算特别说明

### DHS模型 - 预期盈余的替代计算

**学术定义**: SUE (标准化未预期盈余) = (实际EPS - **预期EPS**) / std(实际EPS - 预期EPS)

**当前实现**: 由于无分析师一致预期数据，使用**净利润同比变化率**作为代理变量。

```
SUE ≈ (EPS_t - EPS_{t-4}) / std(EPS_t - EPS_{t-4})
```

即：当期净利润与去年同期净利润之差，除以其标准差。

**理论基础**: 若假设利润服从随机游走，则 $E(eps_t) = eps_{t-4}$，此时同比变化确实等于SUE。

### NOVY_MARX模型 - 毛利因子与HML_ADJ行业调整

**学术定义**: GP/A = 毛利 / 总资产，毛利 = 营业收入 - 营业成本

**当前实现**: 使用 `(revenue - cogs) / ta` 计算，其中：
- `revenue`: 营业总收入
- `cogs`: 营业总支出（营业成本）
- `ta`: 总资产（从资产负债表获取）

**HML_ADJ行业调整**: hml_adj因子在分组时使用行业调整后的BM值：
- `bm_adj = bm - median(bm within same industry)`
- 即每个股票的BM减去其所在行业的BM中位数，再进行高低分组


### REVERSAL模型 - 反转因子方向

**学术定义**: 短期反转因子 = 低收益率组合 - 高收益率组合（即"跌的多的未来涨的多"）

**实现**: REV因子计算为 `low - high`，做多过去20日跌幅最大的组，做空涨幅最大的组。

### LOW_VOL模型 - 特质波动率

**学术定义**: 通过CAPM或FF3模型对日收益率做残差回归，取残差的标准差

**当前实现**: 使用日收益率的滚动20日标准差作为特质波动率的简化代理。

### CH3模型 - 价值因子VMG

**学术定义**: VMG (Value Minus Growth) 在分组前先剔除市场市值最小的30%股票

**当前实现**: 在分组计算时暂未实现剔除逻辑，VMG与传统HML计算方式一致。

### SY4模型 - 管理因子与绩效因子

**学术定义**:
- MGMT (管理因子): 综合资产增长率、应计项、净股票发行等指标
- PERF (绩效因子): 综合ROE、资产周转率变动、财务困境指标

**当前实现**:
- MGMT: 使用资产增长率 (asset_growth) 作为代理
- PERF: 使用ROE作为代理

## 数据原则

### 因子与数据映射

| 因子         | 数据来源                    | 计算逻辑                                    |
| ------------ | -------------------------- | ------------------------------------------ |
| MKT          | 上证指数收益率 - SHIBOR    | 市场超额收益率                              |
| SMB          | 总市值 (total_mv)          | 小市值组合 - 大市值组合                     |
| HML          | PB的倒数 (1/PB)            | 高BM组合 - 低BM组合                        |
| HML_ADJ      | PB的倒数 (1/PB)、行业分类     | BM行业调整：bm_adj = bm - industry_median(bm)，高bm_adj组合 - 低bm_adj组合 |
| RMW          | 营业利润/所有者权益 (OP)   | 高盈利组合 - 低盈利组合                     |
| CMA          | 资产增长率                 | 低投资组合 - 高投资组合（保守-激进）         |
| UMD          | 过去12月收益率（不含近1月）| 过去12月收益率 - 过去1月收益率               |
| GP/A         | 毛利/总资产                | (revenue - cogs) / ta，revenue=营业总收入, cogs=营业成本 |
| ME           | 总市值 (total_mv)          | 同SMB，但分组逻辑更细致                     |
| IA           | 资产增长率                 | 同CMA                                      |
| ROE          | 净利润/所有者权益 (NI/BE)  | 季度ROE作为盈利因子                         |
| PEAD         | 利润表 (LRB)               | 净利润同比变化率标准化                      |
| FIN          | 资产负债表 (ZCFZ)          | 股本变化率或总资产变化率                    |
| VMG          | PB的倒数 (1/PB)            | 同HML（暂未实现剔除小市值逻辑）             |
| MGMT         | 资产增长率                 | 作为管理因子的代理                          |
| PERF         | ROE                        | 作为绩效因子的代理                          |
| REV          | 日频收盘价                 | 过去20日累计收益率                          |
| IVOL         | 日频收盘价                 | 过去20日收益率滚动标准差                    |

### PIT原则（Point-in-Time）

获取财务报表数据时，采用PIT原则确定报告期，确保使用已披露的财务数据，避免使用距离交易日最近但尚未披露的财务数据。

**报告期选择规则**：

| 交易日期           | 强制使用的报告期 | 说明                        |
| ------------------ | ---------------- | --------------------------- |
| 5月1日 - 8月31日   | Q1 (0331)        | 此时年报和一季报肯定都已出齐 |
| 9月1日 - 10月31日  | Q2 (0630)        | 此时中报肯定已出齐          |
| 11月1日 - 次年4月30日 | Q3 (0930)    | 此时三季报肯定已出齐        |

> 原则上最理想情况是结合公告日期，因为akshare提供的财报(东财接口)是最新修订的，理论上去年的财务数据也可能被修订过

### 前视偏差(Look-Ahead Bias)控制

所有因子计算均严格控制前视偏差：
- 股价数据：使用前复权数据
- 财务数据：确保PIT原则，使用已披露的财务数据

## License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
