agentleFS
yuisekiyuiseki/GeoAI-master-skills/.agents/skills/time-series-forecasting/SKILL.md

time-series-forecasting

Skill3 starsChanged yesterdayApache-2.0View on GitHub

多数の系列 (国、格子、地点ごとの月や年の値) の先の期間を、予測の距離 (1 か月先、12 か月先) ごとに当て、前の期間、季節ナイーブ、平年値と比べる。予測の時点を動かして、その時点より後の値を使わずに採点する。未来の値を当てる問いに使う。

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

time-series-forecasting

時系列の予測は、前の期間の値という強い基準に負けることが多い。基準を必ず並べる。過去の平均 (平年値) は、傾向のある系列では系統的にずれる。

reference読むとき中身
baselines基準を作るとき、いつも (手順 5 の前)前の期間、季節ナイーブ、平年値、縮めた前の期間
ets指数平滑を試すとき (手順 5 の前)指数平滑 (Holt-Winters)
lag-gbdt過去の値を特徴量にしたブースティングを試すとき (手順 5 の前)過去の値を特徴量にした勾配ブースティング
sarima季節 ARIMA を試すとき、差分の数を決めるとき (手順 5 の前)季節 ARIMA (既定は airline モデル)。差分の取りすぎの見分け方

TimesFM はまだ入っていない。

手順

  1. 何を、どの距離先まで当てるかを書く。予測を使う時点で何が分かっているか (前の月の値は分かっているか、発表の遅れ) も書く。
  2. 系列を揃える。1 期間 1 値で欠けが無いこと。事象の無い期間は 0 で埋める。季節の周期 (月なら 12) を決める。偏った量は対数を取る。
  3. モデルを作る前に、必ず、系列の水準の不連続と、データの版を調べる。scripts/forecast.py を使わず、自分のコードで予測するときも同じで、先に scripts/series_breaks.py を流し、その出力 (跳ねの一覧) を報告書の「データの確認」に貼る。跳ねが無いなら、無いと書く。scripts/series_breaks.py で、系列ごとの 1 期間の対数の変化が、その系列のふだんの変化から大きく外れた所を探す。合計の変化も、同じ系列だけを比べる形で出す。見つけた跳ねは、原因 (実際の出来事、データの改訂や定義の変更、系列の入れ替わり) を、「跳ねの原因を調べる」の順で調べて書き、予測の対象に含める、除く、頑健な基準で受ける、のどれにするかを決める。データが版ごとに改訂されるなら、過去の値が版の間でどれだけ変わるかを数える。現行の版を過去で切って評価しても、当時使えた値での予測の再現にはならない。
  4. 予測の時点を決める。最後の何期間を予測の時点にするか (--origins)。最後の期間だけで比べると、その期間の出来事に左右される。
  5. scripts/forecast.py で、基準とモデルを予測の距離ごとに採点する。最初に、跳ねの一覧が出る (手順 3 と同じもの)。
  6. 偏り (予測 − 実際の平均) を見る。0 から離れていたら、傾向やその期間の変化を取りこぼしている。
  7. 基準に勝たないモデルは採用しない。勝つなら、どの距離で、どれだけ勝つかを書く。
  8. 書き出す。
systemd-run --user --scope -q -p MemoryMax=8G -p MemorySwapMax=0 -p CPUQuota=400% -- \
  uvx --with numpy --with scipy --with scikit-learn --with statsmodels --with duckdb \
  python scripts/forecast.py tmp/series.parquet SERIES TIME VALUE \
  --season 12 --horizons 12 --origins 36 --report-horizons 1 3 12

各予測の時点 o で、系列ごとのモデルはその系列の o までの値だけを、系列をまたぐモデルは全ての系列の o までの値から作った組 (特徴量の時点 t、目的の時点 t + h ≤ o) だけを受け取る。

uvx --with numpy --with duckdb python scripts/series_breaks.py tmp/series.parquet SERIES TIME VALUE --top 15 \
  [--min-level 10000] [--other-table tmp/series_other_version.parquet]

