evaluate-ml-pipeline

ML パイプラインを評価する

1 つの学習器をスコアリングし、レポートを保存します。パイプライン、分割器、およびデフォルト以外のスコアは、すでに宣言されています。 skore.evaluate がエントリーポイントです。cross_val_score、cross_validate、classification_report、またはメトリクスの出力を独自に実装しないでください。

SkrubLearner は sklearn の fit(X, y) を実装していません。 cross_val_score はエラーになります。skore.evaluate(learner, data={...}) を呼び出し、translation.splitter が prefit の場合を除き、splitter= を省略してください。

ユーザー向けの文章

詳細：setup-workspace references/human_facing_prose.md。 実験の Markdown と # コメントでは、この評価について説明します。 質問と締めくくりでは、スキル ID、G-* 名、ラッパー CLI ではなく、データサイエンスの言葉を使います。 `` はサイトマーカーです。

手順

1. python -m skore_skills status。status.setup.pending が空でなく、 status.skills.setup-ml-project が true の場合は、 setup-ml-project を読み込み、停止します。このスキルを 開始してはいけません。スキルから戻ったら続行します。このターンでは 再度読み込まないでください。そのスキルがインストールされていない場合は、 保留中の項目を1行で示して停止します。git init、scaffold、または env init をでっち上げてはいけません。status.setup.env または status.setup.workspace が declined の場合は、1行で停止します。 git または editable が declined の場合は、再度尋ねずに続行します。 次に --revise を付けずに python -m skore_skills frame show を実行します。 status.modeling_decisions が locked でない場合は、 draft を含め、model-ml-pipeline に戻って停止します。 同意やストレージモードを尋ねたり、プレビューであっても skore.evaluate の呼び出しを表示したりしてはいけません。 proceed 以外の場合は frame-ml-problem を読み込んで停止します。 translation が null の場合は停止します。評価呼び出しを記述してはいけません。
2. 履歴に依存するパイプライン（後方シフト、ラグ、ローリング ウィンドウ、ターゲットシフト、または履歴データを持つテーブルとの結合）： tests/smoke/test_<stem>.py が存在しない場合、または pytest が失敗した場合は、 停止して build に戻ります（§ Back to build）。skore.evaluate を 記述してはいけません。履歴依存のステップがない場合に限り、 文書に n/a と記載できます。
3. python -m skore_skills evaluate consent --stem <stem>。
   • ask であり、このターンに build-ml-pipeline の Evaluate にまだ回答していない場合は、JSON の context を引用し、 Evaluate（推奨）／Modify／Stop を提示します。停止します。 初回の実行で「評価を実行する」と言うことは同意ではありません。
   • ユーザーがこのターンにすでに Evaluate と回答した場合、 または JSON が proceed の場合（実際のロケーターがすでに存在します）： 続行します。
   • stop — スモークテストファイルがありません。build に戻ります （§ Back to build）。
