Favorita

​

辅助函数

这些辅助函数用于高效地创建和整理 Favorita 的时间序列。

​

Numpy 数据整理

​

numpy_balance

 numpy_balance (*arrs)

*快速的 NumPy 实现的‘balance’操作，可用于创建平衡面板数据集，即包含所有‘unique_id’和‘ds’交互的数据集。

参数
arrs: NumPy 数组。

返回
out: NumPy 数组。*

​

numpy_ffill

 numpy_ffill (arr)

*快速的 NumPy 实现的 ffill，通过向前传播最后一个非缺失值来填充数组中的缺失值。

例如，如果数组包含以下值
0 1 2 3
1 2 NaN 4

ffill 方法会按如下方式填充缺失值
0 1 2 3
1 2 2 4

参数
arr: NumPy 数组。

返回
out: NumPy 数组。*

​

numpy_bfill

 numpy_bfill (arr)

*快速的 NumPy 实现的 bfill，通过向后传播最后一个非缺失值来填充数组中的缺失值。

例如，如果数组包含以下值
0 1 2 3
1 2 NaN 4

bfill 方法会按如下方式填充缺失值
0 1 2 3
1 2 4 4

参数
arr: NumPy 数组。

返回： out: NumPy 数组。*

​

Pandas 数据整理

​

one_hot_encoding

 one_hot_encoding (df, index_col)

*对 dataFrame df 的分类变量进行编码，跳过 index_col。

参数
df: 包含分类列的 pd.DataFrame。
index_col: str，要避免编码的索引列。

返回： one_hot_concat_df: 包含独热编码分类列的 pd.DataFrame。
*

​

nested_one_hot_encoding

 nested_one_hot_encoding (df, index_col)

*对 dataFrame df 的分层嵌套分类变量进行编码，跳过 index_col。

嵌套分类变量（例如地理级别 国家>州），需要哑变量特征保留编码顺序，以反映分类变量的层次结构。

参数
df: 包含分层嵌套分类列的 pd.DataFrame。
index_col: str，要避免编码的索引列。

返回
one_hot_concat_df: 包含独热编码分层嵌套分类列的 pd.DataFrame。
*

​

get_levels_from_S_df

 get_levels_from_S_df (S_df)

*获取聚合约束数据框 S_df 所隐含的分层索引级别。

从求和矩阵（基础，底部）创建级别。遍历行直到所有底部级别序列被聚合约束“覆盖”，以发现块/层次结构级别。

参数
S_df: 大小为 (base, bottom) 的求和矩阵 pd.DataFrame，参见 aggregate 方法。

返回
levels: list，包含分层聚合索引，其中每个条目是一个级别。*

​

Favorita 数据集

​

Favorita 原始数据

​

FavoritaRawData

 FavoritaRawData ()

*Favorita 原始数据

Favorita 2018 Kaggle 竞赛的原始子集数据集。此类包含下载、加载和过滤数据集部分的实用工具。

如果您愿意，也可以直接从 Kaggle 下载原始数据集。
pip install kaggle --upgrade
kaggle competitions download -c favorita-grocery-sales-forecasting*

​

FavoritaRawData._load_raw_group_data

 FavoritaRawData._load_raw_group_data (directory, group, verbose=False)

*加载原始组数据。

读取、过滤和排序 Favorita 子集数据集。

参数
directory: str，数据将下载到的目录。
group: str，数据集组名，可以是‘Favorita200’、‘Favorita500’、‘FavoritaComplete’。
verbose: bool=False，是否打印部分输出。

返回
filter_items: 有序列表，包含 Favorita 子集中的唯一项目标识符。
filter_stores: 有序列表，包含 Favorita 子集中的唯一商店标识符。
filter_dates: 有序列表，包含 Favorita 子集中的日期。
raw_group_data: 字典，包含原始 Favorita pd.DataFrames，如 temporal, oil, items, store_info, holidays, transactions。
*

​

Favorita 原始数据使用示例

from datasetsforecast.favorita import FavoritaRawData

verbose = True
group = 'Favorita200' # 'Favorita500', 'FavoritaComplete'
directory = './data/favorita' # directory = f's3://favorita'

filter_items, filter_stores, filter_dates, raw_group_data = \
    FavoritaRawData._load_raw_group_data(directory=directory, group=group, verbose=verbose)
n_items  = len(filter_items)
n_stores = len(filter_stores)
n_dates  = len(filter_dates)

print('\n')
print('n_stores: \t', n_stores)
print('n_items: \t', n_items)
print('n_dates: \t', n_dates)
print('n_items * n_dates: \t\t',n_items * n_dates)
print('n_items * n_stores: \t\t',n_items * n_stores)
print('n_items * n_dates * n_stores: \t', n_items * n_dates * n_stores)

