# 期货 / CTA 因子库

[中文](README.md) · [English](README.en.md)

连接跨资产趋势、商品 Carry、库存和持仓压力，把合约换月与风险预算纳入同一研究流程。

本次根据学术文献新建研究目录、经济逻辑、数据契约和独立基础示例；不是已有完整市场数据因子库的迁移。

## 网页与语言切换

[中文网页](https://yuedai-pbc.github.io/futures-factor-library/?lang=zh) · [English website](https://yuedai-pbc.github.io/futures-factor-library/?lang=en)

网页的概览、目录、因子详情、构建思路、特征工程、文献说明及交互提示均提供中英文。使用右上角 中文 / English 切换，也支持双语检索。代码 ID、论文原题、作者、公式变量和标注为上游原文的材料保留原样，以便核对来源。

离线打开 `site/index.html`，或在仓库根目录启动：

```sh
python -m http.server 8000
```

访问 [localhost:8000/site/](http://localhost:8000/site/).

## 内容规模

- **30**: 研究条目
- **12**: 学术与方法文献
- **0**: 已完成真实数据回测

## 构建思路

1. **合约与交易日历** — 品种、合约、交易所、乘数、最小变动、结算价、到期、交割、交易时段和公告时点版本化；夜盘归属交易日须一致。

2. **连续序列与换月** — 先确定流动性、到期安全距离和换月规则；用昨日持仓逐合约累计损益，不能把拼接价跳跃视为投资收益。

3. **信号与组合** — 分别记录时间序列方向、横截面排名、carry 和供需特征；风险缩放使用历史估计，设置品种、板块和杠杆约束。

4. **样本外与实施** — 纳入佣金、价差、冲击、涨跌停和换月成本；按名义本金与实际资本分别报告收益，抵押现金收益单列，保证金不是收益率分母的默认选择。

5. **特征家族与增量检验** — 先复现基准定义，再登记允许的窗口、变化率、条件残差和少量交互。按经济家族分组去重，使用时间滚动、跨市场留出和成本后消融检验。预计数量与数据前提见特征工程页。

## 特征工程与泛化预算

计划 24 个种子 × 每种子 4–7 种允许表达 = **96–168 个候选列**，包含基础表达。这是依赖数据的构建预算，不是已实现数量或有效 alpha 数量。

先趋势和曲线，再加入库存、持仓与分布；仓位缩放和损益核算不作为预测种子计入 24 个预算。

[完整特征工程方案](FEATURE_ENGINEERING.md)

## 运行与测试

Python 3.10+；基础示例仅使用标准库。

```sh
python examples/demo.py
python -m unittest discover -s tests -v
```

## 文件与研究文档

- `site/`: 可离线浏览的静态网页。
- `docs/`: 同一套 GitHub Pages 网页与双语研究文档。
- `data/catalog.json` / `data/catalog.en.json`: 中文 / 英文因子目录。
- `data/references.json` / `data/references.en.json`: 中文 / 英文书目说明。
- `src/factors.py`: 独立编写的基础算子。
- [方法与经济逻辑](METHODOLOGY.md)
- [输入与时点约束](DATA_CONTRACT.md)
- [来源与实现边界](PROVENANCE.md)
- [论文与引用关系](REFERENCES.md)
- [双语复核记录](BILINGUAL_AUDIT.md)

## 完成度与待验证事项

- 30 项包含文献候选、风险度量、组合方法和明确标注的扩展假设，不等于独立有效 alpha 数量。
- 新建学术研究框架，尚无授权期货行情和完整回测；基础信号、基差与逐合约损益有独立示例。
- 商品库存与商业套保持仓适用范围有限；股指、利率、外汇不能机械套用商品供需变量。
- 负价格时对数基差无定义，应采用明确替代指标；不能静默取绝对值。

## GitHub Pages 发布

本仓库网页从 `main` 分支的 `/docs` 发布。更新网页时同步 `site/` 与 `docs/` 的静态资源；GitHub Actions 验证 Python 示例，Pages 构建独立运行。

## 数据、来源与许可

示例输入是教学数据，不含真实持仓、原始行情、账户信息或连接凭据；不宣称真实样本外业绩。新写网页及示例代码采用 GPL-2.0。论文版权属于原作者与出版方，完整第三方报告不重新分发；OAP 元数据保留上游署名。