4. G-SKORE-MODE。status.policy.skore_mode を読みます。すでに設定されている場合は、 その設定を維持します。未設定の場合は local（推奨）／hub／mlflow を尋ねてから、 python -m skore_skills policy set skore_mode <mode> を実行します。local：mkdir reports を実行します （exist_ok）。reports/README.md を記述してはいけません。hub または mlflow：reports/ を作成してはいけません。次に、 インストールされている場合は add-python-package を読み込みます。 このスキルは env add-skore --mode <mode> --execute を実行します。 ここで skore[...] と書いてはいけません。ここで env add を 実行してはいけません。コンストラクターについては references/g_skore_mode.md を参照してください。モードの切り替えや 移行の際は、そのスキルがインストールされていれば sync-ml-reports を読み込みます。
5. Pre-flight を出力し、続けて1～3文で説明します。これは、ロック済みの方式、 レポートメトリクス、skore のチェック、project.put を使った ローカルでの全データセット評価です。チェックはこの実行で計算され、 レポートとともに保存されます。translation.splitter が prefit の場合は、 モデルを学習テーブルで学習し、提供されたテストテーブルでスコアを 算出すると伝えます。stem、判明している場合は fold 数、 experiments/<stem>.py、および scratch/results/<stem>/ を明記します。 所要時間は行数、fold 数、学習器、チェックによって異なります。 分数をでっち上げてはいけません。同意がまだ保留中の場合は、 プレビューを表示して停止します。
6. 呼び出しは experiments/NN_*.py のみに記述します。以下の呼び出し形式を 参照してください。編集後に python -m skore_skills style を実行します。 実験は report.checks.summarize()、 project.put、および単独の report で終了します。このファイルを 実行してはいけません。
7. templates/materialize.py を scratch/results/<stem>/materialize.py にコピーします。Project の初期化を 置き換えます。<CALL> ブロックを、引数と順序が同じ実験呼び出しに 置き換えます。このファイルを env verify で確認した composed-dev Python で 1回実行します。これが唯一の skore.evaluate 呼び出しであり、 唯一の project.put です。id.txt を読み取り、ロケーターを作成して locator.txt に書き込みます。policy.notebooks が true の場合は、 python -m skore_skills notebook fill experiments/<stem>.py を実行し、 policy.site も true の場合に限り --html を追加します。 実験を notebook convert してはいけません。また、実験ファイルを 実行してはいけません。notebooks が null または false の場合は、 ポリシーを変更せず、fill も実行しません。policy.site が true で、 export-ml-site がインストールされている場合は、ロケーターの作成後、 監査／レビュー、または別のユーザー確認の前に python -m skore_skills site build --if-stale を実行します。 これにより結果ビューアーをただちに公開できます。record-outcome 後の クローズ時ビルドの代わりにはなりません。その後、ターンを終了します。 実験ファイルに materialize の書き込みを追加してはいけません。 すべての Python プローブは scratch/<ts>_<short>.py に保存し、 env verify の composed-dev Python で実行します。インラインの python -c は使いません。ユーザーから依頼されない限り、 warnings.filterwarnings は使いません。確認できていないシグネチャは 書きません。そのプローブの末尾には BLOCKED: <class> signature needs an API lookup that cannot run this turn (<why>). と記載します。キャッシュにあれば、参照確認済みとして扱います。

呼び出し

experiments/NN_*.py の skore.evaluate を使います。 translation.splitter が prefit でない限り、splitter= は省略して skore に DataOp の cv と split_kwargs を再利用させます。それ以外の splitter= を渡すと、split_kwargs は破棄されます。DataOp に cv が 設定されていない状態で splitter= を省略すると、80/20 のホールドアウト になります。これは translation.report が EstimatorReport で、 translation.splitter が null の場合に限り正しい設定です。配線方法： references/metadata-routing.md。

translation.splitter が prefit の場合は、トレーニングテーブルだけで 学習してから、テストテーブルをスコアリングします。fit と evaluate を api get で確認します。トレーニングテーブルを evaluate に渡しては いけません。この場合に splitter= を省略すると、テストテーブルが新たに 80/20 に分割されます。2 つのテーブルを連結してはいけません。

learner = build_learner()
fitted = learner.fit({"table": train_df})
report = skore.evaluate(
    fitted,
    data={"table": test_df},
    splitter="prefit",
)

fit が (X, y) を取る推定器にも、同じルールが適用されます。

fitted_model = LogisticRegression().fit(X_train, y_train)
report = skore.evaluate(
    fitted_model, X_test, y_test, splitter="prefit"
)

X / y と data は同時に指定できません。

• SkrubLearner — skore.evaluate(learner, data={...})。キーは skrub.var の名前です。相互運用： references/skrub_interop.md。
• fit が (X, y) を取る推定器 — skore.evaluate(estimator, X, y)。固定済みの cv がすでに評価方式に なっている場合は、ここでも splitter= を省略します。上記の prefit の 呼び出しは例外です。推定器はすでに学習済みで、X と y は テストテーブルです。

mark_as_X の cv は、KFold、GroupKFold、または build で使う 日付ベースのクラスです。translation で cv が指定されていて、 マーカーには設定されていない場合は、build に戻ってください （§ build に戻る）。ここでは split_kwargs を設定しません。 split_kwargs が空で、グループ列が存在する可能性がある場合は、build に 戻ってください。デフォルトで KFold を使ってはいけません。 translation.splitter の prefit は、マーカーの cv ではありません。

クラスの不均衡に Stratified* を使ってはいけません。fold 間の分散が 圧縮されます。

