数据集模块

数据集模块#

推荐数据集及相关工具

推荐数据集#

Amazon Reviews#

Amazon Reviews 数据集包含来自 Amazon 的评论。数据跨度为 18 年，截至 2013 年 3 月，包含约 3500 万条评论。评论包括产品和用户信息、评分以及纯文本评论。

引用:: J. McAuley and J. Leskovec, “Hidden factors and hidden topics: understanding rating dimensions with review text”, RecSys, 2013.

recommenders.datasets.amazon_reviews.data_preprocessing(reviews_file, meta_file, train_file, valid_file, test_file, user_vocab, item_vocab, cate_vocab, sample_rate=0.01, valid_num_ngs=4, test_num_ngs=9, is_history_expanding=True)[源码]#

从原始数据集创建用于训练、验证和测试的数据

参数:

reviews_file (str) – 从先前的操作下载的评论数据集。
meta_file (str) – 从先前的操作下载的元数据集。

recommenders.datasets.amazon_reviews.download_and_extract(name, dest_path)[源码]#

下载并提取 Amazon 评论和元数据文件，如果它们尚不存在

参数:

name (str) – 评论类别。
dest_path (str) – 下载文件的文件路径。

返回:

提取文件的文件路径。

返回类型:

str

recommenders.datasets.amazon_reviews.get_review_data(reviews_file)[源码]#

（仅）下载 Amazon 评论数据，按所需格式准备并存储在同一位置

参数:: reviews_file (str) – 下载的评论数据集的文件名。

CORD-19#

COVID-19 开放研究数据集 (CORD-19) 是一个包含 COVID-19 和冠状病毒相关学术文章的全文和元数据数据集，针对机器可读性进行了优化，并供全球研究社区使用。

为应对 COVID-19 大流行，艾伦人工智能研究所与领先的研究机构合作，准备并分发 COVID-19 开放研究数据集 (CORD-19)，这是一个免费资源，包含超过 47,000 篇学术文章，其中超过 36,000 篇有全文，内容关于 COVID-19 和冠状病毒家族病毒，供全球研究社区使用。

此数据集旨在动员研究人员应用自然语言处理的最新进展，以产生新的见解，支持对抗这种传染病。

引用:: Wang, L.L., Lo, K., Chandrasekhar, Y., Reas, R., Yang, J., Eide, D., Funk, K., Kinney, R., Liu, Z., Merrill, W. and Mooney, P. “Cord-19: The COVID-19 Open Research Dataset.”, 2020.

recommenders.datasets.covid_utils.clean_dataframe(df)[源码]#

清理数据帧。

参数:: df (pandas.DataFrame) – Pandas 数据帧。
返回:: 清理后的 Pandas 数据帧。
返回类型:: df (pandas.DataFrame)

recommenders.datasets.covid_utils.get_public_domain_text(df, container_name, azure_storage_account_name='azureopendatastorage', azure_storage_sas_token='')[源码]#

获取所有公共领域文本。

参数:

df (pandas.DataFrame) – 公共领域文本的元数据数据帧。
container_name (str) – Azure 存储容器名称。
azure_storage_account_name (str) – Azure 存储帐户名称。
azure_storage_sas_token (str) – Azure 存储 SAS 令牌。

返回:

包含部分元数据和文章全文的数据帧。

返回类型:

df_full (pandas.DataFrame)

recommenders.datasets.covid_utils.load_pandas_df(azure_storage_account_name='azureopendatastorage', azure_storage_sas_token='', container_name='covid19temp', metadata_filename='metadata.csv')[源码]#

将 Azure 开放研究 COVID-19 数据集加载为 pd.DataFrame。

Azure COVID-19 开放研究数据集可在 https://azure.microsoft.com/en-us/services/open-datasets/catalog/covid-19-open-research/ 找到

参数:

azure_storage_account_name (str) – Azure 存储帐户名称。
azure_storage_sas_token (str) – Azure 存储 SAS 令牌。
container_name (str) – Azure 存储容器名称。
metadata_filename (str) – 包含数据集顶层元数据的文件名。

返回:

元数据数据帧。

返回类型:

metadata (pandas.DataFrame)

recommenders.datasets.covid_utils.remove_duplicates(df, cols)[源码]#

移除重复条目。

参数:

df (pd.DataFrame) – Pandas 数据帧。
cols (list of str) – 在其中查找重复项的列名列表。

返回:

删除了重复行的 Pandas 数据帧。

返回类型:

df (pandas.DataFrame)

recommenders.datasets.covid_utils.remove_nan(df, cols)[源码]#

移除指定列中包含 NaN 值的行。

参数:

df (pandas.DataFrame) – Pandas 数据帧。
cols (list of str) – 在其中查找 NaN 的列名列表。

返回:

删除了无效行的 Pandas 数据帧。

返回类型:

df (pandas.DataFrame)

recommenders.datasets.covid_utils.retrieve_text(entry, container_name, azure_storage_account_name='azureopendatastorage', azure_storage_sas_token='')[源码]#

从感兴趣的文章中检索正文文本。

参数:

entry (pd.Series) – 数据帧中的单行 (df.iloc[n])。
container_name (str) – Azure 存储容器名称。
azure_storage_account_name (str) – Azure 存储帐户名称。
azure_storage_sas_token (str) – Azure 存储 SAS 令牌。

结果: text (str): blob 的全文，作为单个字符串。

Criteo#

由 Criteo Labs 发布的Criteo 数据集是一个在线广告数据集，包含数百万展示广告的特征值和点击反馈。每个广告有 40 个属性，第一个属性是标签，值为 1 表示广告被点击，值为 0 表示广告未被点击。其余部分包括 13 个整数列和 26 个分类列。

