Metadata-Version: 2.4
Name: finosdk-preview
Version: 0.0.1a3
Summary: A package for financial data fetching and analysis
License: MIT
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.1
Requires-Dist: pandas<3,>=1.5
Dynamic: license-file

# finosdk安装指导

## 概述

`finosdk`是 Finoview 数据服务的 Python SDK ，用于快速访问量化因子、评级预测、宏观指标等数据接口。

适用于开发者、量化研究员及机构客户进行测试与集成。

## 环境要求

| 项目        | 要求                                                         |
| ----------- | ------------------------------------------------------------ |
| Python 版本 | ≥ 3.10（推荐 3.10 或 3.11）                                  |
| 操作系统    | Windows / macOS / Linux                                      |
| 依赖环境    | pip 或 conda 环境均可<br />requests ：≥ 2.25.1（HTTP 调用）<br />pandas ：≥ 1.5（数据处理） |

## 通用安装Volatility

```cmd
pip install -U finosdk-preview==0.0.1a3 -i https://pypi.org/simple
```

## 配置环境变量

### Windows PowerShell:

```powershell
$env:FINO_BASE_URL="https://track.finoview.com.cn/data_api/"
$env:FINO_API_KEY="your_api_key"
```

### Windows CMD:

```cmd
set FINO_BASE_URL=https://track.finoview.com.cn/data_api/
set FINO_API_KEY=your_api_key
```

若你没有 API Key，请联系 Finoview 管理员或销售团队申请测试密钥

## 初始化配置

```python
import finosdk as fino
fino.init()
```

## 因子类型

| 因子类别                     | 对应函数                |
| ---------------------------- | ----------------------- |
| 量价趋势类因子（Trend）      | fino.get_fac_trend      |
| 期限结构/价差类因子（Carry） | fino.get_fac_carry      |
| 仓单类因子（Warrant）        | fino.get_fac_warrant    |
| 期现类因子（Futurespot）     | fino.get_fac_futurespot |
| 持仓类因子（Position）       | fino.get_fac_position   |
| 价值类因子（Value）          | fino.get_fac_value      |
| 波动类因子（Volatility）     | fino.get_fac_volatility |

### 输入参数字段

| 字段       | 字段类型 | 字段说明                                                     |
| ---------- | -------- | ------------------------------------------------------------ |
| start_date | String   | 开始日期（格式：20250728）                                   |
| end_date   | String   | 结束日期（格式：20250730）                                   |
| code_list  | List     | 合约代码列表(大写格式：CU,RB)                                |
| factor     | List     | 因子名                                                       |
| section    | List     | 板块名称，包括"有色","黑色","能源","化工","农产品","贵金属"，"航运"。 |

注意：

```python
#当code_list、factor和section同时置空，即返回全量的品种内容。
fino.get_fac_trend(start_date="20240602",end_date="20250130",code_list=[],factor=[],section=[],)

#若不输入code_list、factor和section参数，也即返回全量的品种内容。
fino.get_fac_trend(start_date="20250102",end_date="20250130",)

#当sections设置参数，返回全量板块品种因子。
fino.get_fac_trend(start_date="20240602",end_date="20250130",code_list=[],factor=[],section=["农产品"],)

#当code_list 与 sections设置参数，若交集为空，返回并集，同时返回全量因子。
fino.get_fac_trend(start_date="20240602",end_date="20250130",code_list=["AL"],factor=[],section=["农产品"],)


#当code_list 与 sections设置参数，若交集非空：返回交集，同时返回全量因子。
fino.get_fac_trend(start_date="20240602",end_date="20250130",code_list=["JD"],factor=[],section=["农产品"],)
```

### 量价趋势类因子（Trend）

由期货价格所反映出来的趋势信息，最简单的形式即为动量。期货由于存在一定的自相关性，过去的历史信息一定程度上可以影响到未来的走势。我们统计的量价指标以常见的各种趋势、动量指标为主。

调取样例：

```python
fino.get_fac_trend(start_date="20240602",end_date="20250130",code_list=["A"],factor=["T_macross_K5"],section=["农产品"],)
```

