.. _loading_other_datasets:

加载其他数据集
================

.. currentmodule:: sklearn.datasets

.. _sample_images:

示例图像
---------

Scikit-learn 还嵌入了一些由作者以 Creative Commons 许可证发布的示例 JPEG 图像。这些图像对于在二维数据上测试算法和流水线非常有用。

.. autosummary::

   load_sample_images
   load_sample_image

.. image:: ../auto_examples/cluster/images/sphx_glr_plot_color_quantization_001.png
   :target: ../auto_examples/cluster/plot_color_quantization.html
   :scale: 30
   :align: right


.. warning::

  图像的默认编码基于 ``uint8`` dtype，以节省内存。通常，机器学习算法在输入首先转换为浮点表示时效果最佳。此外，如果您计划使用 ``matplotlib.pyplot.imshow`` ，请不要忘记将范围缩放到 0 - 1，如下例所示。

.. rubric:: 示例

* :ref:`sphx_glr_auto_examples_cluster_plot_color_quantization.py` 

.. _libsvm_loader:

svmlight / libsvm 格式的数据集
--------------------------------

scikit-learn 包含用于加载 svmlight / libsvm 格式数据集的实用函数。在这种格式中，每一行采用 ``<label> <feature-id>:<feature-value> <feature-id>:<feature-value> ...`` 的形式。这种格式特别适合稀疏数据集。在这个模块中， ``X`` 使用 scipy 稀疏 CSR 矩阵， ``y`` 使用 numpy 数组。

您可以如下加载数据集::

  >>> from sklearn.datasets import load_svmlight_file
  >>> X_train, y_train = load_svmlight_file("/path/to/train_dataset.txt")
  ...                                                         # doctest: +SKIP

您也可以一次加载两个（或更多）数据集::

  >>> X_train, y_train, X_test, y_test = load_svmlight_files(
  ...     ("/path/to/train_dataset.txt", "/path/to/test_dataset.txt"))
在这种情况下， ``X_train`` 和 ``X_test`` 保证具有相同数量的特征。另一种实现相同结果的方法是固定特征的数量::

  >>> X_test, y_test = load_svmlight_file(
  ...     "/path/to/test_dataset.txt", n_features=X_train.shape[1])
  ...                                                         # doctest: +SKIP

.. rubric:: 相关链接

- `svmlight / libsvm 格式的公共数据集` : https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets
- `更快的 API 兼容实现` : https://github.com/mblondel/svmlight-loader

..
    For doctests:

    >>> import numpy as np
    >>> import os

.. _openml:

从 openml.org 仓库下载数据集
---------------------------------------------------

 `openml.org <https://openml.org>`_    是一个机器学习数据和实验的公共仓库，允许每个人上传开放数据集。

 ``sklearn.datasets`` 包能够使用函数 :func:`sklearn.datasets.fetch_openml` 从仓库下载数据集。

例如，下载一个关于小鼠大脑基因表达的数据集::

  >>> from sklearn.datasets import fetch_openml
  >>> mice = fetch_openml(name='miceprotein', version=4)

要完全指定一个数据集，你需要提供一个名称和一个版本，尽管版本是可选的，参见下面的 :ref:`openml_versions` 。
该数据集总共包含 1080 个样本，属于 8 个不同的类别::

  >>> mice.data.shape
  (1080, 77)
  >>> mice.target.shape
  (1080,)
  >>> np.unique(mice.target)
  array(['c-CS-m', 'c-CS-s', 'c-SC-m', 'c-SC-s', 't-CS-m', 't-CS-s', 't-SC-m', 't-SC-s'], dtype=object)

