optuna.pruners.WilcoxonPruner

class optuna.pruners.WilcoxonPruner(*, p_threshold=0.1, n_startup_steps=2)[source]

このプルーナーは現在のトライアルと現在の最良トライアル間で Wilcoxon 符号付き順位検定を実行し、与えられた p 値以上の確信度で現在のトライアルが最良トライアルより劣っていると判断された時点で停止します。

このプルーナーは、一連の問題インスタンスに対する（評価コストの高い）性能スコアの平均/中央値の最適化に効果的です。具体的な適用例としては、以下の最適化が挙げられます：

一連の問題インスタンスに対するヒューリスティック手法（シミュレーテッドアニーリング、遺伝的アルゴリズム、SAT ソルバーなど）の平均性能
機械学習モデルの k 分割交差検証スコア
大規模言語モデル（LLM）の一連の質問に対する出力精度

「簡単な」インスタンスと「難しい」インスタンスが存在し（プルーナーは異なるトライアル間のインスタンス対応を処理します）、各トライアルでは評価順序をシャッフルすることが推奨されます。これにより、最適化が初期のインスタンスに過度に適合するのを防ぎます。

このプルーナーを使用する場合、各ステップ（インスタンス ID）ごとに Trial.report(value, step) メソッドを評価値とともに呼び出す必要があります。インスタンス ID は昇順である必要はありません。他のプルーナーと異なり、報告された値が実際の値に収束する必要はありません。 SuccessiveHalvingPruner などのプルーナーを同じ設定で使用する場合、評価値の履歴平均などを提供する必要があります。

See also

report() を参照してください。

使用例

import optuna
import numpy as np


# 一連の問題インスタンスに対する平均評価損失を最小化します。
def evaluate(param, instance):
    # 説明用の簡易損失関数
    return (param - instance) ** 2


problem_instances = np.linspace(-1, 1, 100)


def objective(trial):
    # パラメータをサンプリング
    param = trial.suggest_float("param", -1, 1)

    # パラメータの性能を評価
    results = []

    # 最良の結果を得るため、各トライアルで評価順序をシャッフル
    instance_ids = np.random.permutation(len(problem_instances))
    for instance_id in instance_ids:
        loss = evaluate(param, problem_instances[instance_id])
        results.append(loss)

        # インスタンス ID とともに損失を報告
        # 注意：同じインスタンスに対しては同じ ID を渡す必要があります
        # そうしないと、WilcoxonPruner がトライアル間で損失を正しく対応付けできず、
        # プルーニング性能が低下します
        trial.report(loss, instance_id)

        if trial.should_prune():
            # 例外を発生させる代わりに、現在の予測値を返します
            # これは、プルーニングされたトライアルの評価結果を Optuna に通知するための回避策です（下記参照）
            return sum(results) / len(results)

    return sum(results) / len(results)


study = optuna.create_study(pruner=optuna.pruners.WilcoxonPruner(p_threshold=0.1))
study.optimize(objective, n_trials=100)

Note

このプルーナーは infinity や nan の値を処理できません。これらの値を含むトライアルは決してプルーニングされません。

Note

should_prune() が True を返す場合、例外 raise optuna.TrialPruned() の代わりに、最終的な値の推定値（例えば評価されたすべての値の平均）を返します。これは、現在 optuna.TrialPruned を発生させるトライアルの予測目的値を Optuna に通知する方法がないための回避策です。

Parameters:

p_threshold (float) –
プルーニングの p 値閾値。この値は 0 から 1 の間である必要がありますプルーナーが現在のトライアルが最良のトライアルよりも悪いと判断する p 値の閾値ですこの値が大きいほど、より積極的なプルーニングが行われますデフォルトは 0.1

Note

このプルーナーは、サンプル数を増やしながら現在のトライアルと現在の最良トライアルの間で統計的検定を繰り返し行いますこのような逐次検定の偽陽性率は、検定を一度だけ行う場合とは異なります。名目上の偽陽性率を得るには、Pocock 補正された p 値を指定してください
n_startup_steps (int) – プルーニングが開始されるまでのステップ数プルーニングは、現在のトライアルと最良トライアルを比較するための n_startup_steps の観測データが利用可能になるまで開始されませんデフォルトは 2 です。n_startup_steps が 0 または 1 に設定されていても、比較に十分なデータがないためトライアルはプルーニングされません

Note

v3.6.0 で実験的機能として追加されました。インターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.6.0 を参照してください

メソッド

prune(study, trial)

Judge whether the trial should be pruned based on the reported values.

prune(study, trial)[source]

報告された値に基づいてトライアルをプルーニングするかどうかを判断します

このメソッドはライブラリのユーザーが呼び出すことを想定していません。代わりに、 optuna.trial.Trial.report() と optuna.trial.Trial.should_prune() は、目的関数にプルーニング機構を実装するためのユーザーインターフェースを提供します

Parameters:

study (Study) – 対象のスタディオブジェクト
trial (FrozenTrial) – 対象のトライアルオブジェクトこのオブジェクトを変更する前にコピーを取得してください

Returns:

トライアルをプルーニングするかどうかを表すブール値

Return type:

bool