periodic_aggregate: 고정 주기별 집계

foundryts.functions.periodic_aggregate(
    aggregate, window, window_type='end', alignment_timestamp=0
)

숫자형 시계열 하나를 겹치지 않는 일정 길이의 구간으로 나누고 구간마다 집계값을 만드는 함수를 반환합니다. 입력과 출력은 FunctionNode입니다. 관측점이 없는 구간은 출력하지 않습니다.

인수와 경계

인수	형식과 의미	기본값
aggregate	집계 이름 String 또는 time_weighted의 반환 명세	필수
window	int, datetime.timedelta 또는 str 시간 길이. 예: 5ms	필수
window_type	start 또는 end	end
alignment_timestamp	결과 시각을 정렬할 기준 시각. 숫자, 시각 문자열 또는 datetime.datetime	0

정수 시간 길이는 나노초입니다. 결과 시각은 alignment_timestamp에서 window 길이의 정수배만큼 떨어진 지점에 놓입니다.

window_type	포함 범위	결과의 timestamp
start	시작 포함, 끝 제외: `[시작, 끝)`	구간 시작
end	시작 제외, 끝 포함: `(시작, 끝]`	구간 끝

집계 종류

aggregate	구간 안의 계산
min	최솟값
max	최댓값
count	관측 수
sum	값 합
product	값 곱
mean	관측값 평균
standard_deviation	관측값 표준편차
difference	마지막 값에서 첫 값을 뺀 차이
percent_change	첫 값을 기준으로 마지막 값의 변화 비율
first	첫 관측값
last	마지막 관측값
time_weighted("average")	값의 유지 시간을 반영한 구간 평균
time_weighted("integral")	구간의 곡선 아래 넓이

시간 가중 항목은 time_weighted가 반환한 명세를 aggregate에 전달합니다. 범주형 시계열은 지원하지 않습니다.

가상 입력

import foundryts.functions as F

series = F.points(
    (1, 1.0),
    (101, 2.0),
    (200, 4.0),
    (201, 8.0),
    (299, 16.0),
    (300, 32.0),
    (1000, 64.0),
    (12345, 128.0),
    name="series",
)

아래 표의 시각과 구간 경계는 모두 Unix epoch 이후 나노초입니다. 실제 DataFrame의 timestamp는 pandas.Timestamp로 표현됩니다.

기본 end 구간

periodic_difference = F.periodic_aggregate("difference", "100ns")(series)
periodic_change = F.periodic_aggregate("percent_change", "100ns")(series)
difference_df = periodic_difference.to_pandas()

window_type은 end, alignment_timestamp는 0입니다. 관측이 있는 다섯 구간만 출력합니다.

구간	포함된 입력 시각	출력 시각(ns)	difference	percent_change
(0, 100]	1	100	0.0	0.0
(100, 200]	101, 200	200	2.0	1.0
(200, 300]	201, 299, 300	300	24.0	3.0
(900, 1000]	1000	1000	0.0	0.0
(12300, 12400]	12345	12400	0.0	0.0

세 번째 구간은 첫 값 8과 마지막 값 32를 사용합니다. 차이는 24이고 변화 비율은 3, 즉 300%입니다. percent_change 결과가 필요하면 periodic_change를 평가합니다.

start 구간

start_aligned = F.periodic_aggregate(
    "percent_change", "100ns", window_type="start"
)(series)
start_df = start_aligned.to_pandas()

시작을 포함하는 경계로 바꾸면 시각 200의 점은 [200, 300)에 포함되고 시각 300의 점은 다음 구간으로 이동합니다.

구간	포함된 입력 시각	출력 시각(ns)	percent_change
[0, 100)	1	0	0.0
[100, 200)	101	100	0.0
[200, 300)	200, 201, 299	200	3.0
[300, 400)	300	300	0.0
[1000, 1100)	1000	1000	0.0
[12300, 12400)	12345	12300	0.0

기준 시각을 50으로 이동

shifted_alignment = F.periodic_aggregate(
    "percent_change", "100ns", alignment_timestamp=50
)(series)
aligned_df = shifted_alignment.to_pandas()

기본 end 경계를 유지하면서 구간 정렬 기준을 50나노초로 바꿉니다.

구간	포함된 입력 시각	출력 시각(ns)	percent_change
(-50, 50]	1	50	0.0
(50, 150]	101	150	0.0
(150, 250]	200, 201	250	1.0
(250, 350]	299, 300	350	1.0
(950, 1050]	1000	1050	0.0
(12250, 12350]	12345	12350	0.0

각 결과는 timestamp와 value 열을 가집니다. 공통 시계열 스키마의 value는 float 또는 str이지만 이 집계의 입력은 숫자형으로 제한됩니다. 현재 관측을 따라 움직이는 구간은 rolling_aggregate, 처음부터 누적하는 계산은 cumulative_aggregate를 사용합니다.

Keyboard shortcuts