【実装編】TimesFM-3の入力配列をPandasで作る｜shape確認とpredict・predict_batchの使い分け

context = 30日 × 24時間 = 720
horizon = 1日 × 24時間 = 24
context + horizon = 744

import numpy as np
import pandas as pd

DATA_PATH = "data/Tetuan City power consumption.csv"

ZONE_COLUMNS = [
    "Zone 1 Power Consumption",
    "Zone 2  Power Consumption",
    "Zone 3  Power Consumption",
]
WEATHER_COLUMNS = [
    "Temperature",
    "Humidity",
    "Wind Speed",
    "general diffuse flows",
    "diffuse flows",
]
VALUE_COLUMNS = ZONE_COLUMNS + WEATHER_COLUMNS

raw = pd.read_csv(DATA_PATH)
raw["date"] = pd.to_datetime(
    raw["DateTime"],
    format="%m/%d/%Y %H:%M",
    errors="raise",
)

missing_columns = set(VALUE_COLUMNS) - set(raw.columns)
if missing_columns:
    raise ValueError(f"必要な列がありません: {sorted(missing_columns)}")

indexed = (
    raw.set_index("date")[VALUE_COLUMNS]
    .apply(pd.to_numeric, errors="raise")
    .sort_index()
)

if not indexed.index.is_unique:
    raise ValueError("日時に重複があります")

expected_index = pd.date_range(
    start=indexed.index.min(),
    end=indexed.index.max(),
    freq="10min",
)
if not indexed.index.equals(expected_index):
    raise ValueError("10分間隔で連続していない日時があります")

counts = indexed.resample("1h").count()
if not counts.eq(6).all().all():
    raise ValueError("1時間あたり6観測でない区間があります")

hourly = indexed.resample("1h").mean()

if hourly.isna().any().any():
    missing = hourly.isna().sum()
    raise ValueError(f"1時間値に欠損があります:\n{missing[missing > 0]}")

if not np.isfinite(hourly.to_numpy(dtype=float)).all():
    raise ValueError("NaNまたは無限値が含まれています")

CONTEXT_LENGTH = 30 * 24
HORIZON = 24
forecast_start = pd.Timestamp("2017-02-01 00:00:00")

context_dates = pd.date_range(
    end=forecast_start - pd.Timedelta(hours=1),
    periods=CONTEXT_LENGTH,
    freq="1h",
)
forecast_dates = pd.date_range(
    start=forecast_start,
    periods=HORIZON,
    freq="1h",
)

missing_context = context_dates.difference(hourly.index)
if not missing_context.empty:
    raise ValueError(f"contextに存在しない日時があります: {missing_context[:5]}")

context_frame = hourly.loc[context_dates]

CALENDAR_COLUMNS = [
    "hour_sin",
    "hour_cos",
    "dow_sin",
    "dow_cos",
    "is_weekend",
]

def make_calendar_frame(index: pd.DatetimeIndex) -> pd.DataFrame:
    hour = index.hour.to_numpy()
    day_of_week = index.dayofweek.to_numpy()

    values = np.column_stack(
        [
            np.sin(2 * np.pi * hour / 24),
            np.cos(2 * np.pi * hour / 24),
            np.sin(2 * np.pi * day_of_week / 7),
            np.cos(2 * np.pi * day_of_week / 7),
            (day_of_week >= 5).astype(float),
        ]
    )

    return pd.DataFrame(
        values,
        index=index,
        columns=CALENDAR_COLUMNS,
        dtype=np.float32,
    )

all_dates = context_dates.append(forecast_dates)
calendar = make_calendar_frame(all_dates)

targets = (
    context_frame[ZONE_COLUMNS]
    .to_numpy(dtype=np.float32)
    .T
)
past_weather = (
    context_frame[WEATHER_COLUMNS]
    .to_numpy(dtype=np.float32)
    .T
)
known_calendar = (
    calendar[CALENDAR_COLUMNS]
    .to_numpy(dtype=np.float32)
    .T
)

expected_shapes = {
    "targets": (3, 720),
    "past_weather": (5, 720),
    "known_calendar": (5, 744),
}

arrays = {
    "targets": targets,
    "past_weather": past_weather,
    "known_calendar": known_calendar,
}

for name, array in arrays.items():
    assert array.shape == expected_shapes[name]
    assert array.dtype == np.float32
    assert np.isfinite(array).all()

python -m pip install "timesfm[torch]==3.0.2" "torch==2.14.1" "pandas==2.2.3" "numpy==2.1.3"

import platform
from importlib.metadata import version

from timesfm3 import TimesFM3Forecaster

MODEL_ID = "google/timesfm-3.0-pytorch"
MODEL_REVISION = "43046b85ec22d584a13f8098c2ed39c889e129c2"

print("Python:", platform.python_version())
print("timesfm:", version("timesfm"))
print("torch:", version("torch"))
print("pandas:", version("pandas"))
print("numpy:", version("numpy"))
print("OS:", platform.platform())

forecaster = TimesFM3Forecaster.from_pretrained(
    MODEL_ID,
    revision=MODEL_REVISION,
    device="cpu",  # 本記事ではMac上のCPU実行に固定
)

print("device:", forecaster.device)
print("model revision:", MODEL_REVISION)

Python: 3.11.16
timesfm: 3.0.2
torch: 2.14.1
pandas: 2.2.3
numpy: 2.1.3
OS: macOS-26.6-arm64-arm-64bit
device: cpu
model revision: 43046b85ec22d584a13f8098c2ed39c889e129c2

# target: 各要素はtargetsの1行を参照する1次元配列 (720,)
independent_contexts = [
    targets[i]
    for i in range(targets.shape[0])
]

# 共通の共変量は、同じ配列への参照をバッチ件数分並べる
independent_past_weather = [
    past_weather
    for _ in independent_contexts
]
independent_known_calendar = [
    known_calendar
    for _ in independent_contexts
]

independent_outputs = list(
    forecaster.predict_batch(
        contexts=independent_contexts,
        horizon=HORIZON,
        past_only_covariates=independent_past_weather,
        past_future_covariates=independent_known_calendar,
        return_quantiles=False,
        use_znorm=False,
        padding_mode="none",
    )
)

assert len(independent_outputs) == 3
assert all(out.forecast.shape == (24,) for out in independent_outputs)

print(
    "predict_batch:",
    [out.forecast.shape for out in independent_outputs],
)

predict_batch: [(24,), (24,), (24,)]

joint_output = forecaster.predict(
    context=targets,                         # (3, 720)
    horizon=HORIZON,
    past_only_covariates=past_weather,       # (5, 720)
    past_future_covariates=known_calendar,   # (5, 744)
    return_quantiles=False,
    use_znorm=False,
    padding_mode="none",
)

assert joint_output.forecast.shape == (3, 24)

print("predict:", joint_output.forecast.shape)

predict: (3, 24)