.. _recorder:

====================================
Qlib记录器：实验管理系统
====================================
.. currentmodule:: qlib

简介
============
``Qlib`` 包含一个名为 ``QlibRecorder`` 的实验管理系统，旨在帮助用户高效处理实验并分析结果。

该系统包含三个组件：

- `ExperimentManager`
    管理实验的类。

- `Experiment`
    实验类，每个实例负责一个单独的实验。

- `Recorder`
    记录器类，每个实例负责单次运行记录。

以下是该系统结构的概览：

.. code-block::

    ExperimentManager
        - Experiment 1
            - Recorder 1
            - Recorder 2
            - ...
        - Experiment 2
            - Recorder 1
            - Recorder 2
            - ...
        - ...

This experiment management system defines a set of interface and provided a concrete implementation ``MLflowExpManager``, which is based on the machine learning platform: ``MLFlow`` (`link <https://mlflow.org/>`_).

If users set the implementation of ``ExpManager`` to be ``MLflowExpManager``, they can use the command `mlflow ui` to visualize and check the experiment results. For more information, please refer to the related documents `here <https://www.mlflow.org/docs/latest/cli.html#mlflow-ui>`_.

Qlib记录器
=============
``QlibRecorder`` provides a high level API for users to use the experiment management system. The interfaces are wrapped in the variable ``R`` in ``Qlib``, and users can directly use ``R`` to interact with the system. The following command shows how to import ``R`` in Python:

.. code-block:: Python

        from qlib.workflow import R

``QlibRecorder`` 提供了若干常用API用于管理工作流中的 `experiments` 和 `recorders`。更多可用API请参阅后续关于 `实验管理器`、`Experiment` 和 `Recorder` 的章节。

以下是 ``QlibRecorder`` 的可用接口：

.. autoclass:: qlib.workflow.__init__.QlibRecorder
    :members:

Experiment Manager
==================

``Qlib`` 中的 ``ExpManager`` 模块负责管理不同的实验。``ExpManager`` 的大部分 API 与 ``QlibRecorder`` 类似，其中最重要的 API 是 ``get_exp`` 方法。用户可以直接参考上述文档了解如何使用 ``get_exp`` 方法的详细信息。

.. autoclass:: qlib.workflow.expm.ExpManager
    :members: get_exp, list_experiments
    :noindex:

其他接口如 `create_exp`、`delete_exp` 的使用方法，请参阅 `实验管理器 API <../reference/api.html#experiment-manager>`_。

实验
==========

``Experiment`` 类专门负责单个实验，它将处理与实验相关的所有操作。包含诸如 `start`、`end` 等基础实验操作方法。此外，还提供了与 `recorders` 相关的方法：例如 `get_recorder` 和 `list_recorders`。

.. autoclass:: qlib.workflow.exp.Experiment
    :members: get_recorder, list_recorders
    :noindex:

其他接口如 `search_records`、`delete_recorder`，请参阅 `Experiment API <../reference/api.html#experiment>`_。

``Qlib`` 还提供了一个默认的 ``Experiment``，当用户使用 `log_metrics` 或 `get_exp` 等 API 时，会在特定情况下自动创建并使用该默认实验。若使用默认 ``Experiment``，运行 ``Qlib`` 时会有相关日志信息记录。用户可通过修改 ``Qlib`` 配置文件或在 ``Qlib`` 的 `initialization <../start/initialization.html#parameters>`_ 过程中更改默认实验名称，其默认值为 '`Experiment`'。

记录器
========

``Recorder`` 类负责单个记录器的管理。它将处理诸如 ``log_metrics``、``log_params`` 等单次运行的详细操作，旨在帮助用户轻松追踪运行期间产生的结果和内容。

以下是 ``QlibRecorder`` 中未包含的一些重要API：

.. autoclass:: qlib.workflow.recorder.Recorder
    :members: list_artifacts, list_metrics, list_params, list_tags
    :noindex:

对于其他接口如 `save_objects`、`load_object`，请参阅 `Recorder API <../reference/api.html#recorder>`_。

记录模板
===============

``RecordTemp`` 类是一个用于生成特定格式实验结果（如IC和回测）的类。我们提供了三种不同的`记录模板`类：

- ``SignalRecord``：该类生成模型的`预测`结果。
- ``SigAnaRecord``：该类生成模型的`IC`、`ICIR`、`Rank IC` 和 `Rank ICIR`。

以下是``SigAnaRecord``实现的简单示例，用户若想基于自己的预测和标签计算IC、Rank IC、多空收益，可参考此示例。

.. code-block:: Python

    from qlib.contrib.eva.alpha import calc_ic, calc_long_short_return

    ic, ric = calc_ic(pred.iloc[:, 0], label.iloc[:, 0])
    long_short_r, long_avg_r = calc_long_short_return(pred.iloc[:, 0], label.iloc[:, 0])

- ``PortAnaRecord``: This class generates the results of `backtest`. The detailed information about `backtest` as well as the available `strategy`, users can refer to `Strategy <../component/strategy.html>`_ and `Backtest <../component/backtest.html>`_.

以下是``PortAnaRecord``实现的简单示例，用户若想基于自己的预测和标签进行回测，可参考此示例。

.. code-block:: Python

    from qlib.contrib.strategy.strategy import TopkDropoutStrategy
    from qlib.contrib.evaluate import (
        backtest as normal_backtest,
        risk_analysis,
    )

    # backtest
    STRATEGY_CONFIG = {
        "topk": 50,
        "n_drop": 5,
    }
    BACKTEST_CONFIG = {
        "limit_threshold": 0.095,
        "account": 100000000,
        "benchmark": BENCHMARK,
        "deal_price": "close",
        "open_cost": 0.0005,
        "close_cost": 0.0015,
        "min_cost": 5,
    }

    strategy = TopkDropoutStrategy(**STRATEGY_CONFIG)
    report_normal, positions_normal = normal_backtest(pred_score, strategy=strategy, **BACKTEST_CONFIG)

    # analysis
    analysis = dict()
    analysis["excess_return_without_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"])
    analysis["excess_return_with_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"] - report_normal["cost"])
    analysis_df = pd.concat(analysis)  # type: pd.DataFrame
    print(analysis_df)

有关API的更多信息，请参阅 `Record Template API <../reference/api.html#module-qlib.workflow.record_temp>`_。



已知限制
=================
- Python对象基于pickle保存，当转储对象和加载对象的环境不同时可能会导致问题。