Metadata-Version: 2.4
Name: alpha-lab
Version: 0.1.7
Summary: A High-performance And Standard Alpha Factor Mining System
Author-email: huangbogeng <huangbogeng@outlook.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: polars>=1.39.2
Requires-Dist: pandas>=3.0.0
Requires-Dist: clickhouse-driver>=0.2.6
Requires-Dist: pyarrow>=23.0.0
Requires-Dist: numpy>=2.4.0
Requires-Dist: scipy>=1.15.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: sqlparse>=0.5.5
Requires-Dist: dynaconf>=3.2.13
Requires-Dist: rich>=14.3.3
Requires-Dist: varname>=0.15.1
Requires-Dist: toolz>=1.1.0
Requires-Dist: polars_ds>=0.11.0
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: matplotlib>=3.10.8
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Alpha Lab

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![Polars](https://img.shields.io/badge/Polars-Fast-orange.svg)](https://pola.rs/)

专为因子研究员设计的数据处理与因子挖掘框架，提供简洁的数据获取接口和专业的因子分析工具。

---

## 安装

```bash
# 使用 uv 安装（推荐）
uv pip install alpha-lab

# 或使用 pip
pip install alpha-lab
```

---

## 快速开始

### 1. 读取数据

```python
import polars as pl
import datacenter as dc
from tool_box.xcals import api

# 获取交易日列表
trading_days = api.get_tradingdays("2023-01-01", "2023-01-31")

# 读取股票日线数据
df = dc.md.read_data_batch(
    start_date="2023-01-01",
    end_date="2023-01-31",
    instrument=dc.Instrument.STOCK,
    data_type=dc.DataType.KLINE_DAY
)

# 读取基础信息
stocks = dc.jy.asset(date="2023-01-01")      # 可用股票
industry = dc.jy.industry(date="2023-01-01")  # 行业分类
adj_factors = dc.jy.adj_factors(date="2023-01-01")  # 复权因子
```

### 2. 计算因子

使用 Polars 简洁高效地计算因子：

```python
# 计算 5 日收益率因子
factor_df = df.with_columns(
    ret_5d=pl.col("close").pct_change(5)
).filter(
    pl.col("volume") > 0  # 过滤停牌
)

# 更多因子示例
factor_df = df.with_columns(
    ret_1d=pl.col("close").pct_change(1),
    ret_5d=pl.col("close").pct_change(5),
    ret_20d=pl.col("close").pct_change(20),
    volume_ratio=pl.col("volume") / pl.col("volume").rolling_mean(20),
).filter(pl.col("volume") > 0)
```

### 3. 因子分析 (Rack + Polens)

使用 Rack 整合数据，Polens 进行专业因子分析：

```python
from alphamaster.rack import Rack
from alphamaster.polens import FactorAnalyzer

# Rack: 加载行情数据并整合因子
rack = Rack()
rack.load_prices("2023-01-01", "2023-12-31")  # 加载行情
rack.set_factor(factor_df)                      # 设置因子

# Polens: 因子分析
analyzer = FactorAnalyzer(rack.get_data(), group_col="industry")
analyzer.preprocess(periods=[1, 5, 10], quantiles=5)
analyzer.analyze()

# 获取统计指标
stats = analyzer.summary_stats()
print(stats)

# 绘制分析图表
analyzer.plot("ic_ts")           # IC 时序图
analyzer.plot("quantile_cum")    # 分层累积收益
analyzer.plot("stability")       # 因子稳定性
```

> **提示**: Rack 会自动缓存行情数据，更换因子时无需重新加载。

---

## 核心模块

| 模块 | 说明 |
|------|------|
| `datacenter` | 数据访问层，统一获取行情和基础信息 |
| `tool_box.xcals` | 交易日历工具 |
| `alphamaster.rack` | 数据整合器，加载行情并整合因子数据 |
| `alphamaster.polens` | 因子分析工具（IC、分层收益、换手率等） |

---

## 许可证

[MIT](LICENSE)