你可以通过查看 ``DESCR`` 和 ``details`` 属性来获取更多关于数据集的信息::

  >>> print(mice.DESCR) # doctest: +SKIP
  **作者**: Clara Higuera, Katheleen J. Gardiner, Krzysztof J. Cios
  **来源**: [UCI](https://archive.ics.uci.edu/ml/datasets/Mice+Protein+Expression) - 2015
  **请引用**: Higuera C, Gardiner KJ, Cios KJ (2015) 自组织特征映射图识别对学习至关重要的蛋白质，这些蛋白质在唐氏综合症的小鼠模型中。PLoS ONE 10(6): e0129126...

  >>> mice.details # doctest: +SKIP
  {'id': '40966', 'name': 'MiceProtein', 'version': '4', 'format': 'ARFF',
  'upload_date': '2017-11-08T16:00:15', 'licence': 'Public',
  'url': 'https://www.openml.org/data/v1/download/17928620/MiceProtein.arff',
  'file_id': '17928620', 'default_target_attribute': 'class',
  'row_id_attribute': 'MouseID',
  'ignore_attribute': ['Genotype', 'Treatment', 'Behavior'],
  'tag': ['OpenML-CC18', 'study_135', 'study_98', 'study_99'],
  'visibility': 'public', 'status': 'active',
  'md5_checksum': '3c479a6885bfa0438971388283a1ce32'}


 ``DESCR`` 包含数据的自由文本描述，而 ``details`` 包含由 openml 存储的元数据字典，如数据集 ID。更多详情，请参阅 `OpenML 文档 <https ://docs.openml.org/#data>`_  。小鼠蛋白质数据集的 ``data_id`` 是 40966，您可以使用此 ID（或名称）在 openml 网站上获取有关数据集的更多信息::

  >>> mice.url
  'https://www.openml.org/d/40966'

 ``data_id`` 还唯一标识来自 OpenML 的数据集::

  >>> mice = fetch_openml(data_id=40966)
  >>> mice.details # doctest: +SKIP
  {'id': '4550', 'name': 'MiceProtein', 'version': '1', 'format': 'ARFF',
  'creator': ...,
  'upload_date': '2016-02-17T14:32:49', 'licence': 'Public', 'url':
  'https://www.openml.org/data/v1/download/1804243/MiceProtein.ARFF', 'file_id':
  '1804243', 'default_target_attribute': 'class', 'citation': 'Higuera C,
  Gardiner KJ, Cios KJ (2015) 自组织特征映射图识别对学习至关重要的蛋白质，这些蛋白质在唐氏综合症的小鼠模型中。PLoS ONE 10(6):
  e0129126. [Web Link] journal.pone.0129126', 'tag': ['OpenML100', 'study_14',

  'study_34'], 'visibility': 'public', 'status': 'active', 'md5_checksum':
  '3c479a6885bfa0438971388283a1ce32'}

.. _openml_versions:

数据集版本
~~~~~~~~~~

一个数据集由其 ``data_id`` 唯一指定，但不一定由其名称唯一指定。具有相同名称的多个不同“版本”的数据集可以存在，这些版本可能包含完全不同的数据集。如果发现某个特定版本的数据集存在重大问题，可能会将其停用。使用名称来指定数据集将返回仍然有效的最早版本的数据集。这意味着 ``fetch_openml(name="miceprotein")`` 在不同时间可能会产生不同的结果，如果早期版本变为非活动状态。您可以看到我们上面获取的 ``data_id`` 为 40966 的数据集是 "miceprotein" 数据集的第一个版本::

  >>> mice.details['version']  #doctest: +SKIP
  '1'

事实上，这个数据集只有一个版本。而鸢尾花数据集则有多个版本::

  >>> iris = fetch_openml(name="iris")
  >>> iris.details['version']  #doctest: +SKIP
  '1'
  >>> iris.details['id']  #doctest: +SKIP
  '61'

  >>> iris_61 = fetch_openml(data_id=61)
  >>> iris_61.details['version']
  '1'
  >>> iris_61.details['id']
  '61'

  >>> iris_969 = fetch_openml(data_id=969)
  >>> iris_969.details['version']
  '3'
  >>> iris_969.details['id']
  '969'

通过名称 "iris" 指定数据集将返回最低版本，即版本 1，其 ``data_id`` 为 61。为了确保始终获取这个确切的数据集，最安全的方法是通过数据集的 ``data_id`` 指定。另一个数据集，其 ``data_id`` 为 969，是版本 3（版本 2 已变为非活动状态），并且包含数据的二值化版本::

  >>> np.unique(iris_969.target)
  array(['N', 'P'], dtype=object)

您还可以同时指定名称和版本，这也唯一标识了数据集::

  >>> iris_version_3 = fetch_openml(name="iris", version=3)
  >>> iris_version_3.details['version']
  '3'


  >>> iris_version_3.details['id']
  '969'


.. rubric:: 参考文献

* :arxiv:`Vanschoren, van Rijn, Bischl 和 Torgo. "OpenML: 机器学习中的网络科学" ACM SIGKDD 探索通讯, 15(2), 49-60, 2014.
  <1407.7722>` 

.. _openml_parser:

ARFF 解析器
~~~~~~~~~~~

