Metadata-Version: 2.4
Name: binboost
Version: 0.2.4
Summary: Gradient Boosting Berbasis Aturan Logika Adaptif untuk Fitur Biner
Author: Rangga Wahyu Pratama
License: MIT
Keywords: gradient boosting,logical rules,binary features,interpretable machine learning
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# BinBoost

**Gradient Boosting Berbasis Aturan Logika Adaptif untuk Fitur Biner, dengan Regularisasi Newton-Hessian dan Dukungan Multi-Kelas**

BinBoost adalah algoritma klasifikasi gradient boosting yang membangun ensemble aturan logika murni (AND, OR, XOR, termasuk negasi NOT) dengan binarisasi fitur numerik adaptif berbasis gradien pada setiap iterasi boosting. Bobot tiap aturan dihitung dengan pendekatan Newton (memakai Hessian per fungsi loss) dan regularisasi adaptif berbasis dukungan sampel & kompleksitas aturan. Setiap weak learner berupa aturan yang dapat dibaca langsung oleh manusia tanpa memerlukan alat bantu penjelasan pasca-pelatihan.

## Kebaruan Utama
- **Binarisasi adaptif berbasis gradien**: nilai ambang batas fitur numerik dicari per iterasi untuk memaksimalkan korelasi dengan gradien saat ini
- **Ensemble aturan logika murni**: tidak ada pohon keputusan, setiap weak learner adalah aturan seperti: `(A AND B)`, `(C OR D)`, atau `(A AND NOT B)`
- **Youden J**: Penggunaan indeks Youden J sebagai `threshold='auto'` bawaan untuk menentukan titik potong prediksi, bukan fixed di 0.5 serta mengoptimalkan sensitivity + specificity pada data training, cocok untuk kasus kelas tidak seimbang
- **Fitur ternegasi (NOT)**: pencarian aturan otomatis mempertimbangkan dua polaritas (asli dan negasi) untuk tiap kandidat fitur 
- **Bobot aturan berbasis Newton (Hessian)**: bobot dua sisi tiap aturan dihitung dengan `w = G/(H+λ)`, memakai turunan kedua (Hessian) yang sesuai dengan fungsi loss yang dipilih (logistic, focal, atau poly), bukan sekadar rata-rata gradien
- **Regularisasi adaptif**: `λ` menyesuaikan otomatis terhadap jumlah sampel dan panjang aturan, sehingga aturan dengan cakupan kecil/kompleks ditahan bobotnya secara proporsional
- **Minimum-gain pruning (`gamma`)**: aturan dengan kontribusi terlalu kecil bisa ditolak sebelum masuk ensemble, membantu mencegah overfitting pada aturan yang terlalu spesifik
- **Dukungan multi-kelas**: lewat `binboost.multiclass.OneVsRestBinBoost`, BinBoost bisa dipakai untuk klasifikasi dengan lebih dari 2 kelas (strategi One-vs-Rest)

## Instalasi
```bash
pip install binboost
```

## Penggunaan Dasar untuk Klasifikasi Biner
```python
import numpy as np
from binboost import BinBoost

X = np.array([[1, 0, 1], [0, 1, 0], [1, 1, 0], [0, 0, 1]], dtype=float)
y = np.array([1, 0, 1, 0])

model = BinBoost(n_estimators=100, learning_rate=0.2, max_rule_length=4)
model.fit(X, y)

print(model.predict(X))
print(model.predict_proba(X))
print(model.rules_)

import pandas as pd
print(pd.DataFrame(model.rule_summary_))
```

## Penggunaan Multi-Kelas (>2 kelas)
Untuk label dengan lebih dari 2 kelas yang saling eksklusif, gunakan `OneVsRestBinBoost` — hyperparameter yang diteruskan persis sama dengan `BinBoost`:

```python
from binboost.multiclass import OneVsRestBinBoost

model = OneVsRestBinBoost(
    mode='multiclass',
    n_estimators=100,
    learning_rate=0.2,
    max_rule_length=4,
    lambda0=3.0,
)
model.fit(X, y)                          # y boleh berisi >2 kelas, mis. array string atau integer

print(model.predict(X))
print(model.predict_proba(X))            # dinormalisasi supaya tiap baris berjumlah 1
print(pd.DataFrame(model.rule_summary_)) # aturan per kelas, kolom 'kelas' menandai sub-model asalnya
```

`mode='multilabel'` tersedia untuk kasus di mana satu sampel bisa punya lebih dari satu label positif sekaligus dimana probabilitas tidak dinormalisasi, tiap kelas diputuskan independen.

## Hyperparameter Utama

| Parameter | Bawaan | Keterangan |
|---|---|---|
| `n_estimators` | 100 | Jumlah iterasi boosting |
| `learning_rate` | 0.2 | Faktor penyusutan tiap aturan |
| `loss` | `'logistic'` | Fungsi loss: `'logistic'`, `'focal'`, `'poly'` |
| `max_rule_length` | 4 | Jumlah maksimum fitur dalam satu aturan |
| `operators` | `['AND','OR']` | Operator logika yang digunakan ubah `use_xor=True` untuk mengaktifkan XOR |
| `beam_width` | 5 | Lebar beam search |
| `binarize_strategy` | `'gradient'` | Strategi binarisasi: `'gradient'`, `'quantile'`, `'uniform'`, `'kmeans'` |
| `subsample` | 0.8 | Fraksi data per iterasi |
| `feature_selection_threshold` | 0.0 | Ambang batas persentil gain fitur untuk seleksi kandidat (0.0 = semua fitur) |
| `min_samples_rule` | 5 | Jumlah/fraksi minimum sampel yang harus memenuhi sebuah aturan |
| `lambda0` | 3.0 | Konstanta regularisasi Newton adaptif |
| `gamma` | 0.0 | Ambang minimum gain untuk menerima sebuah aturan (0.0 = tanpa pruning, nonaktif secara bawaan) |

Fitur negasi (NOT) aktif otomatis pada pencarian aturan dan bukan hyperparameter yang bisa diatur lewat `BinBoost()` — ini bagian tetap dari mekanisme beam search.

## Fitur yang Didukung
- Fitur biner (0/1): langsung diproses
- Fitur numerik (int/float): dibinarisasi otomatis per iterasi
- Fitur kategorikal 3+ kelas: wajib OneHotEncode terlebih dahulu

```python
from sklearn.preprocessing import OneHotEncoder
enc = OneHotEncoder(sparse_output=False, drop='first')
X_encoded = enc.fit_transform(X[['kolom_kategorikal']])
```

BinBoost secara otomatis mendeteksi kelompok fitur OneHotEncoding dan mencegah aturan yang tidak masuk akal seperti `(Warna_Merah AND Warna_Biru)`.

## Atribut Setelah Pelatihan
```python
model.rules_               # daftar teks aturan termasuk NOT jika ada
model.rule_weights_        # bobot dua sisi [w0, w1] tiap aturan (hasil Newton + regularisasi)
model.feature_importances_ # skor kepentingan fitur
model.train_score_         # loss per iterasi
model.rule_summary_        # ringkasan lengkap atau konversi ke DataFrame
model.n_rules_             # jumlah aturan aktif
model.feature_usage_       # frekuensi penggunaan tiap fitur
model.thresholds_          # riwayat threshold biner per fitur numerik, per iterasi
```

## Lisensi
MIT
