FCST Input and Artifacts

Updated 2024.05.05

데이터 준비

학습 데이터 준비

1. .csv 형태의 동일한 column들을 가진 Train set과 Inference set을 준비합니다. Train set은 단일 time series일 수도 있고 여러 개의 time series들의 집합일 수도 있습니다. 여러 개의 time series들의 집합인 경우, 각 time series를 구분하기 위한 groupkey_column이 필요합니다.
2. Forecasting은 do_validation을 수행할 시 Train set을 분할하여 Train set과 Validation set을 생성하고 Cross validation을 수행하므로 사용자는 input_chunk_length (예측에 활용되는 input timeseries 길이), forecast_periods (예측할 timesereis 길이), cv_numbers (cross validation 횟수)를 충분히 소화할 수 있는 길이의 데이터를 준비합니다.
3. Inference set도 단일 time series 또는 여러 time serieses의 집합일 수 있습니다. Inference set의 column들은 model 학습에 사용된 train set과 동일해야 합니다.
4. 예측 기간은 forecasting_periods로 주어지며, 예측 시작 시점은 기본적으로 inference set의 최종 시점 다음부터입니다. train set을 학습한 뒤, train set의 최종 시점 이후부터 forecasting을 실시하려면 train set을 inference set으로 사용합니다.예측의 시작 시점을 inference set의 그룹 별 가장 최대 시간 인덱스로 하기 위해 bizpreprocess asset의 global_padding_interpolation 기능을 활용하여 padding 시킨 후 진행한다.
5. time_format의 default 값은 "%Y-%m-%d"이고 이를 수정할 경우 readiness asset을 통해 time_column에 반영됩니다. 작성규칙은 여기를 참고해주세요.

• main.py 혹은 jupyter notebook을 실행하기 위해서는 아래 경로에 학습 데이터를 준비해야 합니다.

  • Train set 파일 저장 경로: ./sample_data/train_input_path/
  • Inference set 파일 저장 경로: ./sample_data/inference_input_path/

  input data directory 구조

  ./{train_folder}/
  	└ train_data1.csv
   	└ train_data2.csv
  	└ train_data3.csv
  ./{inference_folder}/
  	└ data_a.csv
   	└ data_b.csv

  train_sample.csv 예시 아래와 같이 프렌차이즈마다 음식이라는 정보를 참고로 하여 평균기온에 따라 매출이 얼마나 변화하는지 모델을 생성한다고 생각해봅시다. 각 각의 파라미터는 하기와 같고, 아래 예시에서는 3일을 학습(input_chunk_length)하고 3일을 예측(forecast_periods)하는 모델입니다.

  • y_column: 매출
  • time_column: time
  • time_format: "%Y-%m-%d"
  • sample_frequency: daily
  • groupkey_column: 프렌차이즈
  • static_covariates: 음식
  • x_covariates: 평균기온
  • input_chunk_length: 3
  • forecast_periods: 3

time	매출	프렌차이즈	음식	평균기온
2023-03-10	100	교촌xx	치킨	0
2023-03-11	150	교촌xx	치킨	-2
2023-03-12	120	BHx	치킨	5
...	...	...	...	...
2024-03-12	80	맥도날드	햄버거	4

inference_sample.csv 예시 input_chunk_length가 3이기 때문에 3일 이상 데이터 필요합니다. forecast_periods가 3이기 때문에 3/13 ~ 3/15 데이터가 생성됩니다.

time	매출	프렌차이즈	음식	평균기온
2024-03-10	95	교촌xx	치킨	5
2024-03-11	100	교촌xx	치킨	10
2024-03-12	150	교촌xx	치킨	8
...	...	...	...	...

---

데이터 요구사항

필수 요구사항

입력 데이터가 다음 조건을 만족할 시, 데이터의 재 처리가 필요합니다.