recommenders.datasets.criteo.download_criteo(size='sample', work_directory='.')[源码]#

将 criteo 数据集下载为压缩文件。

参数:

size (str) – criteo 数据集的大小。可以是“full”或“sample”。
work_directory (str) – 工作目录。

返回:

下载文件的路径。

返回类型:

str

recommenders.datasets.criteo.extract_criteo(size, compressed_file, path=None)[源码]#

提取 Criteo 数据集 tar 文件。

参数:

size (str) – Criteo 数据集的大小。可以是“full”或“sample”。
compressed_file (str) – 压缩文件的路径。
path (str) – 提取文件的路径。

返回:

提取文件的路径。

返回类型:

str

recommenders.datasets.criteo.get_spark_schema(header=['label', 'int00', 'int01', 'int02', 'int03', 'int04', 'int05', 'int06', 'int07', 'int08', 'int09', 'int10', 'int11', 'int12', 'cat00', 'cat01', 'cat02', 'cat03', 'cat04', 'cat05', 'cat06', 'cat07', 'cat08', 'cat09', 'cat10', 'cat11', 'cat12', 'cat13', 'cat14', 'cat15', 'cat16', 'cat17', 'cat18', 'cat19', 'cat20', 'cat21', 'cat22', 'cat23', 'cat24', 'cat25'])[源码]#

从头部获取 Spark schema。

参数:: header (list) – 数据集头部名称。
返回:: Spark schema。
返回类型:: pyspark.sql.types.StructType

recommenders.datasets.criteo.load_pandas_df(size='sample', local_cache_path=None, header=['label', 'int00', 'int01', 'int02', 'int03', 'int04', 'int05', 'int06', 'int07', 'int08', 'int09', 'int10', 'int11', 'int12', 'cat00', 'cat01', 'cat02', 'cat03', 'cat04', 'cat05', 'cat06', 'cat07', 'cat08', 'cat09', 'cat10', 'cat11', 'cat12', 'cat13', 'cat14', 'cat15', 'cat16', 'cat17', 'cat18', 'cat19', 'cat20', 'cat21', 'cat22', 'cat23', 'cat24', 'cat25'])[源码]#

将 Criteo DAC 数据集加载为 pandas.DataFrame。此函数会下载、解压并加载数据集。

该数据集包含 Criteo 在 24 天期间的部分流量。每行对应一个由 Criteo 服务的展示广告，第一列指示该广告是否被点击。

有 13 个整数值特征（主要是计数特征）和 26 个分类特征。为了匿名化目的，分类特征的值已被哈希到 32 位。

其 schema 为

<label> <integer feature 1> ... <integer feature 13> <categorical feature 1> ... <categorical feature 26>

更多详情（需要接受用户条款才能查看信息）：http://labs.criteo.com/2013/12/download-terabyte-click-logs/

参数:

size (str) – 数据集大小。可以是“sample”或“full”。
local_cache_path (str) – 在本地缓存 tar.gz 文件的路径
header (list) – 数据集头部名称。

返回:

Criteo DAC 样本数据集。

返回类型:

pandas.DataFrame

recommenders.datasets.criteo.load_spark_df(spark, size='sample', header=None, schema=None, local_cache_path=None, dbfs_datapath='dbfs:/FileStore/dac', dbutils=None)[源码]#

将 Criteo DAC 数据集加载为 pySpark.DataFrame。

该数据集包含 Criteo 在 24 天期间的部分流量。每行对应一个由 Criteo 服务的展示广告，第一列指示该广告是否被点击。

有 13 个整数值特征（主要是计数特征）和 26 个分类特征。为了匿名化目的，分类特征的值已被哈希到 32 位。

其 schema 为

<label> <integer feature 1> ... <integer feature 13> <categorical feature 1> ... <categorical feature 26>

更多详情（需要接受用户条款才能查看信息）：http://labs.criteo.com/2013/12/download-terabyte-click-logs/

参数:

spark (pySpark.SparkSession) – Spark 会话。
size (str) – 数据集大小。可以是“sample”或“full”。
local_cache_path (str) – 在本地缓存 tar.gz 文件的路径。
header (list) – 数据集头部名称。
dbfs_datapath (str) – 在 Databricks 上存储提取文件的位置。
dbutils (Databricks.dbutils) – Databricks 工具对象。

返回:

Criteo DAC 训练数据集。

返回类型:

pyspark.sql.DataFrame

MIND#

微软新闻数据集 (MIND) 是一个用于新闻推荐研究的大规模数据集。它从微软新闻网站的匿名行为日志中收集。

MIND 包含约 16 万篇英文新闻文章和由 100 万用户生成的超过 1500 万条印象日志。每篇新闻文章都包含丰富的文本内容，包括标题、摘要、正文、类别和实体。每条印象日志包含此用户在此印象之前的点击事件、未点击事件和历史新闻点击行为。为了保护用户隐私，每个用户在安全哈希生成匿名 ID 后，与生产系统解除关联。

引用:: Fangzhao Wu, Ying Qiao, Jiun-Hung Chen, Chuhan Wu, Tao Qi, Jianxun Lian, Danyang Liu, Xing Xie, Jianfeng Gao, Winnie Wu and Ming Zhou, “MIND: A Large-scale Dataset for News Recommendation”, ACL, 2020.

recommenders.datasets.mind.download_and_extract_glove(dest_path)[源码]#

下载并提取 Glove embedding

参数:: dest_path (str) – 下载文件的目标目录路径
返回:: Glove 提取后的文件路径。
返回类型:: str

recommenders.datasets.mind.download_mind(size='small', dest_path=None)[源码]#

下载 MIND 数据集

参数:

