시계열 예측 라이브러리 Prophet 완전 가이드

시계열 예측 라이브러리 Prophet 완전 가이드

설명: Meta의 시계열 예측 라이브러리 Prophet 설치부터 핵심 개념(추세·계절성·휴일·변곡점), 교차검증/튜닝, 실전 팁과 코드 예제까지 한 번에 정리합니다.

---

소개

본 글은 시계열 예측 라이브러리 Prophet(구 fbprophet)에 대한 기술 가이드입니다. Prophet은 일/주/년 주기의 계절성과 휴일 효과를 더한 가산(additive) 모델을 기반으로 하며, 결측치·이상치·추세 변화에 비교적 강인합니다. Python과 R 양 언어를 지원하며, 파이프라인이 단순하고 빠르게 베이스라인을 만들 수 있다는 점이 장점입니다. ([GitHub][1], [facebook.github.io][2])

---

Prophet 개요

모델 철학

• 가산 모델:
  $y(t) = g(t) + s(t) + h(t) + \epsilon_t$

  • $g(t)$: 선형/로지스틱 추세(변곡점 자동 탐지)
  • $s(t)$: 연/주/일 계절성(포리에 급수)
  • $h(t)$: 휴일/특수일 효과
  • $\epsilon_t$: 오차(잔차)

• 강건성(Robustness): 결측치·이상치·추세 전환(변곡점)에 강하고, 여러 시즌이 있는 비즈니스 데이터(웹 트래픽, 매출, 수요 등)에 적합합니다. ([GitHub][1])

설치 및 버전 포인트

• Python: python -m pip install prophet (PyPI) 또는 conda install -c conda-forge prophet

  • v1.0부터 패키지명이 fbprophet → prophet으로 변경
  • v1.1부터 최소 Python 3.7 이상

• Stan 백엔드: v1.1에서 Python 패키지가 pystan2 → cmdstan + cmdstanpy로 전환되었고, 기본적으로 고정 버전의 cmdstan을 다운로드/사용합니다(원격 환경에서도 설치가 쉬워짐). ([facebook.github.io][3], [GitHub][1])

---

빠른 시작(파이썬)

import pandas as pd
from prophet import Prophet

# 1) 데이터: 두 컬럼(ds: 날짜, y: 타깃값)
df = pd.read_csv("sales_daily.csv")  # ds, y
df['ds'] = pd.to_datetime(df['ds'])

# 2) 모델 구성
m = Prophet(
    seasonality_mode="additive",       # 또는 "multiplicative"
    changepoint_prior_scale=0.05,      # 추세 유연성
    interval_width=0.95                # 불확실성 구간
)

# (선택) 내장 휴일 추가
m.add_country_holidays(country_name='US')  # 한국은 직접 휴일 DF 구성 권장

# (선택) 사용자 정의 계절성
m.add_seasonality(name='monthly', period=30.5, fourier_order=5)

# 3) 학습
m.fit(df)

# 4) 미래 데이터프레임 생성 + 예측
future = m.make_future_dataframe(periods=90, freq='D')  # 90일 예측
forecast = m.predict(future)

# 5) 시각화
fig1 = m.plot(forecast)
fig2 = m.plot_components(forecast)

• 데이터 형식: ds(datetime), y(float) 필수
• make_future_dataframe로 예측 지평(horizon)만큼 미래 시점을 생성
• plot_components에서 추세·연/주/일 계절성·휴일 기여도를 분해 확인

---

핵심 구성요소와 튜닝

1) 추세(Trend) & 변곡점(Changepoints)

• Prophet은 초기 구간에서 후보 변곡점을 균등 간격으로 생성하고, **변곡점 사전 확률(prior)**로 추세의 유연성을 제어합니다.

