数据层：数据框架与使用

介绍

数据层 提供用户友好的 API 来管理和检索数据。它提供高性能的数据基础设施。

它是为量化投资设计的。例如，用户可以轻松地使用 数据层 构建公式化的阿尔法。有关更多详细信息，请参阅 构建公式化阿尔法。

数据层 的介绍包括以下部分。

• 数据准备

• 数据 API

• 数据加载器

• 数据处理程序

• 数据集

• 缓存

• 数据和缓存文件结构

以下是 Qlib 数据工作流的典型示例

• 用户下载数据并将数据转换为 Qlib 格式（文件名后缀为 .bin）。在此步骤中，通常仅将一些基本数据存储在磁盘上（例如 OHLCV）。

• 基于 Qlib 的表达引擎创建一些基本特征（例如 "Ref($close, 60) / $close"，返回过去 60 个交易日的收盘价）。表达引擎中支持的运算符可以在 这里 找到。此步骤通常在 Qlib 的 数据加载器 中实现，该组件是 数据处理器 的一部分。

• 如果用户需要更复杂的数据处理（例如数据归一化），数据处理器 支持用户自定义处理器来处理数据（一些预定义的处理器可以在 这里 找到）。处理器与表达引擎中的运算符不同。它是为一些复杂的数据处理方法设计的，这些方法在表达引擎中的运算符中难以支持。

• 最后，数据集 负责从数据处理器处理的数据中准备特定于模型的数据集。

数据准备

Qlib 格式数据

我们特别设计了一种数据结构来管理金融数据，详细信息请参阅 Qlib 论文中的 文件存储设计部分。此类数据将以文件名后缀 .bin 存储（我们称之为 .bin 文件，.bin 格式或 qlib 格式）。.bin 文件是为金融数据的科学计算而设计的。

Qlib 提供两种不同的现成数据集，可以通过此 链接 访问：

数据集	美国市场	中国市场
Alpha360	√	√
Alpha158	√	√

此外，Qlib 提供了高频数据集。用户可以通过这个 link 运行高频数据集示例。

Qlib 格式数据集

Qlib 提供了一个现成的 .bin 格式数据集，用户可以使用脚本 scripts/get_data.py 下载中国股票数据集，如下所示。用户还可以使用 numpy 加载 .bin 文件以验证数据。价格成交量数据与实际交易价格看起来不同，因为它们是 调整过的 (adjusted price)。然后你可能会发现调整后的价格可能来自不同的数据源而有所不同。这是因为不同的数据源在调整价格的方式上可能存在差异。Qlib 在调整价格时将每只股票的首个交易日的价格标准化为 1。用户可以利用 $factor 获取原始交易价格（例如，$close / $factor 获取原始收盘价）。

以下是关于 Qlib 价格调整的一些讨论。

• https://github.com/microsoft/qlib/issues/991#issuecomment-1075252402

# download 1d
python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn

# download 1min
python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/qlib_cn_1min --region cn --interval 1min

除了中国股票数据外，Qlib 还包括一个美国股票数据集，可以使用以下命令下载：

python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/us_data --region us

运行上述命令后，用户可以在 ~/.qlib/qlib_data/cn_data 目录和 ~/.qlib/qlib_data/us_data 目录中找到 Qlib 格式的中国股票和美国股票数据。

Qlib 还提供了 scripts/data_collector 中的脚本，帮助用户在互联网上抓取最新数据并将其转换为 qlib 格式。

当 Qlib 使用此数据集初始化时，用户可以使用它构建和评估自己的模型。有关更多详细信息，请参阅 初始化。

每日频率数据的自动更新

建议用户手动更新数据一次（--trading_date 2021-05-25），然后设置为自动更新。

有关更多信息，请参阅：yahoo collector

• 每个交易日自动更新数据到 "qlib" 目录（Linux）

  • 使用 crontab：crontab -e

  • 设置定时任务：

    * * * * 1-5 python <script path> update_data_to_bin --qlib_data_1d_dir <user data dir>
    

    • 脚本路径：scripts/data_collector/yahoo/collector.py

