autocarver

AutoCarver は、生の数値列、カテゴリ列、順序尺度列を、少ないコードで、教師ありかつドリフトに強い、人が解釈しやすいビンに変換します。最適でない手動ビニングによるモデル性能の低下を防ぎ、本番環境でのモニタリング中に過学習したビンが見つかる事態も防ぎます。

• 目視ではなく探索 — 動的計画法による探索で、min_freq と max_n_mod に応じた候補のグループ分けを、Tschuprow の T（デフォルト）または Cramér の V に基づいて順位付けします。
• 設計段階から堅牢 — すべての候補グループ分けは、fit 時に、ホールドアウトした開発セット（および任意の CV フォールド）で有効でない限り採用されません。モニタリング時ではなく、学習時に検証します。
• 定義 → ビン作成 → モデル — Features を宣言し、carver を fit してから transform します。特徴量セット全体を一度の教師あり処理でビンに分けるため、特徴量ごとにノートブックを用意する必要はありません。ターゲットの種類ごとに 1 つの carver を使います。BinaryCarver、MulticlassCarver、OrdinalCarver、ContinuousCarver（回帰）を、すべて同じ API で利用できます。
• AI による支援 — ローカル MCP サーバーにより、LLM アシスタントがツール呼び出しを通じて列を評価し、ビンに分けられます。処理はすべてお使いのマシン上で行われます。

Titanic のクイックスタートでは、Fare のモダリティ数がビン作成前の 72 から 2 ビンに減り、生存との関連性が高まります。Tschuprow の T は、生データの 0.18 からビン作成後の 0.29 に上昇します。

信用スコアリング、不正検知、リスクモデリング向けに開発されています。

🆕 新機能

📊 交差検証による頑健性の確認。 fit で cv 引数を受け付けるようになりました。開発用データセットに加えて（またはその代わりに）、ホールドアウトデータで頑健性を確認できます。 carver.fit(X, y, cv=5) のように指定します。整数、scikit-learn の任意の分割器、または明示的なインデックスペアを指定でき、sklearn.model_selection.check_cv を使って解決されます。フォールドによって過学習した組み合わせは除外されますが、並べ替えは行われません（順位は全学習データに基づいたままです）。詳しくは交差検証のフォールドをご覧ください。

🤖 LLM と MCP の統合。 AutoCarver に、ローカルで動作するModel Context Protocolサーバーが追加されました。MCP 対応アシスタント（VS Code Copilot、Claude Desktop、Cursor など）にデータファイルを指定すると、ツール呼び出しを通じて列を分類し、目的変数に対してビニングできます。サーバーはすべてお使いのマシン上で動作します。データセットが AutoCarver や外部サービスに送信されることはありません（アシスタントが共有する情報を確認できるのは、ご利用の LLM プロバイダーのみです）。ビニングの品質は LLM に依存するため、本番環境で使う前に、特徴量の定義を人間が確認してください。詳しくはLLM と MCP のガイドをご覧ください。

pip install "autocarver[mcp]"

設定が済んだら、アシスタントに次のように尋ねてください。

titanic.csv の列を分類し、Survived に対してビニングしてください。

アシスタントが特徴量の種類を推定し、ビニング案を提案して、要約テーブルを返します。手動でコードを書く必要はありません。

{
  "servers": {
    "autocarver": {
      "command": "python",
      "args": ["-m", "AutoCarver.mcp"]
    }
  }
}

{
  "servers": {
    "autocarver": {
      "command": "uv",
      "args": ["run", "python", "-m", "AutoCarver.mcp"]
    }
  }
}

インストール

pip install autocarver

クイックスタート

すでに DataFrame と目的変数があるなら、作業を始める前の最初の項目はクリアです。

• データを読み込む
• 学習用データと開発用データに分割する
• 特徴量を種類ごとに宣言する
• 開発用データセットで検証しながら、carver を学習させる
• ビニング後の区間を確認する
• 保存する

あとは以下のコードを実行するだけです。Titanic データセットを使った二値分類の例です。

from pathlib import Path

import pandas as pd
from sklearn.model_selection import train_test_split

from AutoCarver import BinaryCarver, Features

# 1. Load data
url = "https://web.stanford.edu/class/archive/cs/cs109/cs109.1166/stuff/titanic.csv"
data = pd.read_csv(url)
target = "Survived"

# 2. Train / dev split, stratified on the target
train, dev = train_test_split(data, test_size=0.33, random_state=42, stratify=data[target])