• 주요 파라미터

  • n_changepoints: 후보 변곡점 수(기본 25)
  • changepoint_prior_scale: 추세의 유연성(↑ 크면 과적합 위험, ↓ 크면 과소적합 위험)
  • changepoint_range: 변곡점 탐색을 과거 히스토리의 몇 %까지로 제한(기본 0.8)

• 실무 팁: 예측이 지나치게 “구불구불”하면 changepoint_prior_scale을 줄이고, 추세 전환을 놓친다면 키워봅니다. 교차검증으로 최적값을 찾는 게 안전합니다. ([facebook.github.io][4])

2) 계절성(Seasonality)

• 연(yearly_seasonality), 주(weekly_seasonality), 일(daily_seasonality)을 자동/수동 제어

• add_seasonality(name, period, fourier_order)로 커스텀 주기 추가 가능

• 모드 선택: seasonality_mode="additive"(기본) 또는 "multiplicative"

  • 데이터가 규모가 커질수록 변동폭이 커지는 타입이면 multiplicative가 자연스러울 수 있습니다.

3) 휴일/이벤트(Holidays)

• add_country_holidays(country_name='US')로 국가별 내장 휴일을 손쉽게 포함할 수 있고, 사용자 정의 휴일 DF를 넘겨 세밀 제어가 가능합니다. 한국의 경우 실제 영업 영향력이 있는 법정 공휴일·대체휴일·프로모션 시작/마감일 등을 수동으로 설계하는 게 일반적으로 더 잘 맞습니다. ([facebook.github.io][5])

4) 불확실성(Interval)

• interval_width로 예측 구간(기본 0.80)을 조절합니다. 의사결정 임계값(예: 재고 안전재고)과 맞춰 세팅합니다.

5) 스케일링/기타(최근 변경)

• v1.1.5부터 scaling 인자가 도입되어, 타깃 y 스케일링 방식을 'absmax'(기본) 또는 **'minmax'**로 선택할 수 있습니다. Apple 실리콘/NumPy 2.0 대응 등 성능/호환성 업데이트도 계속됩니다. ([GitHub][1])

---

교차검증과 성능평가

Prophet은 시계열 전용 롤링 기반 교차검증 유틸리티를 제공합니다.

from prophet.diagnostics import cross_validation, performance_metrics
from prophet.plot import plot_cross_validation_metric

df_cv = cross_validation(
    m, 
    horizon='30 days',    # 예측 지평
    period='15 days',     # 컷오프 간격
    initial='365 days'    # 최초 학습 구간(기본값: 3*horizon)
)
df_pm = performance_metrics(df_cv)  # rmse, mae, mape 등
fig = plot_cross_validation_metric(df_cv, metric='rmse')

• cross_validation은 여러 컷오프를 자동 생성하고, performance_metrics로 RMSE/MAE/MAPE/coverage 등을 집계합니다. 지평·초기학습·컷오프 간격은 업무 맥락에 맞춰 설정합니다. ([facebook.github.io][6])

---

실전 설계 체크리스트

데이터/전처리

• 최소 2~3 시즌 이상의 히스토리 확보가 이상적(연 계절성이 있으면 2년+ 권장).
• 결측/이상치에 관대하지만, 명백한 오류는 사전에 보정하는 것이 안전.
• 프로모션/가격/마케팅 지표 등 외생 변수는 add_regressor로 추가해 설명력 향상을 시도.

모델링 전략

• 변곡점 튜닝: changepoint_prior_scale 그리드 서치(+교차검증)로 과대/과소적합 균형을 탐색.
• 계절성 분해 검증: plot_components로 과·소적합 여부를 시각적으로 점검.
• 휴일 설계: 내장 휴일 + 도메인 이벤트(런칭/세일/파업/날씨 등)를 병행.

배포/운영

• 데이터 누수 방지(피처 생성 시점 주의).
• 예측 지평별(7/30/90일) 성능 프로파일 관리.
• 월/분기 집계(Resample)와 함께 Prophet의 Non-daily data 가이드를 참고. ([facebook.github.io][3])