size (str) – 数据集大小。可以是 [“small”, “large”] 之一
dest_path (str) – 下载路径。如果 path 为 None，它将下载数据集到一个临时路径

返回:

训练集和验证集的路径。

返回类型:

str, str

recommenders.datasets.mind.extract_mind(train_zip, valid_zip, train_folder='train', valid_folder='valid', clean_zip_file=True)[源码]#

提取 MIND 数据集

参数:

train_zip (str) – 训练 zip 文件的路径
valid_zip (str) – 验证 zip 文件的路径
train_folder (str) – 训练集的目标文件夹
valid_folder (str) – 验证集的目标文件夹

返回:

训练和验证文件夹

返回类型:

str, str

recommenders.datasets.mind.generate_embeddings(data_path, news_words, news_entities, train_entities, valid_entities, max_sentence=10, word_embedding_dim=100)[源码]#

生成 embeddings。

参数:

data_path (str) – 数据路径。
news_words (dict) – 新闻词典。
news_entities (dict) – 新闻实体词典。
train_entities (str) – 训练实体文件。
valid_entities (str) – 验证实体文件。
max_sentence (int) – 最大句子长度。
word_embedding_dim (int) – 词 embedding 维度。

返回:

新闻、词和实体 embeddings 的文件路径。

返回类型:

str, str, str

recommenders.datasets.mind.get_train_input(session, train_file_path, npratio=4)[源码]#

生成训练文件。

参数:

session (list) – 用户会话列表，包含 user_id、点击、正负交互。
train_file_path (str) – 文件路径。
npration (int) – 负采样比例。

recommenders.datasets.mind.get_user_history(train_history, valid_history, user_history_path)[源码]#

生成用户历史文件。

参数:

train_history (list) – 训练历史。
valid_history (list) – 验证历史
user_history_path (str) – 文件路径。

recommenders.datasets.mind.get_valid_input(session, valid_file_path)[源码]#

生成验证文件。

参数:

session (list) – 用户会话列表，包含 user_id、点击、正负交互。
valid_file_path (str) – 文件路径。

recommenders.datasets.mind.get_words_and_entities(train_news, valid_news)[源码]#

加载词和实体

参数:

train_news (str) – 新闻训练文件。
valid_news (str) – 新闻验证文件。

返回:

词和实体词典。

返回类型:

dict, dict

recommenders.datasets.mind.load_glove_matrix(path_emb, word_dict, word_embedding_dim)[源码]#

加载 word_dict 中词的预训练 embedding 指标

参数:

path_emb (string) – 下载的 glove 文件的文件夹路径
word_dict (dict) – 词典
word_embedding_dim – 词 embedding 向量的维度

返回:

预训练词 embedding 指标，词可以在 glove 文件中找到

返回类型:

numpy.ndarray, list

recommenders.datasets.mind.read_clickhistory(path, filename)[源码]#

读取点击历史文件

参数:

path (str) – 文件夹路径
filename (str) – 文件名

返回:

一个用户会话列表，包含 user_id、点击、正负交互。
一个包含 user_id 点击历史的字典。

返回类型:

list, dict

recommenders.datasets.mind.word_tokenize(sent)[源码]#

对句子进行分词

参数:: sent – 需要分词的句子
返回:: 句子中的词
返回类型:: list

MovieLens#

由 MovieLens 数据集，于 1998 年首次发布，描述了人们对电影的偏好。这些偏好以 <user, item, rating, timestamp> 元组的形式出现，每个元组都是一个人在特定时间对一部电影表达偏好（0-5 星评分）的结果。

它有几种不同的尺寸

MovieLens 100k: 来自 1000 位用户的 100,000 条评分，针对 1700 部电影。
MovieLens 1M: 来自 6000 位用户的 100 万条评分，针对 4000 部电影。
MovieLens 10M: 来自 72000 位用户的 1000 万条评分，针对 10000 部电影。
MovieLens 20M: 来自 138000 位用户的 2000 万条评分，针对 27000 部电影

引用:: F. M. Harper and J. A. Konstan. “The MovieLens Datasets: History and Context”. ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19, DOI=http://dx.doi.org/10.1145/2827872, 2015.

class recommenders.datasets.movielens.MockMovielensSchema(*args, **kwargs)[源码]#

模拟数据集 schema，用于生成假数据进行测试。此 schema 配置为模仿 Movielens 数据集

https://files.grouplens.org/datasets/movielens/ml-100k/

数据集 schema 和生成使用 pandera 进行配置。更多信息请参见 https://pandera.readthedocs.io/en/latest/schema_models.html。

class Config#

name: str | None = 'MockMovielensSchema'#: schema 名称

classmethod get_df(size: int =3, seed: int =100, keep_first_n_cols: int | None =None, keep_title_col: bool =False, keep_genre_col: bool =False) → DataFrame[源码]#

返回指定行数的模拟 movielens 数据集作为 Pandas Dataframe。

参数:

size (int) – 要生成的行数
seed (int, optional) – 伪随机数生成的种子。默认为 100。
keep_first_n_cols (int, optional) – 保留前 n 个默认的 movielens 列。
keep_title_col (bool) – 如果为 False，则移除标题列。默认为 True。
keep_genre_col (bool) – 如果为 False，则移除流派列。默认为 True。

返回:

一个模拟数据集

返回类型:

pandas.DataFrame

classmethod get_spark_df(spark, size: int =3, seed: int =100, keep_title_col: bool =False, keep_genre_col: bool =False, tmp_path: str | None =None)[源码]#

将模拟 movielens 数据集作为指定行数的 Spark Dataframe 返回

参数:

spark (SparkSession) – 要加载数据帧的 spark 会话
size (int) – 要生成的行数
seed (int) – 伪随机数生成的种子。默认为 100。
keep_title_col (bool) – 如果为 False，则移除标题列。默认为 False。
keep_genre_col (bool) – 如果为 False，则移除流派列。默认为 False。
tmp_path (str, optional) – 在将数据从 python 传输到 java 时用于存储序列化文件的路径。如果为 None，则使用临时路径

返回:

一个模拟数据集

返回类型:

pyspark.sql.DataFrame

recommenders.datasets.movielens.download_movielens(size, dest_path)[源码]#

下载 MovieLens 数据文件。

参数:

size (str) – 要加载的数据的大小。可以是 (“100k”, “1m”, “10m”, “20m”) 之一。
dest_path (str) – 下载文件的文件路径

recommenders.datasets.movielens.extract_movielens(size, rating_path, item_path, zip_path)[源码]#

从 MovieLens 原始 zip 文件中提取 MovieLens 评分和项目数据文件。

要提取所有文件而不仅仅是评分和项目数据文件，请改用 ZipFile 的 extractall(path)。

参数:

size (str) – 要加载的数据的大小。可以是 (“100k”, “1m”, “10m”, “20m”) 之一。
rating_path (str) – 评分数据文件的目标路径
item_path (str) – 项目数据文件的目标路径
zip_path (str) – zip 文件路径

recommenders.datasets.movielens.load_item_df(size='100k', local_cache_path=None, movie_col='itemID', title_col=None, genres_col=None, year_col=None)[源码]#

加载电影信息。

参数:

size (str) – 要加载的数据的大小。可以是 (“100k”, “1m”, “10m”, “20m”) 之一。
local_cache_path (str) – 用于缓存下载的 zip 文件的路径（目录或 zip 文件）。如果为 None，所有中间文件将存储在临时目录中并在使用后删除。
movie_col (str) – 电影 id 列名。
title_col (str) – 电影标题列名。如果为 None，该列将不被加载。
genres_col (str) – 流派列名。流派是 '|' 分隔的字符串。如果为 None，该列将不被加载。
year_col (str) – 电影发行年份列名。如果为 None，该列将不被加载。

返回:

电影信息数据，例如标题、流派和发行年份。

返回类型:

pandas.DataFrame

recommenders.datasets.movielens.load_pandas_df(size='100k', header=None, local_cache_path=None, title_col=None, genres_col=None, year_col=None)[源码]#

将 MovieLens 数据集加载为 pd.DataFrame。

从 https://files.grouplens.org/datasets/movielens 下载数据集，解压并加载。只加载电影信息可以使用 load_item_df 函数。

参数:

size (str) – 要加载的数据的大小。可以是 (“100k”, “1m”, “10m”, “20m”, “mock100”) 之一。
header (list or tuple or None) – 评分数据集头部。如果 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略，数据将使用 ‘DEFAULT_HEADER’ 代替。
local_cache_path (str) – 用于缓存下载的 zip 文件的路径（目录或 zip 文件）。如果为 None，所有中间文件将存储在临时目录中并在使用后删除。如果 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略。
title_col (str) – 电影标题列名。如果为 None，该列将不被加载。
genres_col (str) – 流派列名。流派是 '|' 分隔的字符串。如果为 None，该列将不被加载。
year_col (str) – 电影发行年份列名。如果为 None，该列将不被加载。如果 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略。

返回:

电影评分数据集。

返回类型:

pandas.DataFrame

示例

# To load just user-id, item-id, and ratings from MovieLens-1M dataset,
df = load_pandas_df('1m', ('UserId', 'ItemId', 'Rating'))

# To load rating's timestamp together,
df = load_pandas_df('1m', ('UserId', 'ItemId', 'Rating', 'Timestamp'))

# To load movie's title, genres, and released year info along with the ratings data,
df = load_pandas_df('1m', ('UserId', 'ItemId', 'Rating', 'Timestamp'),
    title_col='Title',
    genres_col='Genres',
    year_col='Year'
)

recommenders.datasets.movielens.load_spark_df(spark, size='100k', header=None, schema=None, local_cache_path=None, dbutils=None, title_col=None, genres_col=None, year_col=None)[源码]#

将 MovieLens 数据集加载为 pyspark.sql.DataFrame。

从 https://files.grouplens.org/datasets/movielens 下载数据集，解压并加载为 pyspark.sql.DataFrame。

只加载电影信息可以使用 load_item_df 函数。

参数:

spark (pyspark.SparkSession) – Spark 会话。
size (str) – 要加载的数据的大小。可以是 (“100k”, “1m”, “10m”, “20m”, “mock100”) 之一。
header (list or tuple) – 评分数据集头部。如果提供了 schema 或将 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略。
schema (pyspark.StructType) – 数据集 schema。如果将 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则数据将以 ‘MockMovielensSchema’ 格式呈现。
local_cache_path (str) – 用于缓存下载的 zip 文件的路径（目录或 zip 文件）。如果为 None，所有中间文件将存储在临时目录中并在使用后删除。
dbutils (Databricks.dbutils) – Databricks 工具对象。如果将 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略。
title_col (str) – 标题列名。如果为 None，该列将不被加载。
genres_col (str) – 流派列名。流派是 '|' 分隔的字符串。如果为 None，该列将不被加载。
year_col (str) – 电影发行年份列名。如果为 None，该列将不被加载。如果 size 设置为 ‘MOCK_DATA_FORMAT’ 中的任何值，则此参数将被忽略。

返回:

电影评分数据集。

返回类型:

pyspark.sql.DataFrame

示例

# To load just user-id, item-id, and ratings from MovieLens-1M dataset:
spark_df = load_spark_df(spark, '1m', ('UserId', 'ItemId', 'Rating'))

