预处理 - Nixtla - TimeGPT 时序预测模型

id_time_grid

 id_time_grid (df:~DFType, freq:Union[str,int],
               start:Union[str,int,datetime.date,datetime.datetime]='per_s
               erie', end:Union[str,int,datetime.date,datetime.datetime]='
               global', id_col:str='unique_id', time_col:str='ds')

生成所有预期的 id 和时间组合。

	类型	默认值	详情
df	DFType		输入数据
freq	Union		序列频率
start	Union	per_serie	序列的初始时间戳。 * ‘per_serie’ 使用每个序列的第一个时间戳 * ‘global’ 使用数据中遇到的第一个时间戳 * 也可以是特定的时间戳或整数，例如 ‘2000-01-01’、2000 或 datetime(2000, 1, 1)
end	Union	global	序列的初始时间戳。 * ‘per_serie’ 使用每个序列的最后一个时间戳 * ‘global’ 使用数据中遇到的最后一个时间戳 * 也可以是特定的时间戳或整数，例如 ‘2000-01-01’、2000 或 datetime(2000, 1, 1)
id_col	str	unique_id	标识每个序列的列。
time_col	str	ds	标识每个时间戳的列。
返回值	DFType		包含预期 id 和时间的 Dataframe。

源

fill_gaps

 fill_gaps (df:~DFType, freq:Union[str,int],
            start:Union[str,int,datetime.date,datetime.datetime]='per_seri
            e',
            end:Union[str,int,datetime.date,datetime.datetime]='global',
            id_col:str='unique_id', time_col:str='ds')

强制 Dataframe 的开始和结束日期时间。

	类型	默认值	详情
df	DFType		输入数据
freq	Union		序列频率
start	Union	per_serie	序列的初始时间戳。 * ‘per_serie’ 使用每个序列的第一个时间戳 * ‘global’ 使用数据中遇到的第一个时间戳 * 也可以是特定的时间戳或整数，例如 ‘2000-01-01’、2000 或 datetime(2000, 1, 1)
end	Union	global	序列的初始时间戳。 * ‘per_serie’ 使用每个序列的最后一个时间戳 * ‘global’ 使用数据中遇到的最后一个时间戳 * 也可以是特定的时间戳或整数，例如 ‘2000-01-01’、2000 或 datetime(2000, 1, 1)
id_col	str	unique_id	标识每个序列的列。
time_col	str	ds	标识每个时间戳的列。
返回值	DFType		已填充间隙的 Dataframe。

df = pd.DataFrame(
    {
        'unique_id': [0, 0, 0, 1, 1],
        'ds': pd.to_datetime(['2020', '2021', '2023', '2021', '2022']),
        'y': np.arange(5),
    }
)
df

	unique_id	ds	y
0	0	2020-01-01	0
1	0	2021-01-01	1
2	0	2023-01-01	2
3	1	2021-01-01	3
4	1	2022-01-01	4

默认功能是采用当前的起始时间，并仅将结束日期扩展为所有序列的相同时间。

fill_gaps(
    df,
    freq='YS',
)

	unique_id	ds	y
0	0	2020-01-01	0.0
1	0	2021-01-01	1.0
2	0	2022-01-01	NaN
3	0	2023-01-01	2.0
4	1	2021-01-01	3.0
5	1	2022-01-01	4.0
6	1	2023-01-01	NaN

我们还可以指定 end='per_serie' 以仅填充每个序列内可能的间隙。

fill_gaps(
    df,
    freq='YS',
    end='per_serie',
)

	unique_id	ds	y
0	0	2020-01-01	0.0
1	0	2021-01-01	1.0
2	0	2022-01-01	NaN
3	0	2023-01-01	2.0
4	1	2021-01-01	3.0
5	1	2022-01-01	4.0

我们还可以指定未来的结束日期。

fill_gaps(
    df,
    freq='YS',
    end='2024',
)

	unique_id	ds	y
0	0	2020-01-01	0.0
1	0	2021-01-01	1.0
2	0	2022-01-01	NaN
3	0	2023-01-01	2.0
4	0	2024-01-01	NaN
5	1	2021-01-01	3.0
6	1	2022-01-01	4.0
7	1	2023-01-01	NaN
8	1	2024-01-01	NaN

我们可以将所有序列设置为在同一时间开始。

fill_gaps(
    df,
    freq='YS',
    start='global'
)

	unique_id	ds	y
0	0	2020-01-01	0.0
1	0	2021-01-01	1.0
2	0	2022-01-01	NaN
3	0	2023-01-01	2.0
4	1	2020-01-01	NaN
5	1	2021-01-01	3.0
6	1	2022-01-01	4.0
7	1	2023-01-01	NaN

我们还可以为所有序列设置一个共同的开始日期（可以早于它们当前的开始时间）。

fill_gaps(
    df,
    freq='YS',
    start='2019',
)

	unique_id	ds	y
0	0	2019-01-01	NaN
1	0	2020-01-01	0.0
2	0	2021-01-01	1.0
3	0	2022-01-01	NaN
4	0	2023-01-01	2.0
5	1	2019-01-01	NaN
6	1	2020-01-01	NaN
7	1	2021-01-01	3.0
8	1	2022-01-01	4.0
9	1	2023-01-01	NaN

如果时间是整数，则频率、开始和结束也必须是整数。

df = pd.DataFrame(
    {
        'unique_id': [0, 0, 0, 1, 1],
        'ds': [2020, 2021, 2023, 2021, 2022],
        'y': np.arange(5),
    }
)
df

	unique_id	ds	y
0	0	2020	0
1	0	2021	1
2	0	2023	2
3	1	2021	3
4	1	2022	4

fill_gaps(
    df,
    freq=1,
    start=2019,
    end=2024,
)

	unique_id	ds	y
0	0	2019	NaN
1	0	2020	0.0
2	0	2021	1.0
3	0	2022	NaN
4	0	2023	2.0
5	0	2024	NaN
6	1	2019	NaN
7	1	2020	NaN
8	1	2021	3.0
9	1	2022	4.0
10	1	2023	NaN
11	1	2024	NaN

该函数也接受 polars dataframes

df = pl.DataFrame(
    {
        'unique_id': [0, 0, 0, 1, 1],
        'ds': [
            datetime(2020, 1, 1), datetime(2022, 1, 1), datetime(2023, 1, 1),
            datetime(2021, 1, 1), datetime(2022, 1, 1)],
        'y': np.arange(5),
    }
)
df

unique_id	ds	y
i64	datetime[μs]	i64
0	2020-01-01 00:00:00	0
0	2022-01-01 00:00:00	1
0	2023-01-01 00:00:00	2
1	2021-01-01 00:00:00	3
1	2022-01-01 00:00:00	4

polars_ms = fill_gaps(
    df.with_columns(pl.col('ds').cast(pl.Datetime(time_unit='ms'))),
    freq='1y',
    start=datetime(2019, 1, 1),
    end=datetime(2024, 1, 1),
)
assert polars_ms.schema['ds'].time_unit == 'ms'
polars_ms

unique_id	ds	y
i64	datetime[ms]	i64
0	2019-01-01 00:00:00	null
0	2020-01-01 00:00:00	0
0	2021-01-01 00:00:00	null
0	2022-01-01 00:00:00	1
0	2023-01-01 00:00:00	2
…	…	…
1	2020-01-01 00:00:00	null
1	2021-01-01 00:00:00	3
1	2022-01-01 00:00:00	4
1	2023-01-01 00:00:00	null
1	2024-01-01 00:00:00	null

df = pl.DataFrame(
    {
        'unique_id': [0, 0, 0, 1, 1],
        'ds': [
            date(2020, 1, 1), date(2022, 1, 1), date(2023, 1, 1),
            date(2021, 1, 1), date(2022, 1, 1)],
        'y': np.arange(5),
    }
)
df

unique_id	ds	y
i64	date	i64
0	2020-01-01	0
0	2022-01-01	1
0	2023-01-01	2
1	2021-01-01	3
1	2022-01-01	4

fill_gaps(
    df,
    freq='1y',
    start=date(2020, 1, 1),
    end=date(2024, 1, 1),
)

unique_id	ds	y
i64	date	i64
0	2020-01-01	0
0	2021-01-01	null
0	2022-01-01	1
0	2023-01-01	2
0	2024-01-01	null
1	2020-01-01	null
1	2021-01-01	3
1	2022-01-01	4
1	2023-01-01	null
1	2024-01-01	null

df = pl.DataFrame(
    {
        'unique_id': [0, 0, 0, 1, 1],
        'ds': [2020, 2021, 2023, 2021, 2022],
        'y': np.arange(5),
    }
)
df

unique_id	ds	y
i64	i64	i64
0	2020	0
0	2021	1
0	2023	2
1	2021	3
1	2022	4

fill_gaps(
    df,
    freq=1,
    start=2019,
    end=2024,
)

unique_id	ds	y
i64	i64	i64
0	2019	null
0	2020	0
0	2021	1
0	2022	null
0	2023	2
…	…	…
1	2020	null
1	2021	3
1	2022	4
1	2023	null
1	2024	null

API 参考

​id_time_grid

​fill_gaps

id_time_grid

fill_gaps