Darts库中时间序列日期属性索引方式的变更解析

背景介绍

Darts是一个强大的Python时间序列分析库，在0.28.0版本中对时间序列日期属性的处理方式进行了重要变更。这个变更影响了add_datetime_attribute方法的行为，将日期属性从1-based索引(从1开始)统一改为0-based索引(从0开始)。

变更详情

在Darts 0.27.2版本中，add_datetime_attribute方法生成的日期属性值与Pandas的DatetimeIndex保持一致：

• 月份(month)范围是1-12
• 日(day)范围是1-31
• 星期(weekday)范围是0-6

而在0.28.0版本中，所有日期属性都被调整为0-based索引：

• 月份(month)范围变为0-11
• 日(day)范围变为0-30
• 星期(weekday)保持0-6不变

变更原因

开发团队做出这一变更主要基于以下技术考虑：

1. 统一索引标准：Pandas中不同日期属性的索引方式不一致(有的从0开始，有的从1开始)，这给开发者带来了认知负担和潜在的错误风险。

2. 便于编码处理：0-based索引更符合编程惯例，特别在进行以下操作时更加方便：

   • 循环编码(cyclic encoding)
   • 独热编码(one-hot encoding)
   • 其他需要数值化处理的特征工程

3. 避免歧义：统一的索引方式减少了因属性索引方式不同而导致的潜在错误。

技术影响

这一变更会影响以下场景：

1. 特征工程：使用日期属性作为模型特征时，需要注意索引的偏移量变化。

2. 数据可视化：直接使用日期属性值作为标签时，显示的值会比实际少1。

3. 业务逻辑处理：如果业务代码中硬编码了特定的日期属性值，需要相应调整。

迁移建议

从旧版本迁移到0.28.0+版本时，开发者可以采取以下措施：

1. 检查依赖代码：查找所有直接使用日期属性值的代码，确认是否需要调整。

2. 添加转换层：对于需要保持1-based索引的场景，可以在使用前对属性值加1。

3. 更新文档：在项目文档中明确说明日期属性的索引方式。

最佳实践

虽然这一变更最初可能带来一些迁移成本，但从长期来看，统一的0-based索引方式更符合编程惯例，能够提高代码的一致性和可维护性。开发团队建议新项目直接采用新的索引方式，而现有项目可以在充分测试的基础上逐步迁移。