--min-level は、両方の値がこれより小さい変化を無視する。件数のように小さな数から始まる系列で、3 から 300 のような跳ねが並ぶのを防ぐ。

テストは uvx --with numpy --with scipy --with scikit-learn --with statsmodels --with duckdb --with pytest pytest scripts/test_forecast.py scripts/test_series_breaks.py。モデルが予測の時点より後の値を受け取らないこと (受け取った履歴の長さを記録するモデルで)、季節ナイーブが季節性のある系列で前の期間に勝つこと、季節の周期より先でも正しく季節をさかのぼること、平年値が季節の位置に合うこと、傾向のある系列で平年値が偏り ETS が偏らないこと、SARIMA の特別な場合が前の期間、季節ナイーブ、手で書いた指数平滑と一致し模擬の係数が戻ること (references/sarima.md)、系列をまたぐモデルが試験の期間で学習しないことを確かめている。履歴に 1 つ先の値を入れる、系列をまたぐモデルの学習に後の組を入れる、季節を 1 周期しかさかのぼらない、平年値の位置をずらす、のそれぞれで落ちることを確かめてある。

実例: 国ごとの月の紛争の事件数

UCDP GED 26.1 の事件を国 × 月 (1989-01〜2025-12、444 か月) で数え、事件の多い 20 か国、log1p、最後の 36 か月を予測の時点、1〜12 か月先 (2026-10-10、メモリ 8 GB と CPU 4 コアの上限の中で 528 秒、最大 230 MB)。

モデルMAE1 か月先12 か月先偏り
前の期間0.4700.3060.594-0.036
季節ナイーブ0.5920.6060.594-0.098
平年値1.9231.8821.963-1.475
ETS0.4660.3040.595-0.010
縮めた前の期間0.5380.3480.664-0.189
ラグ + GBDT0.4800.2930.630-0.089
  • 紛争の事件数には季節性がほとんど無く、前の月の値が季節ナイーブに勝つ。
  • ETS とラグ + GBDT は前の月の値とほぼ同じ。1 か月先でラグ + GBDT がわずかに良いだけ。
  • 平年値は大きく下に外れる。1989 年からの平均には紛争の無かった時期が入る。傾向のある系列で過去の平均を基準にすると、系統的にずれる (東京の気温の分析でも、温暖化で同じことが起きた)。

跳ねの原因を調べる

跳ねを見つけたら、原因を次の順で調べ、結果を報告書に書く。原因によって、跳ねの前の値を信じてよいかが変わる。

  1. データの出どころの注記。その系列、その期間に付いた注記を引く (データセットの reference に、引き方がある)。「系列の断絶」「国勢調査に合わせ直した」のような注記があれば、定義や基準が変わった跳ねで、前の値は新しい基準と比べられない。
  2. 別の版にもあるか。--other-table に、同じ表の別の版を渡すと、その版での同じ期間の変化が出る。両方の版にある跳ねは、後の改訂が作ったのではない。新しい版にだけある跳ねは、改訂が作った。
  3. 同じ期間に、ほかの系列も跳ねているか。出力の same period が、同じ期間に跳ねた系列の数。多ければ、共通の出来事か、共通の方法の変更。1 つだけなら、その系列の事情。
  4. 注記も版の差も無く、1 つの系列だけなら、実際の出来事の可能性が高い。ただし、出来事だと確かめたのでなければ、「出来事と推測、未確認」と書く。

国別の総人口 (WDI)、版 2026-10-01 と版 2024-05-30、series_breaks.py --other-table、2026-10-13。