主要な指標は translation.metric です。build-ml-pipeline の skore デフォルトリストにある名前はスコアラー不要です。ただし、 multioutput-regression は例外です。デフォルトの回帰指標は出力ごとに 計算されるため、固定済みの集約指標がすでに .skb.with_scoring(...) になっている必要があります。それ以外の名前は すべて、予測 DataOp 上ですでに .skb.with_scoring(...) になっている 必要があります。そうでなければ、skore.evaluate の前に build に 戻ってください（§ build に戻る）。report.metrics.add は呼び出しません。 スコアラーを設定すると、その名前は report.metrics.summarize().frame() の行になります。 multioutput-regression の場合、このフレームには出力ごとに 1 行も 含まれます。実験ファイルでこれらの行を平均して消してはいけません。 締めくくりでは固定済みの集約指標を引用してもかまいませんが、出力ごとの 行は保存されたレポートに残します。skore.evaluate に scoring= 引数は ありません（references/custom-metrics.md）。名前が設定済みなのに、 そのフレームにまだ表示されない場合は、予測器クラスが間違っています。 ミックスインを継承してから BaseEstimator を継承する必要があります （先に RegressorMixin または ClassifierMixin）。build に戻ってください （§ build に戻る）。BaseEstimator だけを継承する場合も、 ミックスインより先に BaseEstimator を継承する場合も、どちらも失敗します。

固定後にユーザーから追加のチェックを依頼された場合： references/custom-checks.md。experiments/NN_*.py のモジュールレベルで skore.Check をサブクラス化し、evaluate の後、summarize の前に report.checks.add(...) を呼び出します。add は SKD のチェックを拡張します。 チェックを作り上げてはいけません。audit/ から登録してはいけません。 Check と checks.add を api get で確認します。

すべての評価では、evaluate の後、および checks.add を行った場合は その後に、引数なしで report.checks.summarize() を呼び出してから project.put を呼び出します。これによりチェック結果がレポートに保存されます。 fast_mode や ignore を渡してはいけません。checks.summarize を api get で確認します。

report = skore.evaluate(...)
report.checks.summarize()
project.put(STEM, report)
report

ディスパッチャーの粒度が粗すぎる場合に限り、evaluate より詳細なレポートを使用します （references/reports.md）。単一のホールドアウト適合には EstimatorReport、フォールドごとのアーティファクトには CrossValidationReport を使用します。ホールドアウトでは EstimatorReport を使用します。このループでは、単一の学習器に対して skore.evaluate を1回、report.checks.summarize() を1回、 project.put を1回実行してスコアを評価します。

履歴に依存する特徴量を含むパイプラインでは、CVは必要ですが、それだけでは不十分です。 skore.evaluate は1つの env-dict を使ってグラフを一度だけ具体化し、インデックスを分割します。 スモークテストでは、予測時に新しい env-dict を使用します。呼び出し元がステータスを done に変更する前に、スモークテストに合格する必要があります。このスキルから JOURNAL.md の History または設計メモの Status を done に変更しないでください。

人間が作成する実験ファイルには skore.evaluate(...) と project.put(...) が含まれますが、実行はされません。同じ呼び出しを scratch/results/<stem>/materialize.py にコピーし、実行するのはこのファイルだけにします。 そのため、project.put は一度だけ実行されます。監査ファイル、スクラッチプローブ、または実験ファイルに対する notebook convert で、これらを呼び出してはいけません。保存済みレポートは project.summarize() の後に project.get(id) で読み込みます。get は idを指定して取得するため、get(key) は KeyError を発生させます。その問題を取り繕うために evaluate を再実行しないでください。

skore が標準で描画しないプロットを作成する場合は、そのスキルがインストールされていれば plot-ml-figure を読み込みます。

put の後

Project.put は None を返します。materialize.py は、そのキーに対する最新の idを scratch/results/<stem>/id.txt に書き込みます。そのidからロケーターを1つ作成し、 loop locator と loop artifacts の前に locator.txt に書き込みます。 これらの書き込みを experiments/<stem>.py に入れないでください。 python -m skore_skills loop locator --stem <stem> を実行し、JSON の locator を そのまま貼り付けます。ロケーターがない場合は、 n/a — backend did not expose a locator とします。

• local — local workspace: [reports/](../reports/) · id: <id> と reports/ の絶対パスを記載します。非公開ファイルへのリンクは作成しないでください。
• hub — 正確な Consult your report at … URLを使用します： [Open report](<url>) · hub · id: <id>。Skore がURLを出力しない場合は、 プロジェクトのランディングページに Open project としてリンクします。
• mlflow — View run … URLがある場合は、それをそのまま使用します。URLがなく、 tracking_uri が HTTP(S) の場合は、 /#/experiments/<experiment-id>/runs/<run-id> を使用します。file:、 sqlite:、databricks、またはURLが出力されないその他の URI の場合は、 mlflow · tracking: <uri> · experiment: <id> · run: <run-id> とします。ブラウザーリンクを推測して作成しないでください。

