Metadata-Version: 2.4
Name: silars
Version: 2026.7.29.0
Summary: Silars - Alpha lens and backtesting library
License-Expression: MIT
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: ipython>=9.5.0
Requires-Dist: lidb>=2026.7.15.2
Requires-Dist: logair
Requires-Dist: numpy>=2.3.1
Requires-Dist: pandas>=2.3.1
Requires-Dist: plotly>=6.3.0
Requires-Dist: matplotlib
Requires-Dist: polars
Requires-Dist: pyecharts
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: mlflow>=3.8.1
Requires-Dist: polars-ds>=0.12.0
Requires-Dist: cvxpy>=1.8.1
Requires-Dist: ecos>=2.0.14
Requires-Dist: atrs
Requires-Dist: tqdm
Requires-Dist: ygo
Dynamic: license-file

# Silars

Silars 是基于 Polars 的因子分析与回测工具库，提供数据预处理、组合权重、策略和回测入口。

## 安装

Silars 需要 Python 3.12 或更高版本；CI 持续验证 Python 3.12 和 3.13。

```bash
pip install silars
```

使用 uv：

```bash
uv add silars
```

## 最小示例

下面按每个 `(date, time)` 截面选择得分最高的两个资产，并生成等权组合：

```python
from copy import deepcopy

import polars as pl

from silars.alphalens import top_k

scores = pl.DataFrame(
    {
        "date": ["2026-01-02"] * 3,
        "time": ["09:31:00"] * 3,
        "asset": ["A", "B", "C"],
        "score": [0.2, 0.8, 0.5],
    }
)

selector = deepcopy(top_k).set_params(num=2)
weights = selector.transform(scores)
print(weights.select("date", "time", "asset", "target_weight"))
```

## 主要入口

- `Preprocessor` 及预处理函数：因子清洗、标准化和中性化。
- `top_k`、`qcut`、`MFEs` / `MFEConfig`：组合权重生成。
- `Strategy`、`FactorStrategy`：策略编排。
- `BacktestEngine`、`bt`：回测。
- `Zoo`、`zoo`：因子数据工作区。

这些入口均从 `silars.alphalens` 导入。

## 研究期 tree shortlist

`silars.feature_selection.select_features` 用固定的单特征浅树，按独立验证期的每日
prediction RankIC 对已物化数值特征做粗筛：

```python
from silars.feature_selection import select_features

ranking = select_features(
    train,
    valid,
    feature_names,
    "forward_return",
    max_features=100,
)
```

它衡量的是 `tree(feature)` 对下游模型的排序潜力，不是原始特征 RankIC、独立 OOS、
显著性结论或可直接传给 MFEs 的 `score`。PIT、purge/embargo、正式评估和发布仍由
调用方及 `factor_eval` 负责。该入口也不同于
`silars.alphalens.evaluate.select_features` 的多重检验与相关性筛选。

## 基准对冲回测

对已加载的 `Zoo`，可复用原多头回测并得到 1:1 对冲收益。传入指数代码时读取对应
指数日收益：

```python
from silars.alphalens import FactorStrategy, zoo

results = zoo.hedge(
    ["KMID"],
    FactorStrategy(),
    index_code="000300",
    times=["09:31:00", "10:00:00"],
)
print(results["KMID"]["ret"])
print(results["KMID"]["metric"])
```

`hedge()` 会立即完成回测、显示多头/基准/对冲组合净值图，并返回每个因子的
`pos`、`ret` 和对冲组合 `metric`，不是延迟任务生成器。

`index_code=""` 时不读取指数，直接从回测输入的 `prev_close/open/close` 构造等权市场
日收益，结果列为 `mkt` 和 `long-mkt`。指数路径运行时需要当前环境可导入
`dc.data.base.ds_index_retC2C`；`period` 仅控制原组合持仓周期，不缩放日度基准收益。

## 许可证

Silars 使用 MIT License。`silars/empyrical` 包含 Apache-2.0 许可的第三方代码，详见
`THIRD_PARTY_NOTICES.md` 和 `LICENSES/Apache-2.0.txt`。
