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

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

## 功能特性

- **多因子模型支持**: FF3、FF5、CARHART、NOVY_MARX、HOU_XUE_ZHANG、DHS、CAPM
- **因子收益计算**: 独立排序，支持多种加权方案
- **个股暴露计算**: 通过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, RMW, CMA      | Novy-Marx四因子              |
| **HOU_XUE_ZHANG** | MKT, ME, IA, ROE        | Hou-Xue-Zhang四因子          |
| **DHS**           | MKT, SMB, IDIO_VOL      | Daniel-Hirshleifer-Sun三因子 |

## 数据原则

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

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

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

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

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

**使用示例**：

```python
# 在 get_financial_data 中传入 trade_date 参数启用PIT原则
financial_data = data_provider.get_financial_data(
    data_type="LRB",
    trade_date="2024-06-15"  # 6月15日 -> 对应Q1(0331)报告期
)
```

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

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

## License

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