---

자주 쓰는 파라미터 요약

구분	파라미터	의미/팁
추세	growth	"linear"(기본) / "logistic" (cap/floor 필요)
추세	n_changepoints	후보 변곡점 수(기본 25)
추세	changepoint_prior_scale	추세 유연성(↑크면 더 유연)
추세	changepoint_range	변곡점 탐색 구간 비율(기본 0.8)
계절성	yearly_seasonality/weekly_seasonality/daily_seasonality	자동/정수/불린
계절성	seasonality_mode	"additive" / "multiplicative"
계절성	add_seasonality	커스텀 주기(예: 월간 30.5일)
휴일	add_country_holidays	국가 휴일 추가(내장)
불확실성	interval_width	예측구간(기본 0.80)
기타	scaling	'absmax'(기본) / 'minmax' (v1.1.5+) ([facebook.github.io][4], [GitHub][1])

---

예시: 로지스틱 성장 + 바닥/상한 + 외생변수

import pandas as pd
from prophet import Prophet

df = pd.read_csv("signup_daily.csv")  # ds, y, promo_spend
df['ds'] = pd.to_datetime(df['ds'])
df['cap'] = 50000     # 상한
df['floor'] = 0       # 바닥

m = Prophet(
    growth="logistic",
    seasonality_mode="multiplicative",
    changepoint_prior_scale=0.1,
    interval_width=0.9
)

# 외생변수(광고비)
m.add_regressor('promo_spend', prior_scale=10.0, mode='additive')

# 휴일(사용자 정의)
holidays = pd.DataFrame({
    'holiday': ['BlackFriday', 'CyberMonday'],
    'ds': pd.to_datetime(['2025-11-28', '2025-12-01']),
    'lower_window': [-1, 0],
    'upper_window': [1, 0],
})
m.holidays = holidays

m.fit(df)

future = m.make_future_dataframe(periods=60, freq='D')
future['cap'] = 50000
future['floor'] = 0
future['promo_spend'] = some_forecast_of_spend  # 사전 시나리오 준비
forecast = m.predict(future)

---

Prophet과 다른 방법 비교/활용

• ARIMA/ETS: 시계열 통계모형은 해석가능성이 높고, 짧은 시계열에도 강점. Prophet은 **달력 기반 신호(연/주/휴일)**를 빠르게 얹어 현업 친화적 베이스라인을 만들기에 유리.
• 딥러닝/NeuralProphet: 더 복잡한 패턴/상호작용을 포착 가능하지만, 데이터/서빙 복잡도가 증가. Prophet으로 신속한 기준선을 만든 뒤 필요 시 고도화로 확장하는 접근을 권장.

---

결론(요약 정리)

Prophet은 달력 신호에 강한 가산형 시계열 모델로, 간결한 API와 교차검증 도구를 통해 빠르게 안정적인 베이스라인을 구축하는 데 유용합니다. 변곡점·계절성·휴일·외생변수의 가설 주도 튜닝이 성패를 가릅니다. 최신 버전(v1.1.x)은 cmdstan 기반으로 설치/호환성이 개선되었고, scaling 등 실무 친화 업데이트도 포함되어 있습니다. 핵심은 도메인 지식으로 피처링과 제약을 설계하고, 교차검증으로 객관적 성능을 관리하는 것입니다. ([GitHub][1], [facebook.github.io][6])

---

참고 자료

• Installation & Docs: Prophet 공식 문서(설치/가이드/토픽) ([facebook.github.io][3])
• Model & Features: GitHub README/Changelog(1.1.x, cmdstan 전환, scaling 등) ([GitHub][1])
• Diagnostics/CV: Cross validation & 성능평가 가이드 ([facebook.github.io][6])
• Trend/Changepoints: 튜닝 가이드 ([facebook.github.io][4])
• Holidays: 내장 국가 휴일 사용법 ([facebook.github.io][5])