# The schema can be defined as well:
schema = StructType([
    StructField(DEFAULT_USER_COL, IntegerType()),
    StructField(DEFAULT_ITEM_COL, IntegerType()),
    StructField(DEFAULT_RATING_COL, FloatType()),
    StructField(DEFAULT_TIMESTAMP_COL, LongType()),
    ])
spark_df = load_spark_df(spark, '1m', ('UserId', 'ItemId', 'Rating'), schema=schema)

# To load rating's timestamp together:
spark_df = load_spark_df(spark, '1m', ('UserId', 'ItemId', 'Rating', 'Timestamp'))

# To load movie's title, genres, and released year info along with the ratings data:
spark_df = load_spark_df(spark, '1m', ('UserId', 'ItemId', 'Rating', 'Timestamp'),
    title_col='Title',
    genres_col='Genres',
    year_col='Year'
)

# On DataBricks, pass the dbutils argument as follows:
spark_df = load_spark_df(spark, dbutils=dbutils)

下载工具#

recommenders.datasets.download_utils.download_path(path=None)[源码]#

返回下载数据的路径。如果 path=None，则生成一个最终会被删除的临时路径，否则返回输入路径的实际路径。

参数:: path (str) – 下载数据的路径。
返回:: 数据存储的实际路径。
返回类型:: str

示例

>>> with download_path() as path:
>>> ... maybe_download(url="http://example.com/file.zip", work_directory=path)

recommenders.datasets.download_utils.maybe_download(url, filename=None, work_directory='.', expected_bytes=None)[源码]#

如果文件尚未下载，则下载它。

参数:

filename (str) – 文件名。
work_directory (str) – 工作目录。
url (str) – 要下载文件的 URL。
expected_bytes (int) – 预期的文件大小（字节）。

返回:

下载文件的文件路径。

返回类型:

str

recommenders.datasets.download_utils.unzip_file(zip_src, dst_dir, clean_zip_file=False)[源码]#

解压文件

参数:

zip_src (str) – Zip 文件。
dst_dir (str) – 目标文件夹。
clean_zip_file (bool) – 是否删除 zip 文件。

Pandas 数据帧工具#

class recommenders.datasets.pandas_df_utils.LibffmConverter(filepath=None)[源码]#

将输入数据帧转换为 libffm 格式的另一个数据帧。可选地生成转换后数据帧的文本文件。

注意

输入数据帧应按以下 schema 表示特征数据

|field-1|field-2|...|field-n|rating|
|feature-1-1|feature-2-1|...|feature-n-1|1|
|feature-1-2|feature-2-2|...|feature-n-2|0|
...
|feature-1-i|feature-2-j|...|feature-n-k|0|

其中 1. 每个 field-* 是数据帧的列名（排除标签/评分列），以及 2. feature-*-* 可以是字符串或数值，分别表示字段中特征值的分类变量或实际数值变量。 3. 如果存在以 int 类型表示的有序变量，用户应确保这些列正确转换为字符串类型。

上述数据将按照本文中解释的约定转换为 libffm 格式。

即 <field_index>:<field_feature_index>:1 或 <field_index>:<field_feature_index>:<field_feature_value>，具体取决于原始数据帧中特征的数据类型。

参数:: filepath (str) – 保存转换后数据的路径。

field_count#

libffm 格式数据中字段的数量

类型:: int

feature_count#

libffm 格式数据中特征的数量

类型:: int

filepath#

输出文件的存储路径 - 可以是 None 或字符串

类型:: str or None

示例

>>> import pandas as pd
>>> df_feature = pd.DataFrame({
        'rating': [1, 0, 0, 1, 1],
        'field1': ['xxx1', 'xxx2', 'xxx4', 'xxx4', 'xxx4'],
        'field2': [3, 4, 5, 6, 7],
        'field3': [1.0, 2.0, 3.0, 4.0, 5.0],
        'field4': ['1', '2', '3', '4', '5']
    })
>>> converter = LibffmConverter().fit(df_feature, col_rating='rating')
>>> df_out = converter.transform(df_feature)
>>> df_out
    rating field1 field2   field3 field4
0       1  1:1:1  2:4:3  3:5:1.0  4:6:1
1       0  1:2:1  2:4:4  3:5:2.0  4:7:1
2       0  1:3:1  2:4:5  3:5:3.0  4:8:1
3       1  1:3:1  2:4:6  3:5:4.0  4:9:1
4       1  1:3:1  2:4:7  3:5:5.0  4:10:1

fit(df, col_rating='rating')[源码]#

适配 libffm 格式的数据帧。此方法仅检查输入列的有效性。

参数:

df (pandas.DataFrame) – 输入 Pandas 数据帧。
col_rating (str) – 数据的评分。

返回:

转换器实例

返回类型:

object

fit_transform(df, col_rating='rating')[源码]#

按顺序执行 fit 和 transform

参数:

df (pandas.DataFrame) – 输入 Pandas 数据帧。
col_rating (str) – 数据的评分。

返回:

输出 libffm 格式数据帧。

返回类型:

pandas.DataFrame

get_params()[源码]#

获取 libffm 转换器的参数（属性）

返回:: 一个包含字段计数、特征计数和文件路径的字典。
返回类型:: dict

transform(df)[源码]#

使用已适配的转换器将具有相同 schema（列名和 dtypes）的输入数据集转换为 libffm 格式。

参数:: df (pandas.DataFrame) – 输入 Pandas 数据帧。
返回:: 输出 libffm 格式数据帧。
返回类型:: pandas.DataFrame

class recommenders.datasets.pandas_df_utils.PandasHash(pandas_object)[源码]#: 包装类，允许 pandas 对象 (DataFrames 或 Series) 成为可哈希的

