time series tutorial では、statsmodelsについてあまり解説がありません。英語圏の方は直接公式ドキュメントをよむと良いのですが、日本語での資料が不足しています。tutorial 解説からは少し離れていますが、tutorial で使用した関数については日本語の訳を載せます。私のつたない日本語訳ですので、プルリクをいただけたら幸いです。

クラス statsmodels.tsa.deterministic.CalendarFourier(freq, order)

カレンダー時刻に基づいたフーリエ級数による決定論的項を生成するクラスです。

引数

freq : str
pandas の頻度に変換可能な文字列 (例: "D" (日次), "M" (月次))。

order : int
使用するフーリエ成分の数。周期の2倍以下である必要があります。

属性

freq
決定論的項の周期。

is_dummy
生成される値がダミー変数 (0 または 1) かどうかを示すフラグ。

order
使用するフーリエ項の次数。

関連項目

DeterministicProcess: 決定論的過程を扱うための一般的なクラス
CalendarTimeTrend: カレンダー時刻に基づいたトレンド項を生成
CalendarSeasonality: カレンダー時刻に基づいた季節性項を生成
Fourier: フーリエ級数による決定論的項を生成 (CalendarFourier はこれをカレンダー時刻に特化したもの)

注釈

次数 order に対して、各次数 i (1 から order まで) について、サイン項とコサイン項の両方が生成されます。

数式は以下の通りです。

ここで、m は周期の長さ、
t_norm は正規化された時刻です。例えば、freq が "D" (日次) で、タイムスタンプが 12:00:00 の場合、t_norm は 0.5 となります (12時間 / 24時間 = 0.5)。

使用例

ここでは、不規則な間隔で取得された時間単位のデータをシミュレートし、そのデータに対するカレンダーフーリエ項を作成します。

import numpy as np
import pandas as pd
base = pd.Timestamp("2020-1-1")
gen = np.random.default_rng()
gaps = np.cumsum(gen.integers(0, 1800, size=1000))  # 0から1800秒のランダムな間隔を生成
times = [base + pd.Timedelta(gap, unit="s") for gap in gaps]  # 基準時刻に間隔を加算してタイムスタンプを生成
index = pd.DatetimeIndex(pd.to_datetime(times))  # タイムスタンプをインデックスに変換

from statsmodels.tsa.deterministic import CalendarFourier
cal_fourier_gen = CalendarFourier("D", 2)  # 日次周期で次数2のフーリエ項を生成cal_fourier_gen.in_sample(index)  # インデックスに基づいたサンプル内データに対するフーリエ項を生成

メソッド

in_sample(index)

与えられた index (DatetimeIndex) に対して、サンプル内データ用の決定論的トレンドを生成します。

out_of_sample(steps, index[, forecast_index])

サンプル外データ用の決定論的トレンドを steps 分だけ生成します。index は既存のデータ、forecast_index は予測対象期間のインデックス (省略可能)。

プロパティ

freq

決定論的項の周期。
is_dummy

生成される値がダミー変数 (0 または 1) かどうかを示すフラグ。
order

使用するフーリエ項の次数。

細かい解説、用語の確認

決定論的項 (deterministic terms):
確率的な変動を含まない、確定的な値を持つ項。CalendarFourier で生成されるフーリエ項は、時刻が決まれば一意に値が決まるため、決定論的項です。
フーリエ級数 (Fourier series): 周期関数を、サイン波とコサイン波の和で表現する方法。次数を増やすことで、任意の周期関数を近似できます。
カレンダー情報に基づく周期性: 一般的なフーリエ級数とは異なり、CalendarFourier は「日次」「月次」といったカレンダー情報に基づいて周期を定義します。これにより、例えば「毎週月曜日に特定のパターンが見られる」といった、現実世界の周期性をより正確に捉えることができます。
freq パラメータ: freq パラメータで周期の単位を指定します。これは pandas の frequencies (例: "D" (日次), "W" (週次), "M" (月次) など) に準拠しています。
order パラメータ: order パラメータでフーリエ級数の次数を指定します。次数が高いほど、より複雑な周期パターンを表現できますが、過学習のリスクも高まります。
正規化された時刻 (t_norm): 時刻は周期の長さで正規化されます。これにより、周期の異なるデータに対しても、フーリエ項を統一的に扱うことができます。
in_sample と out_of_sample メソッド: in_sample は既存のデータに対するフーリエ項を生成し、out_of_sample は未来の予測期間に対するフーリエ項を生成します。
サンプル内 (in-sample) / サンプル外 (out-of-sample):
モデルの学習に使用されるデータを「サンプル内データ」、学習に使用されず、モデルの予測性能を評価するために使用されるデータを「サンプル外データ」と呼びます。