time_weighted: 시간이 반영된 집계 명세

foundryts.functions.time_weighted(
    aggregate, method='linear', bounds_interpolation=None
)

TimeWeightedSpec을 반환하여 cumulative_aggregate, rolling_aggregate 또는 periodic_aggregate의 aggregate 인수로 전달합니다. 이 함수 자체는 시계열을 입력받아 평가하는 함수가 아닙니다.

일반 평균은 점마다 같은 가중치를 주지만 시간 가중 집계는 인접 점 사이의 곡선을 적분하여 값이 유지되는 시간을 반영합니다. 불규칙하게 기록한 숫자형 센서 값이나 다음 갱신까지 유지되는 숫자형 상태값에 사용할 수 있습니다. 입력 시계열은 숫자형으로 제한됩니다.

집계와 적분 방법

method는 다음 소문자 String 중 하나이며 기본값은 linear입니다.

구간 경계 보간

bounds_interpolation의 기본값은 None입니다. 이 경우 구간 내부 관측점 사이의 넓이만 집계하고 경계와 가장 가까운 내부 관측 사이의 빈 부분은 제외합니다. 관측 시각과 집계 경계가 일치하지 않으면 경계 부근의 넓이가 빠질 수 있습니다.

경계까지의 곡선도 계산하려면 다음 String 전략을 선택합니다.

일반 보간의 default는 범주형에 previous를 사용하지만 시간 가중 집계 API는 숫자형 시계열에만 적용합니다. 보간 전략의 의미는 시계열 보간에 설명되어 있습니다.

가상 입력

import foundryts.functions as F

series = F.points(
    (1, 5.0),
    (3, 15.0),
    (6, 30.0),
    name="series",
)

정수 시각은 나노초입니다. 첫 간격은 2나노초이고 두 번째 간격은 3나노초입니다.

누적 시간 가중 평균

cumulative_average = F.cumulative_aggregate(
    F.time_weighted("average")
)(series)
cumulative_df = cumulative_average.to_pandas()

기본 linear 적분을 사용합니다. 시각 6까지의 넓이는 (5 + 15) / 2 × 2 + (15 + 30) / 2 × 3 = 87.5이며 값×나노초 단위입니다. 이를 5나노초로 나누면 17.5가 됩니다.

첫 시각에는 첫 관측값 5.0을 반환하는 예입니다.

5나노초 이동 구간의 RHS 적분

rolling_integral = F.rolling_aggregate(
    F.time_weighted("integral", method="rhs"), "5ns"
)(series)
rolling_df = rolling_integral.to_pandas()

bounds_interpolation을 지정하지 않아 구간 내부 점 사이만 적분합니다. 시각 3에서는 뒤쪽 값 15를 2나노초 동안 적용합니다. 시각 6의 이동 구간은 (1, 6]이므로 시각 1의 점이 빠지고 뒤쪽 값 30을 3나노초 동안 적용합니다.

적분 결과의 단위는 값×초입니다. 첫 시각에는 적분할 두 점이 없어 0입니다.

경계를 보간한 2나노초 주기 평균

periodic_average = F.periodic_aggregate(
    F.time_weighted("average", bounds_interpolation="linear"),
    "2ns",
)(series)
periodic_df = periodic_average.to_pandas()

• 끝 시각 2에서는 내부 관측 (1, 5.0)과 보간한 경계 (2, 10.0) 사이의 평균이 7.5입니다.
• 끝 시각 4에서는 경계값을 (2, 10.0)과 (4, 20.0)으로 보간하여 평균 15.0을 얻습니다.
• 끝 시각 6에서는 보간한 (4, 20.0)과 실제 관측 (6, 30.0)을 사용하여 평균 25.0을 얻습니다.

구간별 명세를 구성하지 않고 시계열 시작부터 누적 적분할 때는 integral도 사용할 수 있습니다.