• 数据的手动更新

  python scripts/data_collector/yahoo/collector.py update_data_to_bin --qlib_data_1d_dir <user data dir> --trading_date <start date> --end_date <end date>
  

  • trading_date：交易日开始

  • end_date：交易日结束（不包括）

将CSV格式转换为Qlib格式

Qlib``提供了脚本``scripts/dump_bin.py，可以将**任何**CSV格式的数据转换为`.bin`文件（``Qlib``格式），只要它们符合正确的格式。

除了下载准备好的演示数据外，用户还可以直接从Collector下载演示数据，以供参考CSV格式。以下是一些示例：

每日数据：

python scripts/get_data.py download_data --file_name csv_data_cn.zip --target_dir ~/.qlib/csv_data/cn_data

1分钟数据：

python scripts/data_collector/yahoo/collector.py download_data --source_dir ~/.qlib/stock_data/source/cn_1min --region CN --start 2021-05-20 --end 2021-05-23 --delay 0.1 --interval 1min --limit_nums 10

用户还可以提供自己的CSV格式数据。然而，CSV数据**必须满足**以下标准：

• CSV文件以特定股票命名*或*CSV文件包含一列股票名称

  • 将CSV文件命名为股票：SH600000.csv，`AAPL.csv`（不区分大小写）。

  • CSV文件包含一列股票名称。用户**必须**在导出数据时指定列名。以下是一个示例：

    python scripts/dump_bin.py dump_all ... --symbol_field_name symbol
    

    数据格式如下：

    symbol	close
    SH600000	120

• CSV文件**必须**包含日期列，并且在导出数据时，用户必须指定日期列名。以下是一个示例：

  python scripts/dump_bin.py dump_all ... --date_field_name date
  

  数据格式如下：

  symbol	date	close	open	volume
  SH600000	2020-11-01	120	121	12300000
  SH600000	2020-11-02	123	120	12300000

假设用户在目录 ~/.qlib/csv_data/my_data 中准备了他们的CSV格式数据，他们可以运行以下命令来开始转换。

python scripts/dump_bin.py dump_all --csv_path  ~/.qlib/csv_data/my_data --qlib_dir ~/.qlib/qlib_data/my_data --include_fields open,close,high,low,volume,factor

有关将数据导出到 .bin 文件时支持的其他参数，用户可以通过运行以下命令参考相关信息：

python dump_bin.py dump_all --help

转换后，用户可以在目录 ~/.qlib/qlib_data/my_data 中找到他们的Qlib格式数据。

备注

--include_fields 的参数应与CSV文件的列名对应。Qlib 提供的数据集的列名应至少包括开盘价、收盘价、最高价、最低价、成交量和因子。

• open

  调整后的开盘价

• close

  调整后的收盘价

• high

  调整后的最高价

• low

  调整后的最低价

• volume

  调整后的交易量

• factor

  恢复因子。通常，factor = adjusted_price / original_price，调整后的价格 参考：拆分调整

在 Qlib 数据处理的约定中，如果股票暂停交易，open, close, high, low, volume, money 和 factor 将被设置为NaN。如果您想使用自己的无法通过OCHLV计算的alpha因子，例如PE、EPS等，您可以将其与OHCLV一起添加到CSV文件中，然后导出为Qlib格式数据。

股票池（市场）

Qlib 定义 股票池 为股票列表及其日期范围。预定义的股票池（例如 csi300）可以如下导入。

python collector.py --index_name CSI300 --qlib_dir <user qlib data dir> --method parse_instruments

多种股票模式

Qlib 现在为用户提供两种不同的股票模式：中国股票模式和美国股票模式。以下是这两种模式的一些不同设置：

地区	交易单位	限制阈值
中国	100	0.099
美国	1	无

交易单位 定义了在交易中可以使用的股票数量，限制阈值 定义了股票涨跌幅度的百分比界限。