从版本 1.2 开始，scikit-learn 提供了一个新的关键字参数 `parser` ，该参数提供了几种解析 OpenML 提供的 ARFF 文件的选项。传统的解析器（即 `parser="liac-arff"` ）基于 `LIAC-ARFF <https://github.com/renatopp/liac-arff>`_    项目。然而，这个解析器速度较慢，并且消耗的内存比所需的多。基于 pandas 的新解析器（即 `parser="pandas"` ）速度更快，内存效率更高。然而，这个解析器不支持稀疏数据。因此，我们建议使用 `parser="auto"` ，它将使用最适合请求数据集的解析器。

 `"pandas"` 和 `"liac-arff"` 解析器可能导致输出中的数据类型不同。显著的差异如下：

- `"liac-arff"` 解析器总是将分类特征编码为 `str` 对象。相反， `"pandas"` 解析器在读取时推断类型，数值类别将尽可能转换为整数。
- `"liac-arff"` 解析器使用 float64 编码元数据中标记为 'REAL' 和 'NUMERICAL' 的数值特征。 `"pandas"` 解析器则推断这些数值特征是否对应于整数，并使用 pandas 的整数扩展数据类型。
- 特别是，具有整数类别的分类数据集通常会使用 `"pandas"` 解析器加载为 `(0, 1, ...)` ，而 `"liac-arff"` 解析器将强制使用字符串编码的类别标签，如 `"0"` 、 `"1"` 等。
- `"pandas"` 解析器不会从字符串列中去除单引号 - 即 `'` 。例如，字符串 `'my string'` 将保持原样，而 `"liac-arff"` 解析器会去除单引号。对于分类列，

单引号会从值中去除。

此外，当使用 `as_frame=False` 时， `"liac-arff"` 解析器返回顺序编码的数据，其中类别在 `Bunch` 实例的 `categories` 属性中提供。相反， `"pandas"` 返回一个 NumPy 数组，其中包含类别。然后，用户需要设计一个特征工程管道，通常使用 `OneHotEncoder` 或 `OrdinalEncoder` 实例包装在 `ColumnTransformer` 中，以显式预处理分类列。例如，请参见：:ref:`sphx_glr_auto_examples_compose_plot_column_transformer_mixed_types.py` 。

.. _external_datasets:

从外部数据集加载
------------------

scikit-learn 适用于存储为 numpy 数组或 scipy 稀疏矩阵的任何数值数据。其他可转换为数值数组的数据类型，如 pandas DataFrame，也是可以接受的。

以下是一些推荐的方法，用于将标准列式数据加载到 scikit-learn 可用的格式：

* `pandas.io <https://pandas.pydata.org/pandas-docs/stable/io.html>`_    提供了从常见格式（包括 CSV、Excel、JSON 和 SQL）读取数据的工具。DataFrame 也可以从元组列表或字典构造。Pandas 平滑处理异构数据，并提供工具将其转换为适合 scikit-learn 的数值数组。
* `scipy.io <https://docs.scipy.org/doc/scipy/reference/io.html>`_    专门处理科学计算中常用的二进制格式，如 .mat 和 .arff。
* `numpy/routines.io <https://docs.scipy.org/doc/numpy/reference/routines.io.html>`_    用于将列式数据标准加载到 numpy 数组中。
* scikit-learn 的 :func:`load_svmlight_file` 用于 svmlight 或 libSVM 稀疏格式。
* scikit-learn 的 :func:`load_files` 用于文本文件目录，其中每个目录的名称是每个类别的名称，每个目录中的每个文件对应于该类别的一个样本。
对于一些杂项数据，如图像、视频和音频，您可能希望参考：

* `skimage.io <https://scikit-image.org/docs/dev/api/skimage.io.html>`_    或
  `Imageio <https://imageio.readthedocs.io/en/stable/reference/core_v3.html>`_   
  用于将图像和视频加载到 numpy 数组中
* `scipy.io.wavfile.read
  <https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.wavfile.read.html>`_   
  用于将 WAV 文件读取到 numpy 数组中

存储为字符串的分类（或名义）特征（常见于 pandas DataFrame）需要使用
:class:`~sklearn.preprocessing.OneHotEncoder` 或
:class:`~sklearn.preprocessing.OrdinalEncoder` 或类似方法转换为数值特征。
请参阅 :ref:`preprocessing` 。

注意：如果您自行管理数值数据，建议使用 HDF5 等优化文件格式以减少数据加载时间。
H5Py、PyTables 和 pandas 等库提供了该格式的 Python 接口，用于读取和写入数据。