Metadata-Version: 2.4
Name: tidequant
Version: 0.3.0
Summary: TideQuant因子层: 算子库、表达式因子求值与历史因子生成引擎
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: bottleneck
Requires-Dist: jsonargparse
Requires-Dist: loguru
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: polars
Requires-Dist: pyarrow
Requires-Dist: setproctitle
Requires-Dist: tqdm

# TideQuant 潮汐量化
顺势而生,逆势有度

本包发布的是 TideQuant 的**因子层**: 算子库、表达式因子求值,
以及从历史逐笔数据生成因子库的引擎。交易执行、交易所对接与看板
不在这个包里。

## 安装

```bash
pip install tidequant
```

## 因子计算

```python
from tidequant.factor import OPS, evaluate, parse

node = parse("cs_zscore(ts_mean(amount / volume, 20))")
value = evaluate(node, lambda leaf: load(leaf))
```

`OPS` 是算子表,`register` 可以往里加自定义算子。算子分三族:
`ts_` 时序、`cs_` 截面、`ew_` 指数加权。

## 生成历史因子库

读取逐笔 trade 数据,按 interval 聚合字段因子,再对 `factors.json`
里的表达式因子沿整个时间轴求值:

```bash
python -m tidequant.engine.history_factor_generator \
    --tbt_folder data/binance/trades --out_folder data/factors_15m \
    --start_dt 2022-07-01 --end_dt 2026-07-01 --interval 15m
```

已生成的因子自动跳过,中断后重跑自动续写。用 `--factors_path`
指向自己的因子名单文件即可替换内置的 `factors.json`。

因子库读写接口在 `tidequant.data.FactorBase`。

## A 股侧因子框架 `tidequant.factor_base`

另一套独立的因子框架,解析的是 A 股因子清单那套老语法(函数调用 +
窗口后缀 + 管道):

```python
from tidequant.factor_base.legacy import parse
from tidequant.factor_base.engine import OPS, evaluate_contiguous

node = parse("ECORR_2(vwapAdj|PctChange_1, volume|PctChange_1)")
```

`legacy.parse` 出 `Leaf`/`Const`/`Call` 三种 AST 节点,`engine.OPS`
是算子表(103 个,其中 44 个语义尚未对拍,见 `UNVERIFIED_OPS`)。
`ops/ts.py` 是 numba 实现的时序算子,`ops/cs.py` 是截面算子,
`l1/` 是逐笔成交到分钟字段的字段层。

`config.REF_LIB` 默认指向作者机器上的参照库挂载,换机器用环境变量
`FACTOR_BASE_REF_LIB` 指过去;产出目录同理用 `FACTOR_BASE_OUT`。
`scripts/` 下是对拍与考古脚本,跑它们需要参照库。

## 研究侧 `tidequant.research`

三棵研究代码树,原样收进来:

- `research.yky` —— 因子挖掘系统:L1 事件流构建、算子与因子说明文档
  (`docs/` 下的 HTML)、smoke test 的完整性核对产物与 LightGBM 训练脚本。
- `research.intraday` —— 日内深度学习栈:截面数据集(h5py / 3FS 用户态
  直读两种后端)、训练引擎、模型定义与 3FS IO 封装。
- `research.scripts` —— 配套的研究脚本:建 h5 库、训练、IC 与 spread 对比、
  因子清单盘点。

这些模块的重依赖(`torch`、`ray`、`h5py`、`lightgbm`、`matplotlib`、
`scipy`、`xarray`、`accelerate`、`transformers`、`cupy`)**不在本包的
依赖里**,要跑哪块自己装对应的库。

内部数据路径都改成了环境变量兜底,默认值仍是原机器上的挂载点:
`INTRADAY_REPO`、`FACTORMINING_ROOT`、`FACTOR_DATA_ROOT`、
`FACTOR_TEST_ROOT`、`BAR162N_TRAIN_BIN`、`BAR162N_TEST_BIN`、
`X_LISTS_162N`、`EXP_LOGS_162N`、`H5_162N_ROOT`、`DEEPFACTOR_META`。

两点需要知道:

- `research.yky` 是上游 `factormining` 仓库的一个切片。`yky/build_l1.py`
  要 `construct_features`,`yky/smoke_test/regen_factors.py` 要
  `factor_loader`,两者都在上游仓库里、没有收进本包 —— import 它们会得到
  一句说明怎么办的 `ImportError`。同目录其余脚本不受影响。
- `research.intraday.utils.hf3fs` 需要 3FS 客户端(`hf3fs_py_usrbio` 加
  `libhf3fs_api_shared.so`),不在 PyPI 上。数据集构造参数传
  `use_hf3fs=False` 走 h5py 后端即可。