• 如果用户在中国股票模式下使用 Qlib，则需要中国股票数据。用户可以按照以下步骤在中国股票模式下使用 Qlib：

  • 下载 qlib 格式的中国股票数据，请参考 Qlib 格式数据集 部分。

  • 在中国股票模式下初始化 Qlib

    假设用户将其 Qlib 格式数据下载到目录 ~/.qlib/qlib_data/cn_data。用户只需按如下方式初始化 Qlib。

    from qlib.constant import REG_CN
    qlib.init(provider_uri='~/.qlib/qlib_data/cn_data', region=REG_CN)
    

• 如果用户在美国股票模式下使用 Qlib，则需要美国股票数据。Qlib 还提供了一个脚本来下载美国股票数据。用户可以按照以下步骤在美国股票模式下使用 Qlib：

  • 下载 qlib 格式的美国股票数据，请参考 Qlib 格式数据集 部分。

  • 在美国股票模式下初始化 Qlib

    假设用户在目录 ~/.qlib/qlib_data/us_data 中准备了他们的 Qlib 格式数据。用户只需按如下方式初始化 Qlib。

    from qlib.config import REG_US
    qlib.init(provider_uri='~/.qlib/qlib_data/us_data', region=REG_US)
    

备注

欢迎提交新的数据源的 PR！用户可以将爬取数据的代码提交为 PR，类似于 这里的示例。然后我们将使用这些代码在我们的服务器上创建数据缓存，其他用户可以直接使用。

数据 API

数据检索

用户可以使用 qlib.data 中的 API 来检索数据，请参考 数据检索。

特征

Qlib 提供 Feature 和 ExpressionOps 以根据用户的需求提取特征。

• Feature

  从数据提供者加载数据。用户可以获取特征，如 $high、$low、$open、$close 等，这些特征应与 --include_fields 的参数相对应，请参考 将 CSV 格式转换为 Qlib 格式。

• ExpressionOps

  ExpressionOps 将使用运算符进行特征构建。要了解更多关于 Operator 的信息，请参考 Operator API。此外，Qlib 支持用户定义自己的自定义 Operator，示例已在 tests/test_register_ops.py 中给出。

要了解更多关于 Feature 的信息，请参考 Feature API。

过滤器

Qlib 提供 NameDFilter 和 ExpressionDFilter 以根据用户的需求过滤工具。

• NameDFilter

  名称动态工具过滤器。根据规定的名称格式过滤工具。需要一个名称规则的正则表达式。

• ExpressionDFilter

  表达式动态工具过滤器。根据特定表达式过滤工具。需要一个指示特定特征字段的表达式规则。

  • 基本特征过滤器: rule_expression = '$close/$open>5'

  • 横截面特征过滤器 : rule_expression = '$rank($close)<10'

  • 时间序列特征过滤器: rule_expression = '$Ref($close, 3)>100'

这是一个简单的示例，展示了如何在基本的 Qlib 工作流配置文件中使用过滤器：

filter: &filter
    filter_type: ExpressionDFilter
    rule_expression: "Ref($close, -2) / Ref($close, -1) > 1"
    filter_start_time: 2010-01-01
    filter_end_time: 2010-01-07
    keep: False

data_handler_config: &data_handler_config
    start_time: 2010-01-01
    end_time: 2021-01-22
    fit_start_time: 2010-01-01
    fit_end_time: 2015-12-31
    instruments: *market
    filter_pipe: [*filter]

要了解更多关于 Filter 的信息，请参考 Filter API。

参考

要了解更多关于 Data API 的信息，请参考 Data API。

数据加载器

Data Loader 在 Qlib 中旨在从原始数据源加载原始数据。它将在 Data Handler 模块中加载和使用。

QlibDataLoader

QlibDataLoader 类在 Qlib 中是一个接口，允许用户从 Qlib 数据源加载原始数据。

StaticDataLoader

StaticDataLoader 类在 Qlib 中是一个接口，允许用户从文件或提供的方式加载原始数据。

接口

以下是 QlibDataLoader 类的一些接口：

class qlib.data.dataset.loader.DataLoader