スクリプトは report._repr_html_() を scratch/results/<stem>/report.html に、repr(report) を report.txt、checks.html、metrics.html に書き込みます。メモリ内の学習器から Method ビューアーを再生成します。 EstimatorReport では report.estimator_、 CrossValidationReport では report.reports_[0].estimator_ を使用します。 SkrubLearner は DataOp を learner.data_op に格納します。スクリプトは learner.data_op.skb から draw_graph().svg を使って pipeline.svg を書き込み、 DataOp レポートを scratch/results/<stem>/pipeline/ に report(eval=False, open=False, overwrite=True, output_dir=...) を使って書き込みます。 environment は使用しません。 これは適合を行いません。full_report を呼び出さないでください。また、 eval=False を指定せずに report を呼び出さないでください。 skrub に対して add-python-package を1回再試行した後も Graphviz が失敗する場合は、 エラー名を1行で記載します。

ターン終了時

model-ml-pipeline がこのターンをディスパッチした場合は、JSON locator を渡し、上記のライブ実行とチェックポイントの プレビュー後に戻ります。終了時の loop notebooks、 loop artifacts、監査、record-outcome、別のサイトビルド、 git end-turn は実行しないでください。

それ以外の場合、このスキルが終了処理を担当します。まず python -m skore_skills loop artifacts --stem <stem> を実行します。 stop / evaluate_incomplete → 不足しているファイル名を示し、 監査は実行しないでください。audit → インストールされている場合は audit-ml-pipeline を読み込みます。 record → 監査をスキップします。record はそのコマンドのアクションであり、 ノートブックのゲートではありません。監査スキル内で変換しないでください。

次の順序で実行してください。順序を入れ替えないでください。loop notebooks は skip の場合のみ続行します。

1. python -m skore_skills loop notebooks --stem <stem> を実行します。JSON の action を正式な判断基準として扱ってください。action が convert の間は、 record-outcome、site build、git end-turn を実行しないでください。 not_evaluated は変換しません。
2. convert の場合、experiments/ または audit/ のすべてのエントリーに対して python -m skore_skills notebook fill <source> を実行し、html が true の場合は --html を付けます。これらのファイルに notebook convert を実行しないでください。Fill は put を実行しません。 現在のアーティファクトを書き込んだ実行以降に人間による呼び出しが変更された場合に限り、 先に materialize.py を再実行してください。audit/<stem>.py のみを fill しても終了処理にはなりません。未フィットスナップショットの禁止は適用されません。 skore.evaluate を含む場合でも、実験スクリプトを fill してください。 action が skip になるまで手順 1 を繰り返します。jupytext / nbformat / nbconvert が不足している場合は、add-python-package を指定する一行だけを返します。
3. 手順 1 が skip になった場合に限り、site build の前に record-outcome を実行します。 監査を実行した場合は、そのスキルがインストールされていれば、監査の digest と G-AUDIT-FINDING を manage-ml-backlog に渡します。実験スクリプトが変換された場合は、 手順 2 の locator も渡してください。 監査を実行しなかった場合は、その locator と、ユーザーが指定した見出しがあればそれ、 および n/a — audit not run を使って record-outcome を呼び出します。 backlog スキルが不足している場合は、一行だけ返します。ここでは History を書かないでください。 smoke が赤の間は、決して done にしないでください。
4. policy.site が true で、export-ml-site がインストールされている場合に限り、 site build を実行します： python -m skore_skills site build --if-stale。これは audit/<stem>.nb.html を ## Notebooks の下に埋め込みます。 `` を追加しないでください。site build が mkdocs-material is required でエラーになった場合は、mkdocs-material の add-python-package（agent）を読み込み、もう一度ビルドします。 pixi add / uv add は実行しないでください。ビルドエラーを示しますが、 ターンを失敗扱いにはしないでください。
5. 以下のチェックポイント。policy.site が true で、チェックポイントのビルドが成功した場合は、 ウェブサイトが更新されたことを伝え、その出力の file:// 行をそのまま貼り付けます。 design-note の Markdown には言及しないでください。サイトをビルドしなかった場合は、 更新されたと主張せず、Markdown にも言及しないでください。
6. python -m skore_skills git end-turn --stage evaluate を実行します。JSON の action が invoke の場合は、インストールされていれば persist-ml-git を読み込み、 停止します。それ以外の場合は、インストールされていれば triage-ml-task を読み込みます。 ここで git commit を実行しないでください。

