foundryts.functions.cumulative_aggregate¶

foundryts.functions.cumulative_aggregate(aggregate)¶

Returns a function that computes the cumulative aggregate of all values in a single time series.

The cumulative aggregate is calculated progressively for each point in the input time series, considering all preceding points up to and including the current point.

Aggregation functions supported:

Aggregation function	Description
min	Smallest value up to the current point in the time series.
max	Largest value up to the current point in the time series.
count	Count of all points up to the current point in the time series.
sum	Sum of all point values up to the current point.
product	Product of point values up to the current point.
mean	Average of all point values up to the current point.
standard_deviation	Standard deviation of all point values up to the current point.
difference	Difference between the current point’s value and the first point’s value in the time series, providing the relative change within the series.
percent_change	Percent change between the current point’s value and the first point’s value in the time series, providing the relative rate of change within the series.
first	Value of the first point in the time series.
last	Value of the current (last) point in the time series.

Parameters: aggregate (str) – Aggregation function to apply on each point, use one of the values from Aggregation Function above.
Returns: A function that takes a single time series as input and computes the specified aggregate for each point, considering all preceding points up to the point being evaluated.
Return type: (FunctionNode) -> FunctionNode

Dataframe schema¶

Column name	Type	Description
timestamp	pandas.Timestamp	Timestamp of the point
value	Union[float, str]	Value of the point

:::callout{theme="success" title="See Also"} rolling_aggregate(), periodic_aggregate() :::

:::callout{theme="warning" title="Note"} This function is only applicable to numeric series. :::

Examples¶

>>> series = F.points(
...     (2, 10.0), (5, 20.0), (6, 30.0), (7, 40.0), (8, 50.0), (12, 60.0), name="series-1"
... )
>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   20.0
2 1970-01-01 00:00:00.000000006   30.0
3 1970-01-01 00:00:00.000000007   40.0
4 1970-01-01 00:00:00.000000008   50.0
5 1970-01-01 00:00:00.000000012   60.0

>>> cumulative_agg = F.cumulative_aggregate("mean")(series)
>>> cumulative_agg.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   15.0
2 1970-01-01 00:00:00.000000006   20.0
3 1970-01-01 00:00:00.000000007   25.0
4 1970-01-01 00:00:00.000000008   30.0
5 1970-01-01 00:00:00.000000012   35.0

中文翻译¶

foundryts.functions.cumulative_aggregate¶

foundryts.functions.cumulative_aggregate(aggregate)¶

返回一个函数，用于计算单个时间序列中所有值的累积聚合（cumulative aggregate）。

累积聚合会逐步计算输入时间序列中每个点的值，考虑从起点到当前点（含）的所有前置点。

支持的聚合函数：

聚合函数	描述
min	时间序列中截至当前点的最小值。
max	时间序列中截至当前点的最大值。
count	时间序列中截至当前点的所有点的计数。
sum	截至当前点的所有点值的总和。
product	截至当前点的所有点值的乘积。
mean	截至当前点的所有点值的平均值。
standard_deviation	截至当前点的所有点值的标准差。
difference	当前点值与时间序列中第一个点值之间的差值，反映序列内的相对变化。
percent_change	当前点值与时间序列中第一个点值之间的百分比变化，反映序列内的相对变化率。
first	时间序列中第一个点的值。
last	时间序列中当前（最后一个）点的值。

参数： aggregate (str) – 应用于每个点的聚合函数，请使用上方聚合函数中的值之一。
返回： 一个函数，接收单个时间序列作为输入，并为每个点计算指定的聚合值，考虑从起点到当前评估点的所有前置点。
返回类型： (FunctionNode) -> FunctionNode

数据框模式（Dataframe schema）¶

列名	类型	描述
timestamp	pandas.Timestamp	点的时间戳
value	Union[float, str]	点的值

:::callout{theme="success" title="另请参阅"} rolling_aggregate(), periodic_aggregate() :::

:::callout{theme="warning" title="注意"} 此函数仅适用于数值型序列。 :::

示例¶

>>> series = F.points(
...     (2, 10.0), (5, 20.0), (6, 30.0), (7, 40.0), (8, 50.0), (12, 60.0), name="series-1"
... )
>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   20.0
2 1970-01-01 00:00:00.000000006   30.0
3 1970-01-01 00:00:00.000000007   40.0
4 1970-01-01 00:00:00.000000008   50.0
5 1970-01-01 00:00:00.000000012   60.0

>>> cumulative_agg = F.cumulative_aggregate("mean")(series)
>>> cumulative_agg.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   15.0
2 1970-01-01 00:00:00.000000006   20.0
3 1970-01-01 00:00:00.000000007   25.0
4 1970-01-01 00:00:00.000000008   30.0
5 1970-01-01 00:00:00.000000012   35.0