DataLoader 旨在从原始数据源加载原始数据。

abstract load(instruments, start_time=None, end_time=None) → DataFrame

将数据加载为 pd.DataFrame。

数据示例（列的多重索引是可选的）：

                        feature                                                             label
                        $close     $volume     Ref($close, 1)  Mean($close, 3)  $high-$low  LABEL0
datetime    instrument
2010-01-04  SH600000    81.807068  17145150.0       83.737389        83.016739    2.741058  0.0032
            SH600004    13.313329  11800983.0       13.313329        13.317701    0.183632  0.0042
            SH600005    37.796539  12231662.0       38.258602        37.919757    0.970325  0.0289

参数:

• instruments (str or dict) -- 它可以是市场名称或由InstrumentProvider生成的工具配置文件。如果工具的值为None，则表示没有进行过滤。

• start_time (str) -- 时间范围的开始。

• end_time (str) -- 时间范围的结束。

返回:

从底层源加载数据

返回类型:

pd.DataFrame

抛出:

KeyError: -- 如果不支持工具过滤，则引发KeyError

API

要了解更多关于 Data Loader 的信息，请参考 Data Loader API。

数据处理程序

Data Handler 模块在 Qlib 中旨在处理大多数模型将使用的常见数据处理方法。

用户可以通过 qrun 在自动工作流中使用 Data Handler，有关更多详细信息，请参考 Workflow: Workflow Management。

DataHandlerLP

除了在与 qrun 的自动工作流中使用 Data Handler，Data Handler 还可以作为一个独立模块使用，用户可以轻松地预处理数据（标准化、去除 NaN 等）并构建数据集。

为了实现这一点，Qlib 提供了一个基类 qlib.data.dataset.DataHandlerLP。这个类的核心思想是：我们将有一些可学习的 Processors，它们可以学习数据处理的参数（例如，zscore 标准化的参数）。当新数据到来时，这些 trained Processors 可以处理新数据，从而以高效的方式处理实时数据成为可能。关于 Processors 的更多信息将在下一小节中列出。

接口

以下是 DataHandlerLP 提供的一些重要接口：

class qlib.data.dataset.handler.DataHandlerLP(instruments=None, start_time=None, end_time=None, data_loader: dict | str | DataLoader | None = None, infer_processors: List = [], learn_processors: List = [], shared_processors: List = [], process_type='append', drop_raw=False, **kwargs)

带有 (L)可学习 (P)处理器 的数据处理器

此处理器将生成三份以 pd.DataFrame 格式的数据。

• DK_R / self._data: 从加载器加载的原始数据

• DK_I / self._infer: 处理用于推理的数据

• DK_L / self._learn: 处理用于学习模型的数据。

使用不同处理器工作流进行学习和推理的动机，以下是一些示例。

• 用于学习和推理的工具宇宙可能不同。

• 某些样本的处理可能依赖于标签（例如，一些样本达到限制可能需要额外处理或被丢弃）。

  • 这些处理器仅适用于学习阶段。

数据处理器的提示

• 减少内存成本

  • drop_raw=True：这将直接修改原始数据中的数据；

• 请注意，处理过的数据如 self._infer 或 self._learn 与 Qlib 的 Dataset 中的 segments 概念不同，如 "train" 和 "test"。

  • 处理过的数据如 self._infer 或 self._learn 是经过不同处理器处理的基础数据。

  • Qlib 的 Dataset 中的 segments 如 "train" 和 "test" 只是查询数据时的时间分段（"train" 通常在时间序列中位于 "test" 之前）。

  • 例如，您可以查询在 "train" 时间分段中由 infer_processors 处理的 data._infer。

__init__(instruments=None, start_time=None, end_time=None, data_loader: dict | str | DataLoader | None = None, infer_processors: List = [], learn_processors: List = [], shared_processors: List = [], process_type='append', drop_raw=False, **kwargs)

参数:

• infer_processors (list) --

  • 生成推断数据的处理器的 <描述信息> 列表

  • <描述信息> 的示例：

  1) classname & kwargs:
      {
          "class": "MinMaxNorm",
          "kwargs": {
              "fit_start_time": "20080101",
              "fit_end_time": "20121231"
          }
      }
  2) Only classname:
      "DropnaFeature"
  3) object instance of Processor
  

• learn_processors (list) -- 类似于 infer_processors，但用于生成学习模型的数据

• process_type (str) -- PTYPE_I = '独立' - self._infer 将由 infer_processors 处理 - self._learn 将由 learn_processors 处理 PTYPE_A = '附加' - self._infer 将由 infer_processors 处理 - self._learn 将由 infer_processors + learn_processors 处理 - (例如 self._infer 由 learn_processors 处理 )

• drop_raw (bool) -- 是否丢弃原始数据

fit()

拟合数据而不处理数据

fit_process_data()

拟合和处理数据

fit 的输入将是前一个处理器的输出

process_data(with_fit: bool = False)

处理数据。如果必要，调用 processor.fit

符号： (data) [processor]

# 当 self.process_type == DataHandlerLP.PTYPE_I 时的数据处理流程

(self._data)-[shared_processors]-(_shared_df)-[learn_processors]-(_learn_df)
                                       \
                                        -[infer_processors]-(_infer_df)

# 当 self.process_type == DataHandlerLP.PTYPE_A 时的数据处理流程

(self._data)-[shared_processors]-(_shared_df)-[infer_processors]-(_infer_df)-[learn_processors]-(_learn_df)

参数:

with_fit (bool) -- fit 的输入将是前一个处理器的输出

config(processor_kwargs: dict | None = None, **kwargs)

数据的配置。# 从数据源加载哪些数据

当从数据集加载序列化处理程序时，将使用此方法。数据将使用不同的时间范围进行初始化。

setup_data(init_type: str = 'fit_seq', **kwargs)

设置数据以便在多次运行初始化时使用

参数:

• init_type (str) -- 上述列出的类型 IT_*。

• enable_cache (bool) -- 默认值为 false： - 如果 enable_cache == True：处理后的数据将保存在磁盘上，处理程序将在下次调用 init 时直接从磁盘加载缓存的数据

fetch(selector: Timestamp | slice | str = slice(None, None, None), level: str | int = 'datetime', col_set='__all', data_key: Literal['raw', 'infer', 'learn'] = 'infer', squeeze: bool = False, proc_func: Callable | None = None) → DataFrame

从底层数据源获取数据

参数:

• selector (Union[pd.Timestamp, slice, str]) -- 描述如何通过索引选择数据。

• level (Union[str, int]) -- 选择数据的索引级别。

• col_set (str) -- 选择一组有意义的列。（例如：特征，列）。

• data_key (str) -- 要获取的数据： DK_*。

• proc_func (Callable) -- 请参考 DataHandler.fetch 的文档

返回类型:

pd.DataFrame

get_cols(col_set='__all', data_key: Literal['raw', 'infer', 'learn'] = 'infer') → list

获取列名

参数:

• col_set (str) -- 选择一组有意义的列。（例如：特征，列）。

• data_key (DATA_KEY_TYPE) -- 要获取的数据： DK_*。

返回:

列名列表

返回类型:

list

classmethod cast(handler: DataHandlerLP) → DataHandlerLP

动机

• 用户在他自定义的包中创建一个数据处理器。然后他想将处理后的处理器分享给其他用户，而不引入包依赖和复杂的数据处理逻辑。

• 这个类通过将类转换为 DataHandlerLP 并仅保留处理后的数据，使其成为可能

参数:

handler (DataHandlerLP) -- DataHandlerLP 的子类

返回:

转换后的处理数据

返回类型:

DataHandlerLP

classmethod from_df(df: DataFrame) → DataHandlerLP

动机： - 当用户想要快速获取数据处理器时。

创建的数据处理器将只有一个共享的 Dataframe，没有处理器。在创建处理器后，用户可能经常想要转储处理器以便重用。这是一个典型的用例

