foundryts.functions.integral¶
foundryts.functions.integral(method='LINEAR')¶
Returns a function that calculates the per-second integral for a single time series.
For every point in the time series, (t_i, v_i), output a tick with the value equal to the integral of all
points up to that point (inclusive).
The integral is calculated using ↗ Reimann sums for estimation. The
integration uses the method in the argument where supported options are:
| Method | Description |
|---|---|
| LHS | Left-Hand Sum (LHS) approximates the integral by summing the values at the beginning of each interval. It tends to underestimate for increasing trends and overestimate for decreasing trends. Assumes initial values are representative of the entire interval, useful when historical values strongly influence the total. |
| RHS | Right-Hand Sum (RHS) approximates the integral by summing the values at the end of each interval. It tends to overestimate for increasing trends and underestimate for decreasing trends. Assumes final values are indicative of the trend, useful when recent values are more reflective of the cumulative trend. |
| > LINEAR (default) |
Trapezoidal Rule averages the values at the start and end of each interval. It provides a balanced approximation, reducing overestimation or underestimation. Useful for fluctuating trends as it accounts for both early and recent values. |
- Parameters:
method (str , optional) – Method used to estimate the integral value for a given point, valid options listed in table above
(default is
LINEAR). - Returns: A function that accepts a single time series as input and returns a time series with per-second integral values.
- Return type:
(
FunctionNode) ->FunctionNode
Dataframe schema¶
| Column name | Type | Description |
|---|---|---|
| timestamp | pandas.Timestamp | Timestamp of the point |
| value | float | Value of the point |
:::callout{theme="warning" title="Note"} This function is only applicable to numeric series. :::
:::callout{theme="success" title="See Also"}
derivative()
:::
Examples¶
>>> series = F.points(
... (1000, 1.0), (3000, 3.0), (5000, 0.0), (6000, 5.0), (8000, -7.0),
... name="series"
... )
>>> series.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 1.0
1 1970-01-01 00:00:00.000003 3.0
2 1970-01-01 00:00:00.000005 0.0
3 1970-01-01 00:00:00.000006 5.0
4 1970-01-01 00:00:00.000008 -7.0
>>> linear_integral = F.integral(method="LINEAR")(series)
>>> linear_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000004
2 1970-01-01 00:00:00.000005 0.000007
3 1970-01-01 00:00:00.000006 0.000009
4 1970-01-01 00:00:00.000008 0.000007
>>> lhs_integral = F.integral(method="LHS")(series)
>>> lhs_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000002
2 1970-01-01 00:00:00.000005 0.000008
3 1970-01-01 00:00:00.000006 0.000008
4 1970-01-01 00:00:00.000008 0.000018
>>> rhs_integral = F.integral(method="RHS")(series)
>>> rhs_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000006
2 1970-01-01 00:00:00.000005 0.000006
3 1970-01-01 00:00:00.000006 0.000011
4 1970-01-01 00:00:00.000008 -0.000003
中文翻译¶
foundryts.functions.integral¶
foundryts.functions.integral(method='LINEAR')¶
返回一个函数，用于计算单个时间序列的每秒积分（per-second integral）。
对于时间序列中的每个点 (t_i, v_i)，输出一个刻度（tick），其值等于截至该点（含该点）所有点的积分。
积分计算采用 ↗ 黎曼和 进行估算。积分使用参数中的 method，支持的选项如下：
| 方法 | 描述 |
|---|---|
| LHS | 左和（Left-Hand Sum, LHS）通过将每个区间起始点的值相加来近似积分。对于上升趋势容易低估，对于下降趋势容易高估。假设初始值能代表整个区间，适用于历史值对总量影响较大的场景。 |
| RHS | 右和（Right-Hand Sum, RHS）通过将每个区间结束点的值相加来近似积分。对于上升趋势容易高估，对于下降趋势容易低估。假设最终值能反映趋势，适用于近期值更能体现累积趋势的场景。 |
| > LINEAR （默认值） |
梯形法则（Trapezoidal Rule）对每个区间起始点和结束点的值取平均。它提供了一种平衡的近似方法，减少了高估或低估的情况。适用于波动趋势，因为它同时考虑了早期值和近期值。 |
- 参数：
method（str ， 可选）– 用于估算给定点积分值的方法，有效选项见上表
（默认值为
LINEAR）。 - 返回值： 一个函数，接受单个时间序列作为输入，并返回一个包含每秒积分值的时间序列。
- 返回类型：
(
FunctionNode) ->FunctionNode
数据框模式（Dataframe schema）¶
| 列名 | 类型 | 描述 |
|---|---|---|
| timestamp | pandas.Timestamp | 点的时间戳 |
| value | float | 点的值 |
:::callout{theme="warning" title="注意"} 此函数仅适用于数值型序列。 :::
:::callout{theme="success" title="另请参阅"}
derivative()
:::
示例¶
>>> series = F.points(
... (1000, 1.0), (3000, 3.0), (5000, 0.0), (6000, 5.0), (8000, -7.0),
... name="series"
... )
>>> series.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 1.0
1 1970-01-01 00:00:00.000003 3.0
2 1970-01-01 00:00:00.000005 0.0
3 1970-01-01 00:00:00.000006 5.0
4 1970-01-01 00:00:00.000008 -7.0
>>> linear_integral = F.integral(method="LINEAR")(series)
>>> linear_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000004
2 1970-01-01 00:00:00.000005 0.000007
3 1970-01-01 00:00:00.000006 0.000009
4 1970-01-01 00:00:00.000008 0.000007
>>> lhs_integral = F.integral(method="LHS")(series)
>>> lhs_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000002
2 1970-01-01 00:00:00.000005 0.000008
3 1970-01-01 00:00:00.000006 0.000008
4 1970-01-01 00:00:00.000008 0.000018
>>> rhs_integral = F.integral(method="RHS")(series)
>>> rhs_integral.to_pandas()
timestamp value
0 1970-01-01 00:00:00.000001 0.000000
1 1970-01-01 00:00:00.000003 0.000006
2 1970-01-01 00:00:00.000005 0.000006
3 1970-01-01 00:00:00.000006 0.000011
4 1970-01-01 00:00:00.000008 -0.000003