# 3. Declare features by type
features = Features(
    categoricals=["Sex"],
    numericals=["Age", "Fare", "Siblings/Spouses Aboard", "Parents/Children Aboard"],
    ordinals={"Pclass": ["1", "2", "3"]},
)

# 4. Fit the carver (dev set drives the robustness checks)
carver = BinaryCarver(features=features)
train_processed = carver.fit_transform(train, train[target], X_dev=dev, y_dev=dev[target])
dev_processed = carver.transform(dev)

# 5. Inspect the carved buckets, target rate, and association
carver.summary

# 6. Persist for later use
carver.save(Path("titanic_carver.json"))

# 7. Load the carver back in
carver = BinaryCarver.load(Path("titanic_carver.json"))
dev_processed = carver.transform(dev)

最初に調整するのは min_freq と max_n_mod の 2 つだけです。デフォルト値（0.02 / 5）は一般的なスコアリング手法を反映しています。動作に関するすべての切り替え設定は、1 つの ProcessingConfig オブジェクトにまとめられています。確認して、調整し、先に進みましょう。

多クラス分類では MulticlassCarver（特徴量ごとに 1 つのビニングを行い、K クラス全体の目的変数に対して処理）を使います。クラスごとに個別のビニングを行う場合は OneVsRestCarver、順序尺度の目的変数には OrdinalCarver、回帰には ContinuousCarver を使います。API はすべて同じです。目的変数との関連性と特徴量間の冗長性に基づいて特徴量を事前選択するには、features=carver.features を指定して、ビニング済みの出力を ClassificationSelector または RegressionSelector に渡します（carver は独自のコピーをビニングするため、元の features は未加工のままです）。

得られるもの

次のモデルレビューの前に答えておきたい2つの質問があります。現在のモデルのすべてのビン境界をステークホルダーに説明できるでしょうか。また、それぞれの境界が一度も見たことのないデータでも妥当であることを示せるでしょうか。AutoCarverなら、どちらも1行のコードで実現できます。

• 最初に許容できるグループ化ではなく、最適なグループ化 — 候補となるグループ化をTschuprowのT（デフォルト）またはCramérのVでランク付けし、開発セットで妥当性が確認されたもののうち、最も順位の高いものを採用します。そのため、問題なさそうに見える最初のグループ化で妥協することはありません。

• 本番環境に入る前に、気づかない過学習を防止 — 学習サンプルにしか存在しないビンは、ドリフトの下でひそかに性能が低下します。すべての候補の組み合わせを開発セット（および任意のCVフォールド）で検証します。ターゲット率が逆転する、またはバケットがmin_freqを下回る候補は、モニタリングで発覚するのではなく、fit時に棄却されます。

• 順序特徴量を第一級でサポート — OrdinalDiscretizerは、宣言されたモダリティの順序を適用します。そのため、出現数の少ないレベルは頻度に基づいてまとめられるのではなく、最も近い隣接レベルと統合されます。

• 最終的な監査役はあなたです — carver.features.summaryとcarver.features.historyでは、ビンの定義、ビンごとのターゲット率／頻度、カービングの全履歴を確認できます。境界に異議がある場合は上書きでき、その修正は他のカービング済みビンと同様にtransformで適用されます。

  feature = carver.features("Siblings/Spouses Aboard")  # any carved feature; labels are [0, 1, 2]
  feature.group([1], 2)  # merge two bins you consider equivalent
  

• 解釈可能なバケット — 監査、文書化、スコアカードへの組み込みができる、人が読みやすい境界です。

• 次元削減 — 出現数の少ないモダリティをグループ化し、特徴量ごとのビン数を制限します（max_n_mod）。特に、ワンホットエンコーディングの前に役立ちます。

• 特徴量の事前選択 — ClassificationSelector／RegressionSelectorは、ターゲットとの関連性に基づいて特徴量をランク付けし、特徴量間の相関に基づいて絞り込みます。

タイタニック号のAgeでは、BinaryCarver.fitを1回呼び出すだけで、元の84個の値が生存率の単調な3つのバケットにまとまります。

どのように比較できますか？

3つのライブラリはいずれも sklearn の Pipeline と互換性があります。AutoCarver は JSON での往復永続化（carver.save("...json")）にも対応しています。AutoCarver（ClassificationSelector、RegressionSelector）と optbinning（BinningProcess(selection_criteria=...)）は、どちらも特徴量の事前選択機能を備えています。特徴量行列の全体像、横並びで実行できるコード例、「どちらを選ぶべきか」のガイドは、比較ページをご覧ください。

ドキュメント

完全なリファレンス、チュートリアル、エンドツーエンドのノートブック例はReadTheDocsにあります。