recommenders.datasets.pandas_df_utils.filter_by(df, filter_by_df, filter_by_cols)[源码]#

从输入 DataFrame df 中，移除其目标列 filter_by_cols 的值存在于 filter-by DataFrame filter_by_df 中的记录。

参数:

df (pandas.DataFrame) – 源数据帧。
filter_by_df (pandas.DataFrame) – 过滤数据帧。
filter_by_cols (iterable of str) – 过滤列。

返回:

根据 filter_by_df 在 filter_by_cols 上过滤后的数据帧。

返回类型:

pandas.DataFrame

recommenders.datasets.pandas_df_utils.has_columns(df, columns)[源码]#

检查 DataFrame 是否包含必需的列

参数:

df (pandas.DataFrame) – DataFrame
columns (iterable(str)) – 要检查的列

返回:

如果 DataFrame 包含指定列，则为 True。

返回类型:

bool

recommenders.datasets.pandas_df_utils.has_same_base_dtype(df_1, df_2, columns=None)[源码]#

检查指定列在两个 DataFrames 中是否具有相同的基本 dtypes

参数:

df_1 (pandas.DataFrame) – 第一个 DataFrame
df_2 (pandas.DataFrame) – 第二个 DataFrame
columns (list(str)) – 要检查的列，None 表示检查所有列

返回:

如果 DataFrames 列具有相同的基本 dtypes，则为 True。

返回类型:

bool

recommenders.datasets.pandas_df_utils.lru_cache_df(maxsize, typed=False)[源码]#

pandas Dataframes 的最近最少使用缓存装饰器。

一个装饰器，用一个记忆化（memoizing）可调用对象包装函数，该对象保存最多 maxsize 次最近的调用。当一个开销大或 I/O 绑定的函数定期使用相同的参数被调用时，这可以节省时间。

灵感来自 lru_cache 函数。

参数:

maxsize (int|None) – 缓存最大大小，如果设置为 None 则缓存无限制
typed (bool) – 不同类型的参数分开缓存

recommenders.datasets.pandas_df_utils.negative_feedback_sampler(df, col_user='userID', col_item='itemID', col_label=None, col_feedback='feedback', ratio_neg_per_user=1, pos_value=1, neg_value=0, seed=42)[源码]#

从用户-项目交互数据集中采样负反馈的工具函数。此负采样函数将使用用户-项目交互数据创建二元反馈，即 1 和 0 分别表示正反馈和负反馈。

在文献中，负采样常用于从用户-项目交互数据生成负样本。

例如参见神经网络协同过滤论文。

参数:

df (pandas.DataFrame) – 包含用户-项目元组的输入数据。
col_user (str) – 用户 id 列名。
col_item (str) – 项目 id 列名。
col_label (str) – df 中的标签列名。
col_feedback (str) – 返回的数据帧中的反馈列名；它用于生成的正反馈和负反馈列。
ratio_neg_per_user (int) – 每个用户的负反馈与正反馈数量之比。如果采样数超过总可能的负反馈样本数，则会减少到所有可能的样本数。
pos_value (float) – 正反馈的值。
neg_value (float) – 负反馈的值。
inplace (bool)
seed (int) – 采样函数随机状态的种子。

返回:

包含负反馈的数据。

返回类型:

pandas.DataFrame

示例

>>> import pandas as pd
>>> df = pd.DataFrame({
    'userID': [1, 2, 3],
    'itemID': [1, 2, 3],
    'rating': [5, 5, 5]
})
>>> df_neg_sampled = negative_feedback_sampler(
    df, col_user='userID', col_item='itemID', ratio_neg_per_user=1
)
>>> df_neg_sampled
userID  itemID  feedback
1   1   1
1   2   0
2   2   1
2   1   0
3   3   1
3   1   0

recommenders.datasets.pandas_df_utils.user_item_pairs(user_df, item_df, user_col='userID', item_col='itemID', user_item_filter_df=None, shuffle=True, seed=None)[source]#

获取所有用户和物品数据对。

参数:

user_df (pandas.DataFrame) – 包含唯一用户ID及其特征的用户数据。
item_df (pandas.DataFrame) – 包含唯一物品ID及其特征的物品数据。
user_col (str) – 用户ID列名。
item_col (str) – 物品ID列名。
user_item_filter_df (pd.DataFrame) – 用作过滤器的用户-物品对。
shuffle (bool) – 如果为 True，则打乱结果。
seed (int) – 用于打乱的随机种子

返回:

user_df 和 item_df 中除 user_item_filter_df 中指定的对之外的所有用户-物品对。

返回类型:

pandas.DataFrame

分割器工具#

Python 分割器#

recommenders.datasets.python_splitters.numpy_stratified_split(X, ratio=0.75, seed=42)[source]#

将用户/物品亲和度矩阵（稀疏矩阵）分割成训练集和测试集矩阵，同时保持局部（即每个用户）的比例。

要点

1. 在典型的推荐系统中，不同用户评价的物品数量不同，因此用户/亲和度矩阵具有稀疏结构，每行（用户）的零值（未评价物品）数量各不相同。如果仅根据总评分数量进行分割，将导致训练集和测试集之间的分布不均匀，即某些测试用户可能有很多评分，而其他用户评分很少甚至没有。

2. 在无监督学习问题中，没有给出明确的答案。因此，分割方法的实现需要与监督学习不同。在监督学习中，通常按行（按样本）分割数据集，最终训练集/测试集具有相同数量的特征，但样本数量不同。这种方案在无监督情况下不起作用，因为需要使用部分已评分物品作为固定数量用户的测试集。

解决方案