| 因子        | 因子名                   | 说明                                      | 补充说明        | k取值范围                          | 起始时间 | 更新频度 |
| ----------- | ------------------------ | ----------------------------------------- | --------------- | ---------------------------------- | -------- | -------- |
| T_macross   | 快慢均线的相对比率       | 默认参数K为慢均线参数                     | K/2为快均线参数 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_mamom     | 长期动量                 | 200天慢均线的动量                         |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_maratio   | 乖离率                   | K线与均线的相对比率                       |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_signalmom | 符号动量                 | 过去K天收益率为正的比例                   |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_mom       | 动量                     | 过去K日的累计涨跌幅                       |                 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| T_routemom  | 路径动量                 | 过去K日实际涨跌幅与绝对涨跌幅之间的比值   |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_intraday  | 日内动量                 | （今收-今开）/今开                        | 过去K日取平均   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| T_overnight | 隔夜价差                 | （今开-昨收）/昨收                        | 过去K日取平均   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| T_cumstep   | 日K线反映的日内累计波幅  | （2*(H-L)*sign(C-O)-(C-O)）/C             | 过去K日取平均   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| T_signvol   | 日内波动与日涨幅符号乘积 | sign(C-O) *vol_GK                         | 过去K日取平均   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| T_pctmom    | 分位值动量               | 当前时点价格在过去K日历史分位数           |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_puremom   | 纯粹动量                 | 过去K日剔除涨跌幅在±5%以外的动量         |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_highmom   | 摸高动量                 | 当前时点价格相对过去K日内高点的比值       |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_lowmom    | 触底动量                 | 当前时点价格相对过去K日内低点的比值       |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_locatemom | 空间动量                 | 当前时点价格相对过去K日内高点与低点的位置 |                 | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| T_barmom    | bar动量                  | 开盘与收盘之差较最高价与最低价之差的比值  | 过去K日取平均   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |

### 期限结构/价差类因子（Carry）

价差因子是用于描述期货品种不同月份合约之间期限结构差异的一类因子，本质上它的策略形成逻辑是“相对意义上的多空展期收益差”。

调取样例：

```python
fino.get_fac_carry(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["C_frontnext_K90"],section=[],)
```

| 因子        | 因子名           | 说明                                                            | 补充说明                  | k取值范围                          | 起始时间 | 更新频度 |
| ----------- | ---------------- | --------------------------------------------------------------- | ------------------------- | ---------------------------------- | -------- | -------- |
| C_frontnext | 当月次月carry    | 次月合约较当月合约的年化价差比率                                | 过去K天平均值             | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_mainsub   | 主力次主力carry  | 次主力合约较主力合约的年化价差比率                              | 过去K天的平均值           | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_lfnormal  | OLS等权拟合carry | 期限结构曲线的直线拟合年化斜率（拟合权重等权）                  | 斜率值取过去K天的平均值   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_lfshort   | OLS拟合短端carry | 期限结构曲线的直线拟合年化斜率（拟合权重以近期为主）            | 斜率值取过去K天的平均值   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_lflong    | OLS拟合长端carry | 期限结构曲线的直线拟合年化斜率（拟合权重以远期为主）            | 斜率值取过去K天的平均值   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_lfmiddle  | OLS拟合中端carry | 期限结构曲线的直线拟合年化斜率（拟合权重以中期为主）            | 斜率值取过去K天的平均值   | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_nsnormal  | NS等权拟合carry  | 期限结构曲线的Nelson-Siegel拟合的一阶系数（拟合权重等权）       | 一阶系数取过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_nsshort   | NS拟合短端carry  | 期限结构曲线的Nelson-Siegel拟合的一阶系数（拟合权重以近期为主） | 一阶系数取过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_nslong    | NS拟合长端carry  | 期限结构曲线的Nelson-Siegel拟合的一阶系数（拟合权重以远期为主） | 一阶系数取过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| C_nsmiddle  | NS拟合中端carry  | 期限结构曲线的Nelson-Siegel拟合的一阶系数（拟合权重以中期为主） | 一阶系数取过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |

### 仓单类因子（Warrant）

交易所的注册仓单数量一定程度上反映了期货现货商愿意交割的意愿，同时也作为一种形式的库存数据。当仓单数量上涨，说明当前现货库存水平相对较高、现货商更愿抛售现货而用于交割，对价格形成压力；反之，仓单数量下降，对价格形成支撑。

调取样例：

```python
fino.get_fac_warrent(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["W_yoy_K90"],section=[],)
```

| 因子    | 因子名           | 说明                                                | 补充说明                                     | k取值范围                          | 起始时间 | 更新频度 |
| ------- | ---------------- | --------------------------------------------------- | -------------------------------------------- | ---------------------------------- | -------- | -------- |
| W_yoy   | 仓单同比变化     | 注册仓单数量较历史同期的相对变化                    | 过去K日平均值与过去200-300交易日平均值的比值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/3/7 | 日度     |
| W_pct   | 仓单相对强弱     | 当前注册仓单数量在过去K日中的百分位数               | 取近10日平均                                 | 5 10 20 40 60 90 120 150 180 240   | 2008/3/7 | 日度     |
| W_ratio | 仓单趋势相对比值 | 当前注册仓单的近10日平均较过去K日平均水平的相对比值 |                                              | 5 10 20 40 60 90 120 150 180 240   | 2008/3/7 | 日度     |

