• Documentation
    • Search documentation
    karat

    +

    K

    API Reference ↗
    Use case developmentFoundryTSAPI Referencefunctions.integral

    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:

    MethodDescription
    LHSLeft-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.
    RHSRight-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 nameTypeDescription
    timestamppandas.TimestampTimestamp of the point
    valuefloatValue of the point
    Note

    This function is only applicable to numeric series.

    See Also

    derivative()

    Examples

    Copied!
    1
2
3
4
5
6
7
8
9
10
11
>>> 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
    Copied!
    1
2
3
4
5
6
7
8
>>> 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
    Copied!
    1
2
3
4
5
6
7
8
>>> 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
    Copied!
    1
2
3
4
5
6
7
8
>>> 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