1. 不是按总百分比进行分割，而是为每个用户按已评分物品的相对比例进行分割。例如，如果用户1评价了4个物品，用户2评价了10个物品，按25%的比例分割将在测试集中分别对应1个和2.6个评分，根据round()函数近似为1个和3个。通过这种方式，0.75的比例在局部和全局都得到满足，保留了评分在训练集和测试集中的原始分布。

2. 通过从原始数据集 X 中减去元素来创建测试集，可以轻松（且快速地）满足这些要求。我们首先创建 X 的两个副本；对于每个用户，我们随机抽取本地大小比例的样本（第1点）并擦除剩余的评分，从而得到训练集矩阵 Xtst。训练集矩阵则以相反的方式获得。

参数:

X (numpy.ndarray, int) – 要分割的稀疏矩阵
ratio (float) – 构成训练集的整个数据集的比例
seed (int) – 随机种子

返回:

Xtr: 训练集用户/物品亲和度矩阵。
Xtst: 测试集用户/物品亲和度矩阵。

返回类型:

numpy.ndarray, numpy.ndarray

recommenders.datasets.python_splitters.python_chrono_split(data, ratio=0.75, min_rating=1, filter_by='user', col_user='userID', col_item='itemID', col_timestamp='timestamp')[source]#

Pandas 按时间顺序分割器。

此函数按时间顺序分割数据。也就是说，对于每个用户/物品，分割函数按照指定的分割比例取一部分评分。分割是分层的。

参数:

data (pandas.DataFrame) – 要分割的 Pandas DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。
seed (int) – 种子。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。
col_timestamp (str) – 时间戳列名。

返回:

输入数据的分割结果，类型为 pandas.DataFrame。

返回类型:

list

recommenders.datasets.python_splitters.python_random_split(data, ratio=0.75, seed=42)[source]#

Pandas 随机分割器。

分割器随机分割输入数据。

参数:

data (pandas.DataFrame) – 要分割的 Pandas DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。
seed (int) – 种子。

返回:

输入数据的分割结果，类型为 pandas.DataFrame。

返回类型:

list

recommenders.datasets.python_splitters.python_stratified_split(data, ratio=0.75, min_rating=1, filter_by='user', col_user='userID', col_item='itemID', seed=42)[source]#

Pandas 分层分割器。

对于每个用户/物品，分割函数按照指定的分割比例取一部分评分。分割是分层的。

参数:

data (pandas.DataFrame) – 要分割的 Pandas DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。
seed (int) – 种子。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。

返回:

输入数据的分割结果，类型为 pandas.DataFrame。

返回类型:

list

PySpark 分割器#

recommenders.datasets.spark_splitters.spark_chrono_split(data, ratio=0.75, min_rating=1, filter_by='user', col_user='userID', col_item='itemID', col_timestamp='timestamp', no_partition=False)[source]#

Spark 按时间顺序分割器。

此函数按时间顺序分割数据。也就是说，对于每个用户/物品，分割函数按照指定的分割比例取一部分评分。分割是分层的。

参数:

data (pyspark.sql.DataFrame) – 要分割的 Spark DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。
col_timestamp (str) – 时间戳列名。
no_partition (bool) – 设置此项可实现更精确但效率较低的分割。

返回:

输入数据的分割结果，类型为 pyspark.sql.DataFrame。

返回类型:

list

recommenders.datasets.spark_splitters.spark_random_split(data, ratio=0.75, seed=42)[source]#

Spark 随机分割器。

将数据随机分割成几部分。

参数:

data (pyspark.sql.DataFrame) – 要分割的 Spark DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。
seed (int) – 种子。

返回:

输入数据的分割结果，类型为 pyspark.sql.DataFrame。

返回类型:

list

recommenders.datasets.spark_splitters.spark_stratified_split(data, ratio=0.75, min_rating=1, filter_by='user', col_user='userID', col_item='itemID', seed=42)[source]#

Spark 分层分割器。

对于每个用户/物品，分割函数按照指定的分割比例取一部分评分。分割是分层的。

参数:

data (pyspark.sql.DataFrame) – 要分割的 Spark DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两半，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。索引较早的分割将具有较早的时间（例如，split[0] 中每个用户或物品的最晚时间 <= split[1] 中每个用户或物品的最早时间）
seed (int) – 种子。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。

返回:

输入数据的分割结果，类型为 pyspark.sql.DataFrame。

返回类型:

list

recommenders.datasets.spark_splitters.spark_timestamp_split(data, ratio=0.75, col_user='userID', col_item='itemID', col_timestamp='timestamp')[source]#

Spark 基于时间戳的分割器。

此分割器根据时间戳将数据分割成若干集合，不对用户或物品进行分层。比例应用于时间戳列，该列相应地被划分成若干分区。

参数:

data (pyspark.sql.DataFrame) – 要分割的 Spark DataFrame。
ratio (float 或 list) – 数据分割比例。如果是一个浮点数，则将数据分成两部分，比例参数表示训练数据集的比例；如果是一个浮点数列表，则分割器将数据分割成与分割比例相对应的几部分。如果提供的是列表且比例之和不为1，则会进行归一化。索引较早的分割将具有较早的时间（例如，split[0] 中的最晚时间 <= split[1] 中的最早时间）
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。
col_timestamp (str) – 时间戳列名。以浮点数表示，单位为
纪元（秒）。

返回:

输入数据的分割结果，类型为 pyspark.sql.DataFrame。

返回类型:

list

其他分割器工具#

recommenders.datasets.split_utils.filter_k_core(data, core_num=0, col_user='userID', col_item='itemID')[source]#: 通过重复应用 min_rating_filter 直到满足条件，过滤评分 DataFrame 以满足用户和物品的最小数量要求。