### 期现类因子（Futurespot）

期货是现货未来的价格预期，影响现货价格的供需因素同样对期货价格造成影响，但由于期货的到期日效应，使得期货与现货之间的价差不会出现较大的偏离。我们发现，期货较现货贴水收益越多，越有可能上涨，且存在所谓的“基差动量效应”，即过去期货较现货涨得越多，未来越可能继续上涨。

调取样例：

```python
fino.get_fac_futurespot(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["Fs_basis_K90"],section=[],)
```

| 因子       | 因子名     | 说明                                             | 补充说明        | k取值范围                          | 起始时间 | 更新频度 |
| ---------- | ---------- | ------------------------------------------------ | --------------- | ---------------------------------- | -------- | -------- |
| Fs_basis   | 基差       | 现货价格与期货主力合约价格的差值                 | 过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| Fs_carry   | 年化基差率 | 现货价格与主力合约的年化价差比率                 | 过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| Fs_exmom   | 基差动量   | 期货主力合约过去K天涨跌幅与现货过去K天涨跌幅之差 |                 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| Fs_ratemom | 期现比动量 | 期货主力/现货                                    | 较K天前的差值   | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| Fs_rate    | 现期比     | 现货/期货                                        | 过去K天的平均值 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |

### 持仓类因子（Position）

根据每日交易所披露的各会员单位的成交、持仓排名情况，总结出主要会员单位的多空持仓强弱比值、净多头等，在合计计算了持仓排名前N名的多空持仓数量后，我们发现净多头动量、多空持仓变动相对强弱等指标有微弱的截面收益能力。

调取样例：

```python
fino.get_fac_position(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["Pr_netmom_K90"],section=[],)
```

| 因子          | 因子名             | 说明                                                        | 补充说明      | k取值范围                          | 起始时间 | 更新频度 |
| ------------- | ------------------ | ----------------------------------------------------------- | ------------- | ---------------------------------- | -------- | -------- |
| Pr_netmom     | 净持仓动量         | 净多头（多空之差）的动量效应（较K日之前的变化量）           |               | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/1 | 日度     |
| Pr_lsratio    | 净持仓多空相对强弱 | 持仓排名前N名合计后的多空相对强弱                           | 取过去K日平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/1 | 日度     |
| Pr_lschgratio | 持仓变化的相对强弱 | 持仓排名前N名合计后多头持仓变动与空头持仓变动的相对强弱关系 | 取过去K日平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/1 | 日度     |

### 价值类因子（Value）

期货的价格会以现货价格为重心而上下波动，根据AQR对期货价值的定义，现货价格的长期收益应存在反转效应，原因在于现货价格长期看因为供需的周期性而具有均值回复特征。而我们发现国内期货对应的现货价格在半年至两年内存在动量效应。

调取样例：

```python
fino.get_fac_value(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["Val_halfyear_K90"],section=[],)
```

| 因子          | 因子名     | 说明                             | 补充说明      | k取值范围                          | 起始时间 | 更新频度 |
| ------------- | ---------- | -------------------------------- | ------------- | ---------------------------------- | -------- | -------- |
| Val_halfyear  | 半年期价值 | 现货价格较半年前现货价格的变化率 | 过去K日取平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/3 | 日度     |
| Val_oneyear   | 一年期价值 | 现货价格较一年前现货价格的变化率 | 过去K日取平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/3 | 日度     |
| Val_twoyear   | 两年期价值 | 现货价格较两年前现货价格的变化率 | 过去K日取平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/3 | 日度     |
| Val_threeyear | 三年期价值 | 现货价格较三年前现货价格的变化率 | 过去K日取平均 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/7/3 | 日度     |

### 波动类因子（Volatility）

期货合约的波动率一方面和期货本身的交易规则相关，另一方面也和本身标的资产的波动属性有关。量化CTA策略大多以期货高波动为前提，所以我们更关心波动性是否可以带来收益。我们可以利用这类因子来刻画市场的波动风格，即波动性对收益贡献大小。

调取样例：

```python
fino.get_fac_volatility(start_date="20240602",end_date="20250130",code_list=["AL"],factor=["Vol_std_K90"],section=[],)
```