​

FavoritaData

​

FavoritaData

 FavoritaData ()

*Favorita 数据

经过处理的 Favorita 杂货店数据集包含商品日销售历史，以及有关促销、商品、商店和假期的附加信息，包含从 2013 年 1 月到 2017 年 8 月的 371,312 个时间序列，并具有州、城市和商店的地理层次结构。这种数据整理方式与 DPMN 论文中的一致。

• Kin G. Olivares, O. Nganba Meetei, Ruijun Ma, Rohan Reddy, Mengfei Cao, Lee Dicker (2022).”Probabilistic Hierarchical Forecasting with Deep Poisson Mixtures”. International Journal Forecasting, special issue.*

​

FavoritaData.load_preprocessed

 FavoritaData.load_preprocessed (directory:str, group:str,
                                 cache:bool=True, verbose:bool=False)

*加载 Favorita 组数据集。

为了探索更复杂的模型，我们提供了完整的信息，包括 Favorita 商店销售商品底层的详细数据，以及商品的聚合/国家级别信息。

参数
directory: str，数据将下载和保存的目录。
group: str，数据集组名，可以是‘Favorita200’、‘Favorita500’、‘FavoritaComplete’。
cache: bool=False, 如果为 True 则保存和加载。
verbose: bool=False，是否打印部分输出。

返回
static_bottom: pd.DataFrame，包含底部级别时间序列的静态变量。
static_agg: pd.DataFrame，包含聚合级别时间序列的静态变量。
temporal_bottom: pd.DataFrame，包含底部级别时间序列的时间变量。
temporal_agg: pd.DataFrame，包含聚合级别时间序列的时间变量。
*

​

FavoritaData.load

 FavoritaData.load (directory:str, group:str, cache:bool=True,
                    verbose:bool=False)

*加载 Favorita 预测基准数据集。

与其他分层数据集不同，此数据集包含每个独立杂货商品时间序列的地理层次结构，由 ‘item_id’ 列标识。地理层次结构由 ‘hier_id’ 列捕获。

因此需要少量数据整理以使其适用于 HierarchicalForecast 和 StatsForecast 库。

参数
directory: str，数据将下载和保存的目录。
group: str，数据集组名，可以是‘Favorita200’、‘Favorita500’、‘FavoritaComplete’。
cache: bool=False, 如果为 True 则保存和加载。
verbose: bool=False，是否打印部分输出。

返回
Y_df: pd.DataFrame，目标基础时间序列，包含列 [‘item_id’, ‘hier_id’, ‘ds’, ‘y’]。
S_df: pd.DataFrame，大小为 (base, bottom) 的分层约束数据框。
*

# #| hide
# #| eval: false
# # Test the equality of created and loaded datasets columns and rows
# static_agg1, static_bottom1, temporal_agg1, temporal_bottom1, S_df1 = \
#                         FavoritaData.load_preprocessed(directory=directory, group=group, cache=False)

# static_agg2, static_bottom2, temporal_agg2, temporal_bottom2, S_df2 = \
#                         FavoritaData.load_preprocessed(directory=directory, group=group)

# test_eq(len(static_agg1)+len(static_agg1.columns), 
#         len(static_agg2)+len(static_agg2.columns))
# test_eq(len(static_bottom1)+len(static_bottom1.columns), 
#         len(static_bottom2)+len(static_bottom2.columns))

# test_eq(len(temporal_agg1)+len(temporal_agg1.columns), 
#         len(temporal_agg2)+len(temporal_agg2.columns))
# test_eq(len(temporal_bottom1)+len(temporal_bottom1.columns), 
#         len(temporal_bottom2)+len(temporal_bottom2.columns))

​

Favorita 使用示例

# Qualitative evaluation of hierarchical data
from datasetsforecast.favorita import FavoritaData
from hierarchicalforecast.utils import HierarchicalPlot

group = 'Favorita200' # 'Favorita500', 'FavoritaComplete'
directory = './data/favorita'
Y_df, S_df, tags = FavoritaData.load(directory=directory, group=group)

Y_item_df = Y_df[Y_df.item_id==1916577] # 112830, 1501570, 1916577
Y_item_df = Y_item_df.rename(columns={'hier_id': 'unique_id'})
Y_item_df = Y_item_df.set_index('unique_id')
del Y_item_df['item_id']

hplots = HierarchicalPlot(S=S_df, tags=tags)
hplots.plot_hierarchically_linked_series(
    Y_df=Y_item_df, bottom_series='store_[40]',
)