index	item	spec.
1	결측값 존재	결측 된 변수가 없어야 합니다. 결측값이 발생할 경우 정상 동작하지 않습니다.
2	결측 시점 존재	결측 된 시점이 없어야 합니다. interpolation을 통해 결측치를 자동보완하지만 정확한 예측을 위하여 결측구간이 없어야 합니다.
3	중복 시점 존재	각 Group 내 시점이 중복되어 출현할 경우 정상 동작하지 않습니다. 예를 들어 일별 예측인 경우 A 그룹에 3/14일 데이터가 2건 있으면 1건은 삭제됩니다.
4	New Group Key나 카테고리값 출현	Inference 시점에 새로 출현하는 Group Key나 카테고리값이 없어야 합니다. Label Encoder에 따라 정상동작하지 않을 수 있습니다.
5	학습 데이터 용량	1GB 이상의 데이터의 경우 정상동작하지 않을 수 있습니다.

추가 요구사항

안정적인 성능을 위한 조건입니다. 해당 조건이 부합할수록 예측의 품질이 좋을 확률이 높습니다.

index	item	spec.
1	계절성이 존재할 경우, 학습 데이터 내 계절성이 2-3번 이상 반복되는 것이 이상적입니다.	과소 접합
2	예측에 활용되는 데이터의 분포와 학습 데이터의 분포가 유사해야 합니다.	Data Shift
3	예측 시 데이터 내 결측이 존재하지 않아야 합니다.	결측값 보간으로 인한 예측 편향
4	명목 변수의 고유값이 너무 많지 않고 충분히 출현해야 합니다.	차원의 저주
5	종속변수의 분포가 정규분포를 이룰 경우 예측에 유리할 수 있습니다.	선형회귀의 가정
6	독립변수 간 상호 유사성이 적은것이 바람직 합니다.	다중공선성
7	독립변수와 종속변수 간 인과정보가 명확합니다.	인과정보
8	불필요한 독립변수는 제외하는 것이 바람직합니다.	허위상관

---

산출물(artifacts)

학습/추론을 실행하면 아래와 같은 산출물이 생성됩니다.

Train pipeline

./fcst/train_artifacts/
	└ models/
  	 	└ input/
		  	└ train_config.json
 		└ readiness/
	 		└ readiness_config.json
	 	└ bizpreprocess/
 		 	└ preprocess_config.json
	 		└ preprocess_scaler.pkl
	 		└ preprocess_categorical_encoder.pkl
 	 	└ train/
		  	└ train_config.json
			└ trained_nbeats.pt
			└ trained_nbeats.pt.ckpt
   	└ output/
		└ train_score.csv
	└ extra_output/
    	└ CV{k}.csv   

Inference pipeline

./fcst/inference_artifacts/
	└ output/
   		└ nbeats_prediction_result.csv
   	└ score/
		└ inference_summary.yaml

각 산출물에 대한 상세 설명은 다음과 같습니다.

trained_nbeats.pt

학습이 완료된 모델입니다.

trained_nbeats.pt.ckpt

학습이 완료된 모델의 checkpoint입니다.

train_score.csv

Cross Validation에 대한 성능이 저장된 파일입니다.

CV	train_perdiod	valid_period	mape	프렌차이즈
1	2022-01-01 ~ 2023-12-31	2024-01-01 ~ 2024-01-31	0.6	교촌xx
2	2022-01-01 ~ 2023-11-30	2023-12-01 ~ 2024-12-31	0.8	교촌xx
3	2022-01-01 ~ 2023-10-31	2023-11-01 ~ 2024-11-30	0.4	교촌xx
...	...	...	...	...

CV{k}.csv

각 CV에 대한 실제 값과 예측 값이 같이 저장된 파일입니다.

timestamp	매출	predicted	프렌차이즈
2024-02-29	95	92	교촌xx
2024-02-29	100	84	교촌xx
2024-02-29	150	149	교촌xx
...	...	...	...

nbeats_prediction_result.csv

학습된 모델을 통해 예측한 결과물입니다.

** nbeats_prediction_result.csv 예시**

timestamp	targetdate	매출	프렌차이즈
2024-02-29	2024-03-01	95	교촌xx
2024-02-29	2024-03-02	100	교촌xx
2024-02-29	2024-03-03	150	교촌xx
...	...	...	...

inference_summary.yaml

inference에 대한 요약이 저장된 파일입니다. 현재는 정보가 없이 default 값으로 저장됩니다.

---

Forecasting Version: 2.1.0