shimaenagaboost 0.1.0

ShimaenagaBoost: Attentive Histogram GBDT with sample-level token attention

ShimaenagaBoost

Attentive Histogram GBDT — サンプル単位のトークン注意機構を備えた勾配ブースティング

ShimaenagaBoost は、LightGBM スタイルのヒストグラムベース GBDT に、サンプルごとの トークン注意機構(attention)を組み込んだ機械学習ライブラリです。特徴量を 「トークン」と呼ぶサブセットに分割して各トークンごとに木を成長させ、 サンプルごとに学習された注意重みでそれらを混合します。これにより、 純粋な GBDT では捉えにくい特徴グループ間の相互作用を表現できます。

---

インストール

必要環境

• C++17 コンパイラ(GCC ≥ 9, Clang ≥ 11, MSVC 2019 以降)
• CMake ≥ 3.20
• Python ≥ 3.8 + NumPy
• scikit-learn(sklearn 互換 API と examples の実行に使用)
• (オプション)pybind11 — ネイティブ拡張としてビルドする場合のみ

Python パッケージの利用

pip install shimaenagaboost

---

クイックスタート

from shimaenagaboost import ShimaenagaBoostRegressor, ShimaenagaBoostClassifier, ShimaenagaBoostRanker

回帰

from sklearn.datasets import fetch_california_housing
from sklearn.model_selection import train_test_split
from shimaenagaboost import ShimaenagaBoostRegressor

data = fetch_california_housing()
X_train, X_test, y_train, y_test = train_test_split(
    data.data, data.target, test_size=0.2, random_state=42
)

model = ShimaenagaBoostRegressor(
    tier=1,             # Tier-1: Attentive Readout
    num_tokens=4,       # 特徴を 4 グループに分割
    num_heads=2,        # 注意ヘッド数
    d_attn=4,           # 注意埋め込み次元
    num_iterations=300,
    learning_rate=0.05,
)
model.fit(X_train, y_train)
y_pred = model.predict(X_test)

二値分類

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from shimaenagaboost import ShimaenagaBoostClassifier

data = load_breast_cancer()
X_train, X_test, y_train, y_test = train_test_split(
    data.data, data.target, test_size=0.2, random_state=42
)

clf = ShimaenagaBoostClassifier(
    num_class=1,        # 1 = 二値(既定)
    tier=1,
    num_tokens=4,
    num_iterations=200,
)
clf.fit(X_train, y_train)
proba = clf.predict_proba(X_test)   # shape (n, 2)
labels = clf.predict(X_test)

多クラス分類

from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from shimaenagaboost import ShimaenagaBoostClassifier

data = load_iris()
X_train, X_test, y_train, y_test = train_test_split(
    data.data, data.target, test_size=0.2, random_state=42
)

clf = ShimaenagaBoostClassifier(
    num_class=3,        # K クラス softmax
    tier=1,
    num_tokens=2,
    num_iterations=100,
)
clf.fit(X_train, y_train)
proba = clf.predict_proba(X_test)   # shape (n, 3)

ランキング(LambdaMART)

from shimaenagaboost import ShimaenagaBoostRanker

# group: クエリごとのサンプル数(合計 = len(X_train))
model = ShimaenagaBoostRanker(tier=1, num_iterations=200)
model.fit(X_train, y_train, group=group_train)
scores = model.predict(X_test)

# 検証セット付き(eval_group 必須 — valid の NDCG をクエリ単位で計算するため)
model.fit(X_train, y_train, group=group_train,
          eval_set=[(X_valid, y_valid)], eval_group=[group_valid],
          early_stopping_rounds=50)

モデルの保存・ロード

model.save_model("model.sbb")       # バイナリ形式 (.sbb, 形式 v3)

# ロード: 同じ設定でインスタンスを作り、一度 fit で booster を初期化してから load
loaded = ShimaenagaBoostRegressor(tier=1, num_tokens=4)
loaded.fit(X_tiny, y_tiny)          # booster の初期化(小さなデータで可)
loaded.load_model("model.sbb")
pred = loaded.predict(X_test)

ライセンス

MIT License.
詳細は LICENSE を参照してください。
サードパーティの著作権表示は THIRD_PARTY_NOTICES.md を参照してください。