mma-prediction

MMA Fight Predictionは、UFCの試合勝者、勝利方法、および終了ラウンドを予測するPythonベースの研究およびサービングプロジェクトです。本プロジェクトでは、Eloレーティングシステム、勾配ブースティング（XGBoost）アンサンブル、マルチタスクニューラルネットワークアンサンブルを組み合わせ、これら2つの等重量ブレンドをデプロイ済みのスコアラーとして採用しています。各候補は2018年から2026年にわたる拡張ウィンドウ・ウォークフォワード評価によって判定され、最終的なスコアラーはブレンド平均後、ホールドアウトデータで適合させた温度パラメータを用いてキャリブレーションされます。 再現可能なパイプライン クイックスタートでは、仮想環境の作成とdevエクストラを含むパッケージのインストール後、4つのスクリプトを順に実行します：download_data.py（KaggleのUFCデータセットをdata/raw/へ保存）、make_dataset.py（クリーンなparquetファイルをdata/processed/へ保存）、build_ratings.py（Eloレーティングの調整と構築）、そしてpytestの実行です。Streamlitアプリ（streamlit run app.py）を使用すると、ユーザーは任意の2人のファイターを選択し、不確実性を伴う勝率、勝利方法と終了ラウンドの傾向、および主要な寄与因子の内訳を確認できます。プロジェクトの目標として、パイプライン全体のバイト単位での再現性が文書化されています。 特徴量エンジニアリングとリーク制御 特徴量はsrc/mma/feature_blocks.py内の名前付きブロック（base, external, trajectory, notice, context, opponent_adjusted）から組み立てられ、約1万1千試合×87列のテーブルが生成されます。特徴量は時系列アキュムレータ内で構築されるため、各値は厳密に試合前のデータとなり、切り捨て不変性テストを用いて、どの特徴量も未来の情報を参照していないことが確認されます。各ブロックは事前登録された精度基準で測定されており、1つのブロック（UFC以前のキャリアデータをカバーするexternal）は単独で基準をクリアしましたが、他のブロックはブレンドのスコアリングに使用されたテーブルの一部としてのみ提供されるか、あるいは提供されません。また、コーナーごとの欠損フラグに見つかった選択リークについて文書化されており、これは評価スライス用のテーブルには残しつつ、両方のモデル行列から削除されました。リーク防止策として、いくつかの列はモデル入力から明示的に除外されており、プロベナンス・サイドカーファイルに、各行がプライマリソースかセカンダリソースのどちらから来たかが記録されています。 データソース レコードは、メンテナンスされているKaggleミラー（プライマリかつ調整済みのソース）と、Greco1899/scrape_ufc_statsのCSV公開データ（HTTPS経由で取得され、データとしてのみ使用され、GPLライセンスのコードは含まれない）のユニオンとして組み立てられます。重複する試合についてはプライマリ行が優先されます。マージはソース間の勝者の一致に基づいて制御され、フェイルソフト方式を採用しているため、警告とともにプライマリのみの構築にダウングレードされます。リポジトリでは、このマージに関するプロベナンス、整合性チェック、および回帰ガードが報告されています。 自動更新と前向き評価 週次のGitHub Actionがデータセットを更新し、アーティファクトを再構築して自動的にコミットします。今後のUFCイベントは開催前に予測されgitにコミットされ、その後グレーディングされるため、回顧的な報告だけでなく前向きな実績（prospective track record）が得られます。拒否された特徴量ブロックのハーネスレポートと事前登録済みの実験決定ファイルはmodels/walkforward/にコミットされ、ネガティブな結果も保持されます。 本プロジェクトはPython (3.10+)で記述され、MITライセンスの下でリリースされています。設計書およびフェーズ計画書はdocs/に格納されています。