チェックポイント

単独で記述します。見出しに、または監査をスキップした場合は report.txt に基づいて、 結果を 2～6 文で述べます。監査を実行した場合は、その Checks と Metrics に基づいて説明します。 指標を捏造しないでください。

リンク：policy.site が true でビルドが成功した場合は、ウェブサイトが更新されたことを伝え、 その出力の file:// 行をそのまま貼り付けます。 html/<stem>.html や journal/<stem>.md には言及しないでください。 サイトをビルドしなかった場合は、更新されたと主張せず、Markdown にも言及しないでください。

説明文の後に続けるトークン：まず JSON locator、次に G-AUDIT-FINDING （監査をスキップした場合は n/a — audit not run）。

build に戻る

cv がない、スコアラーがない、予測器クラスが誤っている、またはスモークテストがないか失敗している場合は、build-ml-pipeline で修正するパイプラインの問題です。ここに至った経緯は、このスキルを読み込んだ経路によって異なります。

• ディスパッチ経由 — 今回のターンで model-ml-pipeline または build-ml-pipeline がこのスキルを読み込んだ場合：ここで止め、そのループに戻ってください。修正のために build に戻ります。
• 直接開始 — ユーザーが評価を依頼した場合、またはエントリースキルがここに振り分けた場合：status.skills.model-ml-pipeline が true なら model-ml-pipeline を読み込み、ステム名を伝えてください。承認済みの設計を再開し、build が宣言するモデルのティアで修正のために build に戻ります。ここから build-ml-pipeline を読み込まないでください。このスキルが読み込むサブステップは、このスキル自身のティア以下で動作します。model-ml-pipeline がない場合は、パイプラインには build での修正が必要だと1行で伝え、そこで終了してください。

どちらの場合も、このターンでは skore.evaluate を記述しないでください。

停止条件

• セットアップが保留中（status.setup.pending が空でない）→ setup-ml-project を読み込みます。拒否された git を再度尋ねないでください。環境またはワークスペースを拒否された場合は停止します。
• 履歴に依存するパイプラインでスモークテストがない、または失敗している → build に戻ります（§ build に戻る）。
• split_kwargs が空で、グループ列の可能性がある → build に戻ります（§ build に戻る）。デフォルトで KFold を使用しないでください。
• import skore が失敗する → 未設定の場合は G-SKORE-MODE を設定し、その後 add-python-package を読み込みます。cross_val_score に切り替えないでください。
• ハイパーパラメーター検索、サービング、複数実行のトラッキングは対象外です。
• 不足しているパッケージがインストール済みの場合は、add-python-package を読み込みます。ここでは env add を実行しないでください。

事前確認 — コードより先に出力

Pre-flight (evaluate-ml-pipeline):
- [ ] sklearn, skrub, skore import
- [ ] frame show is proceed; DataOp cv matches translation
      (or holdout / prefit, and the marker has no cv)
- [ ] skore_mode is set (local | hub | mlflow)
- [ ] evaluate consent is proceed, or the user answered Evaluate
- [ ] Call site is experiments/NN_*.py (not executed)
- [ ] The one run is scratch/results/<stem>/materialize.py
      (not cells in the experiment file)
- [ ] skore.evaluate omits splitter=
      (or splitter="prefit" and only the test table is passed)
- [ ] report.checks.summarize() then project.put
      (no fast_mode, no ignore; after any checks.add)
- [ ] Smoke: passing | n/a (no history-dependent step) | STOP

参照資料

• references/metadata-routing.md — ロック済みの cv は DataOp に残し、evaluate では splitter= を省略します。
• references/skrub_interop.md — 環境辞書と (X, y) の使い分け。
• references/g_skore_mode.md — Project のコンストラクター。
• references/reports.md — evaluate では大まかすぎる場合。
• references/custom-metrics.md — with_scoring を使ったデフォルト以外の指標。
• references/custom-checks.md — ユーザーが依頼したチェック。
• templates/materialize.py — 唯一の評価実行。scratch/results/<stem>/materialize.py にコピーします。