from qlib.data.dataset import DataHandlerLP
dh = DataHandlerLP.from_df(df)
dh.to_pickle(fname, dump_all=True)

TODO: - StaticDataLoader速度较慢。它不需要再次复制数据...

如果用户想通过配置加载特征和标签，可以定义一个新的处理程序并调用 qlib.contrib.data.handler.Alpha158 的静态方法 parse_config_to_fields。

此外，用户可以传递 qlib.contrib.data.processor.ConfigSectionProcessor，该处理器提供了一些由配置定义的特征的预处理方法，以便于新的处理程序。

处理器

Processor 模块在 Qlib 中设计为可学习的，负责处理数据处理，例如 归一化 和 删除无效/nan 特征/标签。

Qlib 提供以下 Processors：

• DropnaProcessor：处理器，用于删除 N/A 特征。

• DropnaLabel：处理器，用于删除 N/A 标签。

• TanhProcess：处理器，使用 tanh 处理噪声数据。

• ProcessInf：处理器，处理无穷值，将其替换为列的均值。

• Fillna：处理器，处理 N/A 值，将 N/A 值填充为 0 或其他给定数字。

• MinMaxNorm：处理器，应用最小-最大归一化。

• ZscoreNorm：处理器，应用 z-score 归一化。

• RobustZScoreNorm：处理器，应用稳健 z-score 归一化。

• CSZScoreNorm：处理器，应用横截面 z-score 归一化。

• CSRankNorm：处理器，应用横截面排名归一化。

• CSZFillna：处理器，以横截面方式填充 N/A 值，使用列的均值。

用户还可以通过继承 Processor 的基类创建自己的 处理器。有关更多信息，请参阅所有处理器的实现 (Processor Link)。

要了解更多关于 Processor 的信息，请参阅 Processor API。

示例

Data Handler 可以通过修改配置文件与 qrun 一起运行，也可以作为单独的模块使用。

要了解如何使用 qrun 运行 Data Handler，请参阅 Workflow: Workflow Management。

Qlib 提供实现的数据处理器 Alpha158。以下示例展示了如何将 Alpha158 作为单独模块运行。

备注

用户需要首先使用 qlib.init 初始化 Qlib，请参考 初始化.

import qlib
from qlib.contrib.data.handler import Alpha158

data_handler_config = {
    "start_time": "2008-01-01",
    "end_time": "2020-08-01",
    "fit_start_time": "2008-01-01",
    "fit_end_time": "2014-12-31",
    "instruments": "csi300",
}

if __name__ == "__main__":
    qlib.init()
    h = Alpha158(**data_handler_config)

    # get all the columns of the data
    print(h.get_cols())

    # fetch all the labels
    print(h.fetch(col_set="label"))

    # fetch all the features
    print(h.fetch(col_set="feature"))

备注

在 Alpha158 中，Qlib 使用标签 Ref($close, -2)/Ref($close, -1) - 1，这意味着从 T+1 到 T+2 的变化，而不是 Ref($close, -1)/$close - 1，原因是当获取中国股票的 T 日收盘价时，股票可以在 T+1 日购买并在 T+2 日出售。

API

要了解更多关于 数据处理器 的信息，请参考 数据处理器 API.

数据集

Qlib 中的 Dataset 模块旨在为模型训练和推理准备数据。

该模块的动机是我们希望最大化不同模型处理适合自身的数据的灵活性。此模块为模型提供了以独特方式处理其数据的灵活性。例如，像 GBDT 这样的模型可能在包含 nan 或 None 值的数据上表现良好，而像 MLP 这样的神经网络在此类数据上会崩溃。

如果用户的模型需要以不同方式处理其数据，用户可以实现自己的 Dataset 类。如果模型的数据处理没有特殊要求，可以直接使用 DatasetH。

DatasetH 类是带有 数据处理器 的 dataset。这是该类最重要的接口：

class qlib.data.dataset.__init__.DatasetH(handler: Dict | DataHandler, segments: Dict[str, Tuple], fetch_kwargs: Dict = {}, **kwargs)

