.. _initialization:

===================
Qlib初始化
===================

.. currentmodule:: qlib


初始化
==============

请按照以下步骤初始化 ``Qlib``。

下载并准备数据：执行以下命令下载股票数据。请注意，这些数据是从 `Yahoo Finance <https://finance.yahoo.com/lookup>`_ 收集的，数据可能并不完美。如果用户拥有高质量数据集，我们建议用户准备自己的数据。关于自定义数据集的更多信息，请参阅 `Data <../component/data.html#converting-csv-format-into-qlib-format>`_。

    .. code-block:: bash

        python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn

关于 `get_data.py` 的更多信息，请参阅 `Data Preparation <../component/data.html#data-preparation>`_，


在调用其他API前需先初始化Qlib：在Python中运行以下代码。

    .. code-block:: Python

        import qlib
        # region in [REG_CN, REG_US]
        from qlib.constant import REG_CN
        provider_uri = "~/.qlib/qlib_data/cn_data"  # target_dir
        qlib.init(provider_uri=provider_uri, region=REG_CN)

.. note::
   不要在 ``Qlib`` 的仓库目录中导入qlib包，否则可能会报错。

参数
-------------------

除了 `provider_uri` 和 `region` 外，`qlib.init` 还有其他参数。
以下是 `qlib.init` 的几个重要参数（`Qlib` 有许多配置，此处仅列出部分参数。更详细的设置可查看 `此处 <https://github.com/microsoft/qlib/blob/main/qlib/config.py>`_）：

- `provider_uri`
    类型：str。Qlib数据的URI。例如，可以是 ``get_data.py`` 加载的数据存储位置。
- `region`
    类型：str，可选参数（默认值：`qlib.constant.REG_CN`）。
        当前支持：``qlib.constant.REG_US`` ('us') 和 ``qlib.constant.REG_CN`` ('cn')。不同的 `region` 值会导致不同的股票市场模式。
        - ``qlib.constant.REG_US``：美国股票市场。
        - ``qlib.constant.REG_CN``：中国股票市场。

        不同模式会导致不同的交易限制和成本。
        该区域仅是 `定义一批配置的快捷方式 <https://github.com/microsoft/qlib/blob/528f74af099bf6156e9480bcd2bb28e453231212/qlib/config.py#L249>`_，包括最小交易单位（``trade_unit``）、交易限制（``limit_threshold``）等。它不是必需部分，如果现有区域设置无法满足需求，用户可以手动设置关键配置。
- `redis_host`
    类型：str，可选参数（默认值："127.0.0.1"），`redis`的主机地址
        锁和缓存机制依赖于redis。
- `redis_port`
    类型：int，可选参数（默认值：6379），`redis`的端口号

    .. note::

        `region` 的值应与 `provider_uri` 中存储的数据一致。当前 ``scripts/get_data.py`` 仅提供中国股票市场数据。如果用户想使用美国股票市场数据，需自行准备美股数据到 `provider_uri` 并切换到美股模式。

    .. note::

        如果Qlib无法通过 `redis_host` 和 `redis_port` 连接redis，将不会使用缓存机制！详情请参阅 `缓存 <../component/data.html#cache>`_。
- `exp_manager`
    类型：dict，可选参数，用于指定qlib中使用的 `实验管理器` 设置。用户可以指定实验管理器类，以及所有实验的跟踪URI。但请注意，`exp_manager` 仅支持以下风格的字典输入。关于 `exp_manager` 的更多信息，用户可参考 `记录器：实验管理 <../component/recorder.html>`_。

    .. code-block:: Python

        # For example, if you want to set your tracking_uri to a <specific folder>, you can initialize qlib below
        qlib.init(provider_uri=provider_uri, region=REG_CN, exp_manager= {
            "class": "MLflowExpManager",
            "module_path": "qlib.workflow.expm",
            "kwargs": {
                "uri": "python_execution_path/mlruns",
                "default_exp_name": "Experiment",
            }
        })
- `mongo`
    类型：dict，可选参数，`MongoDB <https://www.mongodb.com/>`_ 的设置，将用于 `任务管理 <../advanced/task_management.html>`_ 等需要高性能和集群处理的功能。
    用户需先按照 `安装指南 <https://www.mongodb.com/try/download/community>`_ 安装MongoDB，然后通过URI访问。
    用户可通过设置 "task_url" 为类似 `"mongodb://%s:%s@%s" % (user, pwd, host + ":" + port)` 的字符串来使用凭证访问mongodb。

    .. code-block:: Python

        # For example, you can initialize qlib below
        qlib.init(provider_uri=provider_uri, region=REG_CN, mongo={
            "task_url": "mongodb://localhost:27017/",  # your mongo url
            "task_db_name": "rolling_db", # the database name of Task Management
        })

- `logging_level`
    系统日志级别。

- `kernels`
    Qlib表达式引擎计算特征时使用的进程数。在调试表达式计算异常时，将其设置为1会非常有帮助