| 因子    | 因子名     | 说明                                          | k取值范围                          | 起始时间 | 更新频度 |
| ------- | ---------- | --------------------------------------------- | ---------------------------------- | -------- | -------- |
| Vol_std | 样本波动率 | 过去K日的收益率的标准差                       | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| Vol_ema | 加权波动率 | 过去K日的收益率的幂指数加权标准差             | 5 10 20 40 60 90 120 150 180 240   | 2008/1/2 | 日度     |
| Vol_GK  | GK波动率   | Garman & Klass给出过去K日的波动率估算方法     | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| Vol_RS  | RS波动率   | Roger & Satchell给出的过去K日的波动率估算方法 | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |
| Vol_PK  | PK波动率   | Parkingson给出的过去K日的波动率估算方法       | 1 5 10 20 40 60 90 120 150 180 240 | 2008/1/2 | 日度     |

## CSFT 因子回测结果表

CSFT 系列表（CTA 因子项目）用于存储量化因子在不同阶段的回测与测试结果数据。这些表覆盖了从因子样本内回测（Backtest）到样本外验证（Out-of-sample Test）的完整分析流程，

可用于以下用途：

* 因子有效性评估（IC、收益率、夏普比、回撤等指标）
* 因子稳定性与分层表现分析（分组收益、Q1~Q5分层差）

### 输入参数字段

| 字段       | 字段类型 | 字段说明                             |
| ---------- | -------- | ------------------------------------ |
| start_date | String   | 开始日期（格式：20250728）           |
| end_date   | String   | 结束日期（格式：20250730）           |
| factor     | List     | 因子名，默认置空即返回全量的品种内容 |

注意：

```python
fino.get_csft_bkt_perf(start_date="20240602",end_date="20250130",factor=[],)
#当factor置空，即返回全量的因子内容。
fino.get_csft_bkt_perf(start_date="20240602",end_date="20250130",)
#当不输入factor为参数，即返回全量的因子内容。
```

### csft_bkt_perf — 因子回测绩效表

调用函数：fino.get_csft_bkt_perf

存储样本内（in-sample）因子绩效指标，包括收益率、夏普比、最大回撤、IC 等。用于整体衡量因子在训练样本期的表现。

调取样例：