带有数据(H)处理器的数据集

用户应尝试将数据预处理函数放入处理器中。仅以下数据处理函数应放置在数据集中：

• 处理与特定模型相关。

• 处理与数据拆分相关。

__init__(handler: Dict | DataHandler, segments: Dict[str, Tuple], fetch_kwargs: Dict = {}, **kwargs)

设置基础数据。

参数:

• handler (Union[dict, DataHandler]) -- 处理器可以是： - DataHandler 的实例 - DataHandler 的配置。请参考 DataHandler

• segments (dict) -- 描述分割数据的选项。以下是一些示例： .. code-block:: 1) 'segments': { 'train': ("2008-01-01", "2014-12-31"), 'valid': ("2017-01-01", "2020-08-01",), 'test': ("2015-01-01", "2016-12-31",), } 2) 'segments': { 'insample': ("2008-01-01", "2014-12-31"), 'outsample': ("2017-01-01", "2020-08-01",), }

config(handler_kwargs: dict | None = None, **kwargs)

初始化 DatasetH

参数:

• handler_kwargs (dict) -- DataHandler 的配置，可以包括以下参数： - DataHandler.conf_data 的参数，例如 'instruments'、'start_time' 和 'end_time'。

• kwargs (dict) -- DatasetH的配置，例如 - segments : dict segments的配置与self.__init__中的'segments'相同。

setup_data(handler_kwargs: dict | None = None, **kwargs)

设置数据

参数:

handler_kwargs (dict) -- 初始化 DataHandler 的参数，可能包括以下参数： - init_type : 处理程序的初始化类型 - enable_cache : 是否启用缓存

prepare(segments: List[str] | Tuple[str] | str | slice | Index, col_set='__all', data_key='infer', **kwargs) → List[DataFrame] | DataFrame

为学习和推理准备数据。

参数:

• segments (Union[List[Text], Tuple[Text], Text, slice]) -- 描述要准备的数据的范围，以下是一些示例： - 'train' - ['train', 'valid']

• col_set (str) -- col_set将在获取数据时传递给self.handler。TODO：使其自动化： - 选择DK_I作为测试数据 - 选择DK_L作为训练数据。

• data_key (str) -- 要获取的数据： DK_* 默认值为 DK_I，表示获取 推理 的数据。

• kwargs -- kwargs 可能包含的参数： flt_col : str 仅在 TSDatasetH 中存在，可用于添加一列数据（True 或 False）以过滤数据。 该参数仅在它是 TSDatasetH 的实例时受支持。

返回类型:

Union[List[pd.DataFrame], pd.DataFrame]

抛出:

NotImplementedError: --

API

要了解更多关于 Dataset 的信息，请参考 Dataset API.

缓存

Cache 是一个可选模块，通过将一些常用数据保存为缓存文件来加速数据提供。Qlib 提供了一个 Memcache 类来在内存中缓存最常用的数据，一个可继承的 ExpressionCache 类，以及一个可继承的 DatasetCache 类。

全局内存缓存

Memcache 是一个全局内存缓存机制，由三个 MemCacheUnit 实例组成，用于缓存 日历、工具 和 特征。MemCache 在 cache.py 中全局定义为 H。用户可以使用 H['c'], H['i'], H['f'] 来获取/设置 memcache。

class qlib.data.cache.MemCacheUnit(*args, **kwargs)

内存缓存单元。

__init__(*args, **kwargs)

property limited

内存缓存是否有限

class qlib.data.cache.MemCache(mem_cache_size_limit=None, limit_type='length')

内存缓存。

__init__(mem_cache_size_limit=None, limit_type='length')

参数:

• mem_cache_size_limit -- 缓存最大大小。

• limit_type -- 长度或大小；长度（调用函数：len），大小（调用函数：sys.getsizeof）。

ExpressionCache

ExpressionCache 是一个缓存机制，用于保存诸如 Mean($close, 5) 的表达式。用户可以继承此基类，以根据以下步骤定义自己的缓存机制，保存表达式。

