Metadata-Version: 2.4
Name: gboostlytec
Version: 0.1.1
Summary: Deteksi anomali unsupervised menggunakan Gradient Boosting dengan hybrid residual dan ensemble voting
Author: Rangga Wahyu Pratama
Author-email: Rangga Wahyu Pratama <ranggawahyupratama386@gmail.com>
License: MIT
Keywords: anomaly detection,gradient boosting,unsupervised learning,machine learning,outlier detection
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
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.19.0
Requires-Dist: scikit-learn>=0.24.0
Requires-Dist: scipy>=1.5.0
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# GBoostLyTec - Deteksi Anomali Unsupervised dengan Gradient Boosting

![Python Version](https://img.shields.io/badge/Python-3.8%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Version](https://img.shields.io/badge/Version-1.0.0-orange)

**GBoostLyTec** adalah library Python untuk deteksi anomali unsupervised yang menggabungkan algoritma gradient boosting dengan hybrid residual, loss functions yang dapat dikonfigurasi, iterative cleaning, dan ensemble voting.

## Fitur Utama

- **Unsupervised**: Tidak memerlukan label data
- **Hybrid Residual**: Menggabungkan reconstruction error dan neighborhood deviation
- **Loss Functions Fleksibel**: Squared error, robust (Huber), atau quantile
- **Iterative Cleaning**: Pembersihan data progresif setiap iterasi
- **Subspace Boosting**: Random feature selection untuk setiap weak learner
- **Ensemble Voting**: Consensus-based anomaly scoring
- **Mahalanobis Distance**: Memperhitungkan struktur covariance features
- **Scikit-learn Compatible**: API yang familiar dan mudah digunakan

## Instalasi

### Dari PyPI
```bash
pip install gboostlytec
```

## Quick Start

### Penggunaan Dasar

```python
from gboostlytec import GBoostLyTec
import numpy as np

# Data Anda (unsupervised - tidak perlu label!)
X = np.random.randn(500, 10)

# Inisialisasi model
model = GBoostLyTec(n_estimators=30, loss_type='robust')

# Training
model.fit(X)

# Prediksi
anomaly_scores, anomaly_labels = model.predict(X)

print(f"Anomali terdeteksi: {anomaly_labels.sum()}")
print(f"Mean anomaly score: {anomaly_scores.mean():.4f}")
```

### Dengan Evaluasi

```python
from gboostlytec import GBoostLyTec
from gboostlytec.utils import generate_synthetic_data, evaluate_predictions

# Generate synthetic data dengan true labels untuk evaluasi
X, y_true = generate_synthetic_data(
    n_normal=500,
    n_anomalies=50,
    n_features=10,
    random_state=42
)

# Train model
model = GBoostLyTec(n_estimators=30, loss_type='robust', random_state=42)
model.fit(X)

# Prediksi
scores, labels = model.predict(X)

# Evaluasi
metrics = evaluate_predictions(y_true, labels, scores, verbose=True)
```

##  Hyperparameter

```python
model = GBoostLyTec(
    # Boosting parameters
    n_estimators=30,           # Jumlah iterasi boosting
    learning_rate=0.05,        # Learning rate awal
    adaptive_lr=True,          # Adaptive decay learning rate
    
    # Residual computation
    alpha=0.6,                 # Bobot reconstruction vs neighborhood
    n_neighbors=5,             # Neighbors untuk neighborhood deviation
    
    # Loss function 
    loss_type='robust',        # 'squared_error', 'robust', atau 'quantile'
    robust_loss_delta=1.0,     # Delta untuk Huber loss
    quantile_level=0.95,       # Quantile level
    
    # Decision Tree
    max_depth=4,               # Kedalaman tree maksimal
    min_samples_split=10,      # Minimum samples untuk split
    
    # Cleaning strategy
    cleaning_rate=0.05,        # Fraksi anomali dihapus per iterasi
    
    # Reproducibility
    random_state=42,           # Random seed
    verbose=1                  # Print progress
)
```

## API Reference

### fit(X)
```python
model.fit(X)
```
Latih model pada data unsupervised.

**Parameter:**
- `X` (array-like, shape (n_samples, n_features)): Data training

**Return:** self

### predict(X)
```python
anomaly_scores, anomaly_labels = model.predict(X)
```
Prediksi anomaly scores dan binary labels.

**Return:**
- `anomaly_scores` (array, shape (n_samples,)): Scores [0, 1]
- `anomaly_labels` (array, shape (n_samples,)): Labels 0/1

### decision_function(X)
```python
scores = model.decision_function(X)
```
Hitung anomaly scores saja.

### predict_proba(X)
```python
proba = model.predict_proba(X)
```
Return probability estimates [P(normal), P(anomali)].

### get_summary()
```python
summary = model.get_summary()
```
Dapatkan training statistics.

## Utility Functions

### generate_synthetic_data()
```python
X, y_true = generate_synthetic_data(
    n_normal=500,
    n_anomalies=50,
    n_features=10,
    random_state=42
)
```

### evaluate_predictions()
```python
metrics = evaluate_predictions(
    y_true, 
    y_pred, 
    y_scores=None, 
    verbose=True
)
```

## Contoh Real-World

### Deteksi Anomali pada Data Transaksi

```python
import pandas as pd
from gboostlytec import GBoostLyTec

# Load data transaksi
df = pd.read_csv('transactions.csv')

# Feature selection dan preprocessing
features = ['amount', 'duration', 'merchant_count', ...]
X = df[features].values

# Normalisasi (GBoostLyTec melakukan standardisasi otomatis)
from sklearn.preprocessing import StandardScaler
scaler = StandardScaler()
X_scaled = scaler.fit_transform(X)

# Deteksi anomali
model = GBoostLyTec(n_estimators=50, loss_type='robust')
model.fit(X_scaled)

scores, labels = model.predict(X_scaled)

# Add hasil ke dataframe
df['anomaly_score'] = scores
df['is_anomaly'] = labels

# Filter anomali
suspicious_transactions = df[df['is_anomaly'] == 1]
print(f"Transaksi mencurigakan: {suspicious_transactions.shape[0]}")
```

## Performa

Pada synthetic dataset (550 samples, 50 anomali):
- **Precision**: 0.8364
- **Recall**: 0.9200
- **F1-Score**: 0.8762
- **ROC-AUC**: 0.9510
- **Training Time**: ~2 detik

## Cara Memilih Hyperparameter

### Loss Function
- **squared_error**: Default, general purpose, sensitif outlier
- **robust**: Recommended jika ada extreme outliers
- **quantile**: Fokus pada tail distribution

### Alpha
- **0.7-0.9**: Emphasize global reconstruction patterns
- **0.3-0.5**: Emphasize local neighborhood patterns
- **0.5-0.6**: Balanced (recommended)

### n_estimators
- **10-20**: Fast, exploratory analysis
- **30-50**: Balanced speed vs accuracy (recommended)
- **100+**: More accurate, slower


## License

Project ini menggunakan MIT License
---