```python
fino.get_csft_bkt_perf(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段         | 字段名称          | 指标说明                                                       | 起始时间   | 更新频度 |
| ------------ | ----------------- | -------------------------------------------------------------- | ---------- | -------- |
| factor       | 因子              | 因子代码                                                       | 2024-08-02 | 周度     |
| date         | 日期              | 计算日期                                                       | 2024-08-02 | 周度     |
| name         | 因子名            | 因子名，同factor，一般为"因子类别_k数字"，其中数字即为因子参数 | 2024-08-02 | 周度     |
| factor_class | 因子类别          | 对应因子名name中的因子类别                                     | 2024-08-02 | 周度     |
| k            | 因子参数          | 对应因子名name中的因子参数                                     | 2024-08-02 | 周度     |
| start_date   | 起始日            | 回测区间的起始日期                                             | 2024-08-02 | 周度     |
| end_date     | 截止日            | 回测区间的截止日期                                             | 2024-08-02 | 周度     |
| sample_len   | 样本数量          | 回测样本长度（期数）                                           | 2024-08-02 | 周度     |
| sample_freq  | 样本频率          | 回测样本采样频率                                               | 2024-08-02 | 周度     |
| yr_factor    | 年化参数          | 年化参数：日，244；周，50；月，12                              | 2024-08-02 | 周度     |
| total_ret    | 收益              | 区间总收益                                                     | 2024-08-02 | 周度     |
| yr_ret       | 年化收益          | 年化收益                                                       | 2024-08-02 | 周度     |
| yr_vol       | 年化波动          | 年化波动                                                       | 2024-08-02 | 周度     |
| max_drawdown | 最大回撤          | 最大回撤                                                       | 2024-08-02 | 周度     |
| sharp        | 夏普比率          | 年化收益/年化波动                                              | 2024-08-02 | 周度     |
| calmar       | Calmar            | 年化收益/最大回撤                                              | 2024-08-02 | 周度     |
| sortino      | Sortino           | 年化收益/下行风险                                              | 2024-08-02 | 周度     |
| winrate      | 胜率              | 胜率                                                           | 2024-08-02 | 周度     |
| maxdd_start  | 最大回撤-起始     | 最大回撤区间的起始日                                           | 2024-08-02 | 周度     |
| maxdd_end    | 最大回撤-截止     | 最大回撤区间的截止日，如有                                     | 2024-08-02 | 周度     |
| maxdd_len    | 最大回撤-回补天数 | 最大回撤区间的长度                                             | 2024-08-02 | 周度     |
| ytd_ret      | 收益-今年以来     | 今年以来实际收益                                               | 2024-08-02 | 周度     |
| oneweek_ret  | 收益-最近一周     | 最近一周实际收益                                               | 2024-08-02 | 周度     |
| onemon_ret   | 收益-最近一月     | 最近一个月实际收益                                             | 2024-08-02 | 周度     |
| threemon_ret | 收益-最近三月     | 最近三个月实际收益                                             | 2024-08-02 | 周度     |
| halfyear_ret | 收益-最近半年     | 最近半年实际收益                                               | 2024-08-02 | 周度     |
| oneyear_ret  | 收益-最近一年     | 最近一年实际收益                                               | 2024-08-02 | 周度     |
| leverage_avg | 平均杠杆          | 平均持仓杠杆/仓位，名义市值/净资产                             | 2024-08-02 | 周度     |
| yr_tno       | 年换手            | 买卖双边，每期换手率（每期交易量 / 上一期末总资产) * 年化参数  | 2024-08-02 | 周度     |
| yr_tno_stg   | 年换手(策略)      | 由策略调仓引发的交易换手，每期换手 * 年化参数                  | 2024-08-02 | 周度     |
| yr_tno_roll  | 年换手(展期)      | 由合约展期引发的交易换手，每期换手 * 年化参数                  | 2024-08-02 | 周度     |
| yr_tradecost | 年交易成本        | 年化换手量 * 单边交易费率                                      | 2024-08-02 | 周度     |

### csft_bkt_data — 因子回测原始数据表

调用函数：fino.get_csft_bkt_data

存储回测阶段逐日（或逐周期）收益数据，是绩效表的基础来源，可用于细粒度的收益序列分析。

调取样例：

```python
fino.get_csft_bkt_data(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段       | 字段名称     | 指标说明                     | 起始时间   | 更新频度 |
| ---------- | ------------ | ---------------------------- | ---------- | -------- |
| factor     | 因子         | 因子代码                     | 2010-01-08 | 周度     |
| date       | 日期         | 计算日期                     | 2010-01-08 | 周度     |
| nv         | 净值         | 净值                         | 2010-01-08 | 周度     |
| drawdown   | 回撤         | 回撤                         | 2010-01-08 | 周度     |
| dcp_real   | 策略实际收益 | 收益拆解：实际各期总收益     | 2010-01-08 | 周度     |
| dcp_roll   | 展期等效贡献 | 收益拆解：各期合约展期收益   | 2010-01-08 | 周度     |
| dcp_change | 价格变动贡献 | 收益拆解：各期价格变动收益   | 2010-01-08 | 周度     |
| tno_stg    | 期换手(策略) | 每期由策略调仓引发的交易换手 | 2010-01-08 | 周度     |
| tno_roll   | 期换手(展期) | 每期由合约展期引发的交易换手 | 2010-01-08 | 周度     |
| tno        | 期换手       | 每期合计总换手               | 2010-01-08 | 周度     |

### csft_bkt_dcp — 因子回测分组收益表

调用函数：fino.get_csft_bkt_dcp

本表根据因子值大小，将样本内数据分为若干层（如 Q1~Q5），计算每层的收益表现。可用于衡量因子的多空分层能力及投资组合构建效果。

调取样例

```python
fino.get_csft_bkt_dcp(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段          | 字段名称         | 指标说明                                                      | 起始时间   | 更新频度 |
| ------------- | ---------------- | ------------------------------------------------------------- | ---------- | -------- |
| factor        | 因子             | 因子代码                                                      | 2010-01-08 | 周度     |
| date          | 日期             | 计算日期                                                      | 2010-01-08 | 周度     |
| code          | 期货品种         | 期货品种                                                      | 2010-01-08 | 周度     |
| last_date     | 上期调仓日期     | 上一期调仓日期（期初日期）                                    | 2010-01-08 | 周度     |
| last_contract | 上期持仓合约     | 上一期持仓合约                                                | 2010-01-08 | 周度     |
| last_wt       | 上期持仓权重     | 上一期持仓合约的期初权重                                      | 2010-01-08 | 周度     |
| last_price    | 上期合约期初价格 | 上一期持仓合约的期初价格                                      | 2010-01-08 | 周度     |
| present_price | 上期合约即期价格 | 上一期持仓合约的期末价格                                      | 2010-01-08 | 周度     |
| contract_ret  | 合约收益         | 上一期持仓合约的实际收益                                      | 2010-01-08 | 周度     |
| contract_rc   | 合约收益贡献     | 上一期持仓合约对组合的收益贡献，持仓权重 * 持仓合约的实际收益 | 2010-01-08 | 周度     |
| ret           | 品种收益         | 考虑持仓期内展期时的实际收益（用主力合约计算的品种收益）      | 2010-01-08 | 周度     |
| rc            | 收益贡献         | 持仓品种对于组合的收益贡献，持仓权重 * 品种主力的实际收益     | 2010-01-08 | 周度     |
| contract      | 最新持仓合约     | 本期持仓合约                                                  | 2010-01-08 | 周度     |
| price         | 最新合约价格     | 本期持仓合约的期初价格                                        | 2010-01-08 | 周度     |
| wt            | 最新持仓权重     | 本期持仓合约/品种的权重                                       | 2010-01-08 | 周度     |

### csft_test_perf — 因子测试绩效表

调用函数：fino.get_csft_test_perf

样本外（out-of-sample）绩效汇总表，用于验证因子在未知数据上的表现稳定性。通常用于筛选具有持续预测能力、不过拟合的因子。

调取样例：

```python
fino.get_csft_test_perf(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段             | 字段名称                 | 指标说明                                                       | 起始时间   | 更新频度 |
| ---------------- | ------------------------ | -------------------------------------------------------------- | ---------- | -------- |
| factor           | 因子                     | 因子代码                                                       | 2024-08-02 | 周度     |
| date             | 日期                     | 计算日期                                                       | 2024-08-02 | 周度     |
| name             | 因子名                   | 因子名，同factor，一般为"因子类别_k数字"，其中数字即为因子参数 | 2024-08-02 | 周度     |
| factor_class     | 因子类别                 | 对应因子名name中的因子类别                                     | 2024-08-02 | 周度     |
| k                | 因子参数                 | 对应因子名name中的因子参数                                     | 2024-08-02 | 周度     |
| sample_range     | 样本起止                 | 测试样本的起始日期 ~ 截止日期                                  | 2024-08-02 | 周度     |
| sample_len       | 样本数量                 | 测试样本长度（期数）                                           | 2024-08-02 | 周度     |
| reg_rf_yret      | 回归-rf年化收益          | 回归纯因子收益的年化收益                                       | 2024-08-02 | 周度     |
| reg_rf_yvol      | 回归-rf年化波动          | 回归纯因子收益的年化波动                                       | 2024-08-02 | 周度     |
| reg_rf_sharp     | 回归-rf夏普比率          | 回归纯因子收益的夏普比率                                       | 2024-08-02 | 周度     |
| reg_rf_posprob   | 回归-rf为正概率          | 回归纯因子收益为正直的比例                                     | 2024-08-02 | 周度     |
| reg_rf_tv        | 回归-rf t值              | 回归纯因子收益显著性t值                                        | 2024-08-02 | 周度     |
| reg_r2_avg       | 回归-截面回归r2平均      | 各期截面回归的R2平均值                                         | 2024-08-02 | 周度     |
| reg_tv_avg       | 回归-截面回归t值平均     | 各期截面回归的显著性t值平均值                                  | 2024-08-02 | 周度     |
| reg_num_avg      | 回归-截面样本数平均      | 各期截面回归的样本量平均值                                     | 2024-08-02 | 周度     |
| ic_mean          | IC-均值                  | IC序列的均值                                                   | 2024-08-02 | 周度     |
| ic_std           | IC-标准差                | IC序列的标准差                                                 | 2024-08-02 | 周度     |
| ic_icir          | IC-信息比(ICIR)          | IC序列的信息比(ICIR)                                           | 2024-08-02 | 周度     |
| ic_posprob       | IC-大于0比例             | IC序列大于0的比例                                              | 2024-08-02 | 周度     |
| ic_tv            | IC-大于0显著性           | IC序列大于0的显著性                                            | 2024-08-02 | 周度     |
| ic_posprob_05    | IC-大于0.05比例          | IC序列大于0.05的比例                                           | 2024-08-02 | 周度     |
| ic_tv_05         | IC-大于0.05显著性        | IC序列大于0.05的显著性                                         | 2024-08-02 | 周度     |
| ic_absprob_05    | IC-绝对值大于0.05比例    | IC序列的绝对值大于0.05的比例                                   | 2024-08-02 | 周度     |
| grp_num          | 分组-分组数量            | 分组数量                                                       | 2024-08-02 | 周度     |
| grp_mono_avg     | 分组-单调性平均          | 每期各分组收益单调性的平均值                                   | 2024-08-02 | 周度     |
| grp_mono_posprob | 分组-单调性为正比例      | 每期各分组收益单调性为正的比例                                 | 2024-08-02 | 周度     |
| grp_mono_tv      | 分组-单调性的显著性      | 每期各分组收益单调性显著性t值                                  | 2024-08-02 | 周度     |
| grp_cumret_mono  | 分组-累计收益的单调性    | 累计各分组收益的单调性                                         | 2024-08-02 | 周度     |
| grp_g1g5_tv      | 分组-g1&g5收益差的显著性 | 第一组和第五组每期收益之间的差异显著性                         | 2024-08-02 | 周度     |
| grp_g2g4_tv      | 分组-g2&g4收益差的显著性 | 第二组和第四组每期收益之间的差异显著性                         | 2024-08-02 | 周度     |

### csft_test_data — 因子测试原始数据表

调用函数：fino.get_csft_test_data

存储样本外阶段（Out-of-sample）逐期的收益、波动率、IC 等详细指标。可用于复现测试结果、绘制性能曲线、分析因子失效区间。

调取样例：

```python
fino.get_csft_test_data(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段         | 字段名称          | 指标说明                     | 起始时间   | 更新频度 |
| ------------ | ----------------- | ---------------------------- | ---------- | -------- |
| factor       | 因子              | 因子代码                     | 2010-01-08 | 周度     |
| date         | 日期              | 计算日期                     | 2010-01-08 | 周度     |
| reg_rf       | 回归-rf           | 截面回归纯因子收益序列       | 2010-01-08 | 周度     |
| reg_pv       | 回归-截面回归pv   | 截面回归p值序列              | 2010-01-08 | 周度     |
| reg_tv       | 回归-截面回归tv   | 截面回归t值序列              | 2010-01-08 | 周度     |
| reg_r2       | 回归-截面回归r2   | 截面回归R2序列               | 2010-01-08 | 周度     |
| reg_num      | 回归-截面样本数   | 截面回归样本数量的序列       | 2010-01-08 | 周度     |
| reg_rf_cum   | 回归-累计rf       | 累计的截面回归纯因子收益序列 | 2010-01-08 | 周度     |
| ic_ic        | IC-IC值           | 各期IC值序列                 | 2010-01-08 | 周度     |
| ic_ma10      | IC_IC滚动10日平均 | IC 10日滚动平均序列          | 2010-03-19 | 周度     |
| ic_cum       | IC_累计IC         | 累计IC值序列                 | 2010-01-08 | 周度     |
| grp_mono     | 分组-单调性       | 各分组收益单调性序列         | 2010-01-08 | 周度     |
| grp_mono_cum | 分组-累计单调性   | 单调性序列的累计值           | 2010-01-08 | 周度     |
| grp_ret_g1   | 分组-g1收益       | 第一组收益                   | 2010-01-08 | 周度     |
| grp_ret_g2   | 分组-g2收益       | 第二组收益                   | 2010-01-08 | 周度     |
| grp_ret_g3   | 分组-g3收益       | 第三组收益                   | 2010-01-08 | 周度     |
| grp_ret_g4   | 分组-g4收益       | 第四组收益                   | 2010-01-08 | 周度     |
| grp_ret_g5   | 分组-g5收益       | 第五组收益                   | 2010-01-08 | 周度     |

### csft_test_dcp — 因子测试分组收益表

调用函数：fino.get_csft_test_dcp

对样本外阶段的因子分组收益进行分析。各组（如 Q1~Q5）按因子值升序或降序排列，用于检验因子在真实场景下的分层稳定性、超额收益可持续性等特征。

调取样例：

```python
fino.get_csft_test_dcp(start_date="20240602",end_date="20250130",factor=["T_overnight_k240"],)
```

| 字段        | 字段名称     | 指标说明                                          | 起始时间   | 更新频度 |
| ----------- | ------------ | ------------------------------------------------- | ---------- | -------- |
| factor      | 因子         | 因子代码                                          | 2009-12-31 | 周度     |
| date        | 日期         | 计算日期                                          | 2009-12-31 | 周度     |
| code        | 期货品种     | 期货品种                                          | 2009-12-31 | 周度     |
| grp_gp      | 分组组号     | 每个品种对应的分组编号                            | 2009-12-31 | 周度     |
| grp_wt      | 组内权重     | 每个品种对应的组内权重                            | 2009-12-31 | 周度     |
| grp_last_gp | 上期分组组号 | 上一期每个品种对应的分组编号                      | 2010-01-08 | 周度     |
| grp_last_wt | 上期组内权重 | 上一期每个品种对应的组内权重                      | 2010-01-08 | 周度     |
| grp_ret     | 分组品种收益 | 每个品种的实际收益                                | 2010-01-08 | 周度     |
| grp_rc      | 分组收益贡献 | 每个品种在各自组内的收益贡献，组内权重 * 品种收益 | 2010-01-08 | 周度     |

## **快速使用示例**

### python样例：

```python
import finosdk as fino
import pandas as pd

fino.init()

df = fino.get_fac_position(
    start_date="20250102",   
    end_date="20250130",   
    code_list=["JD"],
    factor=["Pr_netmom_k90"],
    section=["农产品"]
)

print(df)
```

### 返回样例：

```
                   date code       factor_k   k freq    value           updatetime
0   2025-01-02T00:00:00   JD  Pr_netmom_k90  90    D  10318.0  2025-01-02T18:49:57
1   2025-01-03T00:00:00   JD  Pr_netmom_k90  90    D   7349.0  2025-01-03T18:42:50
2   2025-01-06T00:00:00   JD  Pr_netmom_k90  90    D  15338.0  2025-01-06T19:05:00
3   2025-01-07T00:00:00   JD  Pr_netmom_k90  90    D  14250.0  2025-01-07T18:43:45
4   2025-01-08T00:00:00   JD  Pr_netmom_k90  90    D   8391.0  2025-01-08T18:43:53
5   2025-01-09T00:00:00   JD  Pr_netmom_k90  90    D   5397.0  2025-01-09T18:46:26
6   2025-01-10T00:00:00   JD  Pr_netmom_k90  90    D    840.0  2025-01-10T18:59:28
7   2025-01-13T00:00:00   JD  Pr_netmom_k90  90    D   2279.0  2025-01-13T18:40:28
8   2025-01-13T14:00:00   JD  Pr_netmom_k90  90    D   2279.0  2025-01-14T08:40:28
9   2025-01-14T00:00:00   JD  Pr_netmom_k90  90    D   6905.0  2025-01-14T18:40:43
10  2025-01-14T14:00:00   JD  Pr_netmom_k90  90    D   6905.0  2025-01-15T08:40:43
11  2025-01-15T00:00:00   JD  Pr_netmom_k90  90    D   3335.0  2025-01-15T18:41:28
12  2025-01-15T14:00:00   JD  Pr_netmom_k90  90    D   3335.0  2025-01-16T08:41:28
13  2025-01-16T00:00:00   JD  Pr_netmom_k90  90    D  -2153.0  2025-01-16T18:42:02
14  2025-01-16T14:00:00   JD  Pr_netmom_k90  90    D  -2153.0  2025-01-17T08:42:02
15  2025-01-17T00:00:00   JD  Pr_netmom_k90  90    D   2450.0  2025-01-17T18:41:56
16  2025-01-17T14:00:00   JD  Pr_netmom_k90  90    D   2450.0  2025-01-18T08:41:56
17  2025-01-20T00:00:00   JD  Pr_netmom_k90  90    D  -1055.0  2025-01-20T18:41:40
18  2025-01-20T14:00:00   JD  Pr_netmom_k90  90    D  -1055.0  2025-01-21T08:41:40
19  2025-01-21T00:00:00   JD  Pr_netmom_k90  90    D  -3451.0  2025-01-21T18:41:53
20  2025-01-21T14:00:00   JD  Pr_netmom_k90  90    D  -3451.0  2025-01-22T08:41:53
21  2025-01-22T00:00:00   JD  Pr_netmom_k90  90    D  -5176.0  2025-01-22T18:41:19
22  2025-01-22T14:00:00   JD  Pr_netmom_k90  90    D  -5176.0  2025-01-23T08:41:19
23  2025-01-23T00:00:00   JD  Pr_netmom_k90  90    D   1592.0  2025-01-23T18:40:56
24  2025-01-23T14:00:00   JD  Pr_netmom_k90  90    D   1592.0  2025-01-24T08:40:56
25  2025-01-24T00:00:00   JD  Pr_netmom_k90  90    D  -4845.0  2025-01-24T18:41:37
26  2025-01-24T14:00:00   JD  Pr_netmom_k90  90    D  -4845.0  2025-01-25T08:41:37
27  2025-01-27T00:00:00   JD  Pr_netmom_k90  90    D  -5873.0  2025-01-27T18:41:25
28  2025-01-27T14:00:00   JD  Pr_netmom_k90  90    D  -5873.0  2025-01-28T08:41:25
```

## 常见问题

| 问题                                           | 原因/解决                              |
| :--------------------------------------------- | -------------------------------------- |
| ModuleNotFoundError: No module named 'finosdk' | 没装好包，重新执行安装命令             |
| 401 Unauthorized                               | API key 无效，检查环境变量             |
| Remote end closed connection                   | 时间区间太大或服务器超时，缩短日期窗口 |

### 测试命令合集

```cmd
# 查看 SDK 版本
pip show finosdk-preview

# 更新到最新
pip install -U finosdk-preview -i https://pypi.org/simple

# 卸载重装
pip uninstall -y finosdk-preview
pip install finosdk-preview==0.0.1a3 -i https://pypi.org/simple

```
