distribution: 관측값의 분포

foundryts.functions.distribution(
    start=None, end=None, start_value=None, end_value=None, bins=None
)

숫자형 시계열 하나 또는 여러 개의 값을 같은 폭의 버킷으로 나누어 관측 수를 구하는 함수를 반환합니다. 여러 입력을 전달하면 모든 입력의 관측을 함께 집계합니다. 같은 값이 여러 점에 나타나면 각 관측을 셉니다.

입력은 FunctionNode 또는 NodeCollection이며 반환값은 SummarizerNode입니다. 범주형 시계열에는 적용하지 않습니다.

인수와 범위

인수	형식	동작
start	int, datetime 또는 str	포함하는 시작 시각. 기본 None이면 입력의 전체 시간 범위 사용
end	int, datetime 또는 str	제외하는 종료 시각. 기본 None이면 입력의 전체 시간 범위 사용
start_value	float	포함하는 값의 하한. 기본 None이면 모든 입력의 최솟값을 기준으로 설정
end_value	float	제외하는 값의 상한. 기본 None이면 모든 입력의 최댓값을 기준으로 설정
bins	int	버킷 수. None으로 생략하면 10개

버킷 폭 delta는 설정한 값 범위의 폭을 버킷 수로 나눈 값입니다. 모든 관측을 자동 범위로 집계할 때와 상한 end_value를 직접 지정할 때를 구분합니다. 예제의 자동 범위는 최대 관측값도 집계합니다.

출력 스키마

열	형식	의미
start_timestamp	datetime	계산 시간 범위의 시작
end_timestamp	datetime	계산 시간 범위의 끝, 제외
start	float	값 범위의 시작
end	float	값 범위의 끝
delta	float	모든 버킷에 공통인 폭
distribution_values.start	float	버킷 시작 값
distribution_values.end	float	버킷 끝 값
distribution_values.count	int	해당 버킷의 관측 수

가상 입력

두 시계열의 관측 시각은 나노초입니다.

from foundryts import NodeCollection
import foundryts.functions as F

series_1 = F.points(
    (1, 0.0),
    (101, 10.2),
    (200, 11.3),
    (201, 11.1),
    (299, 11.2),
    (300, 12.0),
    (400, 11.7),
    (500, 16.0),
    (123450, 11.8),
    name="series-1",
)
series_2 = F.points(
    (1, 0.5),
    (101, 0.2),
    (200, 1.3),
    (201, 0.1),
    (299, 1.2),
    (300, 1.4),
    (400, 1.0),
    (500, 2.0),
    (123450, 1.0),
    name="series-2",
)
collection = NodeCollection(series_1, series_2)

시계열 하나의 세 버킷

single_distribution = F.distribution(bins=3)(series_1)
single_df = single_distribution.to_pandas()

가상 결과의 값 범위는 0부터 16이며 delta는 약 5.333333입니다.

distribution_values.start	distribution_values.end	distribution_values.count
0.0	5.333333	1
5.333333	10.666667	1
10.666667	16.0	7

각 행의 start는 0.0, end는 16.0입니다. 예제의 공통 시간 메타데이터는 start_timestamp가 1677-09-21 00:12:43.145225216, end_timestamp가 2262-01-01 00:00:00입니다. 이 값은 각 실제 관측의 첫 시각이나 마지막 시각과 구분합니다.

여러 시계열을 함께 집계

combined_distribution = F.distribution(bins=3)(collection)
combined_df = combined_distribution.to_pandas()

series-2의 아홉 관측은 모두 첫 버킷에 들어갑니다. 값이 1.0인 두 관측도 각각 집계하므로 첫 버킷은 10개입니다.

distribution_values.start	distribution_values.end	distribution_values.count
0.0	5.333333	10
5.333333	10.666667	1
10.666667	16.0	7

delta, start, end와 시간 메타데이터는 위 단일 시계열 예제와 같습니다. 시계열마다 분포를 따로 만들려면 NodeCollection.map을 사용합니다. 통계 요약은 statistics, 두 시계열의 대응 값은 scatter에서 다룹니다.