国と年変化同じ期間の系列数旧い版注記読み
セーシェル 2022+20.8%1+0.189 (同じ)「Break in series. Rebased on the census.」(2022 年)国勢調査に合わせて基準を直した断絶。前の値は新しい基準と比べられない
カタール 2021-10.4%1-0.026無し新しい版にだけある。後の改訂が作った
カタール 2007+24.2%1+0.194無し (2009 年に出どころの切り替えの注記)両方の版にある。出来事の可能性 (未確認)
クウェート 1991-19.8%2-0.223 (ほぼ同じ)無し両方の版にある。出来事の可能性 (未確認)
ルワンダ 1994 と 1995-14.9%、-16.5%1ほぼ同じ無し両方の版にある。出来事の可能性 (未確認)
  • 注記で説明できたのは、8 件のうちセーシェル 1 件だった。ほかは、注記の有る無しだけでは決まらない。
  • 前の値を信じてよいかは、原因で決まる。基準の断絶 (セーシェル) は、跳ねの前後を別の系列として扱う。改訂が作った跳ね (カタール 2021) は、古い版のほうが滑らかで、どちらの値で評価するかを決めて書く。出来事 (戦争、移住) は、直近の水準が新しい水準。
  • 原因を調べたあとで、予測の対象に含める、除く、頑健な基準 (前の期間など) で受ける、のどれにするかを決める。

実例: 水準の不連続と、データの版

国別の総人口 (WDI、版 2026-10-01、217 か国、1990〜2025 年、series_breaks.py、2026-10-13)。

見たもの結果
世界の合計2015 年 74.2 億から 2025 年 81.9 億までなめらか。合計には跳ねの旗が立たない
国ごとの跳ね8 件。セーシェル 2022 年 +20.8% (99,258 から 119,878)、カタール 2007 年 +24.2% と 2021 年 -10.4%、クウェート 1991 年 -19.8% と 1992 年 +21.0%、ルワンダ 1994 年 -14.9% と 1995 年 -16.5%、リベリア 1991 年 -12.0%
データの版2020 年の総人口を、版 2024-05-30 と版 2026-10-01 で比べると、217 か国の差の中央値は 0.89%、64 か国で 2% を超える。最大は英領ヴァージン諸島 +20.1%、サウジアラビア -12.4%
  • 世界の合計はなめらかでも、国の系列には 1 年で 2 割動くものがある。合計だけを見ても気づかない。
  • 2020 年までで切って 2025 年を当てる評価でも、現行の版の 2020 年以前の値は、2024-05-30 の版の値と違う。当時使えた値での予測の再現ではない。

難民の数 (UNHCR、版 2026-10-04、出身国 × 年、2000〜2025 年、217 出身国、--min-level 10000、2026-10-13)。

  • 合計は 2021 年 21.3 百万人から 2022 年 29.4 百万人へ、対数で +0.322 (+38%)。同じ系列だけを比べても同じ (入った系列は 3、出た系列は 1)。5 つの最大の変化の 1 つだが、過去の変動が大きいので、跳ねの旗は立たない。
  • 系列の跳ねは 95 件。ウクライナの 2022 年が +5.33 (+20,523%) で最大で、合計の 2022 年の跳ねの中身。時期は 2022 年のロシアの侵攻と合うが、原因はここでは確かめていない。
  • 小さな数から始まる系列は、--min-level を付けないと 340 件の旗が立つ。件数の系列では、水準の下限を決めて使う。

跳ねの原因が、予測に使う手法の選び方を変える。出来事なら、直近の水準が新しい水準で、前年値の基準が強い。データの改訂や定義の変更なら、跳ねの前の値は信じない。

書き出すもの

  • 当てるもの、予測の距離、予測を使う時点で分かっていること
  • 系列の数と期間、季節の周期、変換、欠けの埋め方
  • 見つけた系列の跳ねと、その原因 (注記、別の版、同じ期間の系列数で調べた結果。確かめていないなら、そう書く)、扱い (含める、除く、頑健な基準)。データの版と、版の間の改訂の大きさ
  • 予測の時点の数と範囲
  • モデルごと、距離ごとの MAE と偏り。基準 (前の期間、季節ナイーブ) との比
  • 採用するモデルと理由。基準に勝たないなら、勝たないと書く

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.