Metadata-Version: 2.4
Name: shimaenagaboost
Version: 0.1.0
Summary: ShimaenagaBoost: Attentive Histogram GBDT with sample-level token attention
Author: ShimaenagaBoost Authors
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: numpy>=1.20
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.0; extra == "sklearn"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: scikit-learn; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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 パッケージの利用

```bash
pip install shimaenagaboost
```
---

## クイックスタート

```python
from shimaenagaboost import ShimaenagaBoostRegressor, ShimaenagaBoostClassifier, ShimaenagaBoostRanker
```

### 回帰

```python
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)
```

### 二値分類

```python
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)
```

### 多クラス分類

```python
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)

```python
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)
```

### モデルの保存・ロード

```python
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. <br/>
詳細は [LICENSE](LICENSE) を参照してください。<br/>
サードパーティの著作権表示は [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) を参照してください。