• 重写 self._uri 方法以定义缓存文件路径的生成方式。

• 重写 self._expression 方法以定义将缓存哪些数据以及如何缓存它。

以下显示了接口的详细信息：

class qlib.data.cache.ExpressionCache(provider)

表达式缓存机制基类。

此类用于包装具有自定义表达式缓存机制的表达式提供者。

备注

重写 _uri 和 _expression 方法以创建您自己的表达式缓存机制。

expression(instrument, field, start_time, end_time, freq)

获取表达式数据。

备注

与表达式提供者中的 expression 方法相同的接口

update(cache_uri: str | Path, freq: str = 'day')

将表达式缓存更新为最新日历。

重写此方法以定义如何根据用户自己的缓存机制更新表达式缓存。

参数:

• cache_uri (str or Path) -- 表达式缓存文件的完整 URI（包括目录路径）。

• freq (str)

返回:

0（成功更新）/ 1（无需更新）/ 2（更新失败）。

返回类型:

int

Qlib 当前提供了实现的磁盘缓存 DiskExpressionCache，该类继承自 ExpressionCache。表达式数据将存储在磁盘中。

DatasetCache

DatasetCache 是一个缓存机制，用于保存数据集。某个数据集由股票池配置（或一系列工具，尽管不推荐）、表达式列表或静态特征字段、收集特征的开始时间和结束时间以及频率来规范。用户可以继承此基类，以根据以下步骤定义自己的缓存机制，保存数据集。

• 重写 self._uri 方法以定义其缓存文件路径的生成方式。

• 重写 self._expression 方法以定义将缓存哪些数据以及如何缓存它。

以下显示了接口的详细信息：

class qlib.data.cache.DatasetCache(provider)

数据集缓存机制基类。

此类用于包装具有自定义数据集缓存机制的数据集提供者。

备注

重写 _uri 和 _dataset 方法以创建您自己的数据集缓存机制。

dataset(instruments, fields, start_time=None, end_time=None, freq='day', disk_cache=1, inst_processors=[])

获取特征数据集。

备注

与数据集提供者中的 dataset 方法相同的接口

备注

服务器使用 redis_lock 确保不会触发读写冲突，但客户端读取者不被考虑。

update(cache_uri: str | Path, freq: str = 'day')

将数据集缓存更新为最新日历。

重写此方法以定义如何根据用户自己的缓存机制更新数据集缓存。

参数:

• cache_uri (str or Path) -- 数据集缓存文件的完整 URI（包括目录路径）。

• freq (str)

返回:

0（成功更新）/ 1（无需更新）/ 2（更新失败）

返回类型:

int

static cache_to_origin_data(data, fields)

缓存数据到原始数据

参数:

• data -- pd.DataFrame，缓存数据。

• fields -- 特征字段。

返回:

pd.DataFrame。

static normalize_uri_args(instruments, fields, freq)

规范化 URI 参数

Qlib 目前提供了实现的磁盘缓存 DiskDatasetCache，该缓存继承自 DatasetCache。数据集的数据将存储在磁盘上。

数据和缓存文件结构

我们特别设计了一种文件结构来管理数据和缓存，请参阅 Qlib 论文中的 文件存储设计部分 以获取详细信息。数据和缓存的文件结构如下所示。

- data/
    [raw data] updated by data providers
    - calendars/
        - day.txt
    - instruments/
        - all.txt
        - csi500.txt
        - ...
    - features/
        - sh600000/
            - open.day.bin
            - close.day.bin
            - ...
        - ...
    [cached data] updated when raw data is updated
    - calculated features/
        - sh600000/
            - [hash(instrtument, field_expression, freq)]
                - all-time expression -cache data file
                - .meta : an assorted meta file recording the instrument name, field name, freq, and visit times
        - ...
    - cache/
        - [hash(stockpool_config, field_expression_list, freq)]
            - all-time Dataset-cache data file
            - .meta : an assorted meta file recording the stockpool config, field names and visit times
            - .index : an assorted index file recording the line index of all calendars
        - ...