recommenders.datasets.split_utils.min_rating_filter_pandas(data, min_rating=1, filter_by='user', col_user='userID', col_item='itemID')[source]#

按每个用户的最小评分数量过滤评分 DataFrame。

过滤用户/物品具有最小评分数量的评分 DataFrame 通常有助于生成一个包含活跃用户/物品的新 DataFrame。活跃度由 min_rating 参数定义。例如，如果一个用户至少评价了4个物品，则称该用户为活跃用户（warm user）。

参数:

data (pandas.DataFrame) – 包含用户-物品元组的 DataFrame。DataFrame 中应包含用户和物品列，而评分、时间戳等其他列是可选的。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。

返回:

根据给定规范过滤后的 DataFrame，至少包含用户和物品列。

返回类型:

pandas.DataFrame

recommenders.datasets.split_utils.min_rating_filter_spark(data, min_rating=1, filter_by='user', col_user='userID', col_item='itemID')[source]#

按每个用户的最小评分数量过滤评分 DataFrame。

过滤用户/物品具有最小评分数量的评分 DataFrame 通常有助于生成一个包含活跃用户/物品的新 DataFrame。活跃度由 min_rating 参数定义。例如，如果一个用户至少评价了4个物品，则称该用户为活跃用户（warm user）。

参数:

data (pyspark.sql.DataFrame) – 包含用户-物品元组的 DataFrame。DataFrame 中应包含用户和物品列，而评分、时间戳等其他列是可选的。
min_rating (int) – 用户或物品的最小评分数量。
filter_by (str) – “user” 或 “item”，取决于使用 min_rating 过滤的是用户还是物品。
col_user (str) – 用户ID列名。
col_item (str) – 物品ID列名。

返回:

根据给定规范过滤后的 DataFrame，至少包含用户和物品列。

返回类型:

pyspark.sql.DataFrame

recommenders.datasets.split_utils.process_split_ratio(ratio)[source]#

生成分割比例列表。

参数:

ratio (float 或 list) – 表示分割比例的浮点数或
ratios (表示分割比例的浮点数列表)

返回:

bool: 一个布尔变量 multi，指示分割是多部分还是单一部分。
list: 归一化后的分割比例列表。

返回类型:

tuple

recommenders.datasets.split_utils.split_pandas_data_with_ratios(data, ratios, seed=42, shuffle=False)[source]#

使用给定比例分割 pandas DataFrame 的辅助函数

注意

实现参考自此源。

参数:

data (pandas.DataFrame) – 要分割的 Pandas DataFrame。
ratios (list of floats) – 分割比例列表。比例之和必须为1。
seed (int) – 随机种子。
shuffle (bool) – 分割时是否打乱数据。

返回:

按给定规范分割后的 pd.DataFrame 列表。

返回类型:

list

稀疏工具#

class recommenders.datasets.sparse.AffinityMatrix(df, items_list=None, col_user='userID', col_item='itemID', col_rating='rating', col_pred='prediction', save_path=None)[source]#

从 pandas DataFrame 生成用户/物品亲和度矩阵，反之亦然

gen_affinity_matrix()[source]#

生成用户/物品亲和度矩阵。

第一步，将两个新列添加到输入 DF 中，包含由 gen_index() 方法生成的索引映射。然后，将新索引与评分一起，使用 scipy 的稀疏矩阵方法 coo_matrix 生成用户/物品亲和度矩阵；参考：https://docs.scipy.org.cn/doc/scipy/reference/generated/scipy.sparse.coo_matrix.html。输入格式为：coo_matrix((data, (rows, columns)), shape=(rows, columns))

返回:: 维度为 (Nusers, Nitems) 的用户亲和度矩阵，为 numpy 格式。未评分的电影被赋值为 0。
返回类型:: scipy.sparse.coo_matrix

map_back_sparse(X, kind)[source]#

将用户/亲和度矩阵映射回 pd DataFrame

参数:

X (numpy.ndarray, int32) – 用户/物品亲和度矩阵
kind (string) – 指定输出值是评分还是预测

返回:

生成的 pandas DataFrame

返回类型:

pandas.DataFrame

知识图工具#

recommenders.datasets.wikidata.get_session(session=None)[source]#

获取会话对象

参数:: session (requests.Session) – 请求会话对象
返回:: 请求会话对象
返回类型:: requests.Session

recommenders.datasets.wikidata.log_retries(func)[source]#

记录重试尝试的装饰器。必须应用于 @retry 装饰器*之后*。

使用示例: @retry(wait_random_min=1000, wait_random_max=5000, stop_max_attempt_number=3) @log_retries def my_function()

函数实现通过

recommenders.datasets.wikidata.read_linked_entities(data)[source]#

从字典中获取关联实体列表（ID和名称）

参数:

data (json) – 包含关联页面的字典

返回:

关联实体ID列表。
关联实体名称列表。

返回类型:

list, list

recommenders.datasets.wikidata.search_wikidata(names, extras=None, describe=True)[source]#

创建 Wikidata 搜索结果的 DataFrame

参数:

names (list[str]) – 要搜索的名称列表
(dict(str (extras) – list)): 可选的额外项，用于分配给对应名称的结果
describe (bool) – 可选标志，用于包含实体的描述

返回:

所有找到实体的名称的 Wikidata 搜索结果

返回类型:

pandas.DataFrame

数据集模块

目录

数据集模块#

推荐数据集#

Amazon Reviews#

CORD-19#

Criteo#

MIND#

MovieLens#

下载工具#

Pandas 数据帧工具#

分割器工具#

Python 分割器#

PySpark 分割器#

其他分割器工具#

稀疏工具#

知识图工具#