statistics: 시간 구간별 통계 요약
foundryts.functions.statistics(start=None, end=None, window=None, **kwargs)
숫자형 시계열 하나를 구간으로 나누고 각 구간의 관측 수, 평균과 끝점 및 극값을 요약하는 함수를 반환합니다. FunctionNode를 입력으로 받아 SummarizerNode를 만듭니다.
인수
| 인수 | 형식 | 기본값과 의미 |
|---|---|---|
| start | int, datetime 또는 str | None. 통계를 계산할 시작 시각이며 포함 |
| end | int, datetime 또는 str | None. 통계를 계산할 마지막 시각이며 포함 |
| window | int, datetime 또는 str | None. 각 구간의 시간폭. 예: 100ns. 생략하면 전체 시계열 |
| include_std_dev | bool, 키워드 | False. True이면 표준편차 추가 |
| window_count | int, 키워드 | 시간 구간의 개수로 분할할 때 사용 |
window_count는 include_std_dev=True일 때만 적용하며 window보다 우선합니다. include_std_dev 없이 전달하면 window_count는 무시됩니다. window_count를 지정해도 각 구간에 같은 수의 관측이 들어가는 것은 아닙니다.
include_std_dev는 향후 표준편차가 기본 기능이 되면 사용 중단될 예정인 옵션입니다. 현재 동작에서는 기본값 False와 True의 차이를 유지합니다.
출력 스키마
각 구간의 요약을 한 행으로 반환합니다.
| 열 | 형식 | 의미 |
|---|---|---|
| count | int | 구간의 관측 수 |
| earliest_point.timestamp | datetime | 구간에서 첫 관측의 시각 |
| earliest_point.value | float | 첫 관측값 |
| latest_point.timestamp | datetime | 마지막 관측의 시각 |
| latest_point.value | float | 마지막 관측값 |
| smallest_point.timestamp | datetime | 최솟값 관측의 시각 |
| smallest_point.value | float | 최솟값 |
| largest_point.timestamp | datetime | 최댓값 관측의 시각 |
| largest_point.value | float | 최댓값 |
| mean | float | 관측값 평균 |
| start_timestamp | datetime | 통계 구간의 시작 경계 |
| end_timestamp | datetime | 통계 구간의 끝 경계 |
| standard_deviation | float | include_std_dev=True일 때 추가하는 표준편차 |
start_timestamp와 end_timestamp는 구간의 경계이며, 실제 첫 관측과 마지막 관측의 시각은 earliest_point와 latest_point에서 확인합니다.
가상 입력
import foundryts.functions as F
series = F.points(
(1, 8.0),
(101, 4.0),
(200, 2.0),
(201, 1.0),
(299, 35.0),
(300, 16.0),
(350, 32.0),
(1000, 64.0),
)
아래 표의 시각은 모두 Unix epoch 이후 나노초입니다. DataFrame에서는 datetime 계열의 시각 값으로 표시합니다.
시간폭 100나노초
stats = F.statistics(window="100ns")(series)
stats_df = stats.to_pandas()
예제는 관측이 있는 다섯 구간을 반환합니다. 구간별 관측 배치는 [시작, 끝) 형태이며, 시각 200의 관측은 200부터 300 직전까지의 구간에 들어갑니다. 이는 start와 end 인수로 지정하는 전체 평가 범위와 구분합니다.
표준편차도 필요하면 다음 노드를 평가합니다.
stats_with_std_dev = F.statistics(
window="100ns", include_std_dev=True
)(series)
std_dev_df = stats_with_std_dev.to_pandas()
| start_timestamp(ns) | end_timestamp(ns) | count | mean | standard_deviation(True일 때) |
|---|---|---|---|---|
| 0 | 100 | 1 | 8.0 | 0.0 |
| 100 | 200 | 1 | 4.0 | 0.0 |
| 200 | 300 | 3 | 12.666667 | 15.797327 |
| 300 | 400 | 2 | 24.0 | 8.0 |
| 1000 | 1100 | 1 | 64.0 | 0.0 |
같은 다섯 행의 관측 정보는 다음과 같습니다. 각 쌍은 (timestamp ns, value)입니다.
| 구간 시작(ns) | earliest_point | latest_point | smallest_point | largest_point |
|---|---|---|---|---|
| 0 | (1, 8.0) | (1, 8.0) | (1, 8.0) | (1, 8.0) |
| 100 | (101, 4.0) | (101, 4.0) | (101, 4.0) | (101, 4.0) |
| 200 | (200, 2.0) | (299, 35.0) | (201, 1.0) | (299, 35.0) |
| 300 | (300, 16.0) | (350, 32.0) | (300, 16.0) | (350, 32.0) |
| 1000 | (1000, 64.0) | (1000, 64.0) | (1000, 64.0) | (1000, 64.0) |
구간 개수 세 개
fixed_count_stats = F.statistics(
include_std_dev=True, window_count=3
)(series)
fixed_count_df = fixed_count_stats.to_pandas()
이 가상 예제의 경계는 1, 335, 669와 1003나노초이며 구간별 관측 수는 6, 1과 1입니다.
| start_timestamp(ns) | end_timestamp(ns) | count | mean | standard_deviation |
|---|---|---|---|---|
| 1 | 335 | 6 | 11.0 | 11.83216 |
| 335 | 669 | 1 | 32.0 | 0.0 |
| 669 | 1003 | 1 | 64.0 | 0.0 |
| 구간 시작(ns) | earliest_point | latest_point | smallest_point | largest_point |
|---|---|---|---|---|
| 1 | (1, 8.0) | (300, 16.0) | (201, 1.0) | (299, 35.0) |
| 335 | (350, 32.0) | (350, 32.0) | (350, 32.0) | (350, 32.0) |
| 669 | (1000, 64.0) | (1000, 64.0) | (1000, 64.0) | (1000, 64.0) |
숫자형 값의 분포는 distribution, 두 시계열 값의 관계는 scatter로 분석할 수 있습니다. 통계 요약을 평가하는 다른 출력 형식은 SummarizerNode를 참고합니다.