Pushppp/pkboost-terminal-documentation

1```markdown2# PKBoost Python Package3 4The official Python wrapper for PKBoost, providing seamless integration with Python's machine learning ecosystem.5 6## Installation7 8```bash9pip install pkboost10```11 12## Quick Start13 14```python15import pkboost16import pandas as pd17from sklearn.model_selection import train_test_split18from sklearn.metrics import precision_recall_curve, auc19 20# Load your data21data = pd.read_csv('your_data.csv')22X = data.drop('target', axis=1)23y = data['target']24 25# Split the data26X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, stratify=y)27 28# Create and train PKBoost classifier29model = pkboost.PKBoostClassifier()30model.fit(X_train, y_train)31 32# Make predictions33y_pred_proba = model.predict_proba(X_test)[:, 1]34 35# Evaluate36precision, recall, _ = precision_recall_curve(y_test, y_pred_proba)37pr_auc = auc(recall, precision)38print(f"PR-AUC: {pr_auc:.4f}")39```40 41## PKBoostClassifier42 43The main classifier class with the following parameters:44 45```python46PKBoostClassifier(47    n_estimators=100,48    learning_rate=0.1,49    max_depth=6,50    min_samples_split=2,51    min_samples_leaf=1,52    subsample=1.0,53    colsample_bytree=1.0,54    reg_lambda=1.0,55    reg_alpha=0.0,56    random_state=None,57    n_jobs=-1,58    verbose=059)60```61 62### Key Features63 64- **Automatic Hyperparameter Tuning**: Use `auto_tune=True` for automatic configuration65- **Early Stopping**: Monitor validation performance with `eval_set`66- **Feature Importance**: Access via `feature_importances_` attribute67- **Handles Imbalance**: Built-in class weighting for imbalanced datasets68 69## Advanced Usage70 71### With Early Stopping72 73```python74from sklearn.model_selection import train_test_split75 76# Split into train, validation, test77X_train, X_temp, y_train, y_temp = train_test_split(X, y, test_size=0.3, stratify=y)78X_val, X_test, y_val, y_test = train_test_split(X_temp, y_temp, test_size=0.5, stratify=y_temp)79 80model = pkboost.PKBoostClassifier(81    n_estimators=1000,  # Set high, early stopping will determine actual number82    early_stopping_rounds=50,83    verbose=1084)85 86model.fit(87    X_train, y_train,88    eval_set=[(X_val, y_val)],89    verbose=True90)91```92 93### Automatic Hyperparameter Tuning94 95```python96model = pkboost.PKBoostClassifier(auto_tune=True)97model.fit(X_train, y_train)98```99 100### Cross-Validation101 102```python103from sklearn.model_selection import cross_val_score104 105model = pkboost.PKBoostClassifier()106scores = cross_val_score(model, X, y, cv=5, scoring='average_precision')107print(f"Mean PR-AUC: {scores.mean():.4f} (+/- {scores.std() * 2:.4f})")108```109 110## PKBoostAdaptive111 112For streaming data and concept drift scenarios:113 114```python115from pkboost import PKBoostAdaptive116 117# Initialize adaptive model118adaptive_model = PKBoostAdaptive(119    drift_detection_sensitivity=0.01,120    adaptation_rate=0.1,121    max_retraining_interval=1000122)123 124# For streaming data125for batch_X, batch_y in data_stream:126    adaptive_model.partial_fit(batch_X, batch_y)127    128    # Check if drift detected129    if adaptive_model.drift_detected:130        print("Concept drift detected! Model is adapting...")131    132    # Get current predictions133    predictions = adaptive_model.predict_proba(batch_X)134```135 136## Handling Large Datasets137 138### Batch Training139 140```python141model = pkboost.PKBoostClassifier()142 143# Train in batches144batch_size = 1000145for i in range(0, len(X_train), batch_size):146    X_batch = X_train[i:i+batch_size]147    y_batch = y_train[i:i+batch_size]148    model.partial_fit(X_batch, y_batch)149```150 151### Memory-Efficient Data Types152 153```python154# Use memory-efficient data types155X = X.astype('float32')156model.fit(X_train, y_train)157```158 159## Integration with Scikit-Learn160 161### Pipeline Integration162 163```python164from sklearn.pipeline import Pipeline165from sklearn.preprocessing import StandardScaler166from sklearn.impute import SimpleImputer167 168pipeline = Pipeline([169    ('imputer', SimpleImputer(strategy='median')),170    ('scaler', StandardScaler()),171    ('classifier', pkboost.PKBoostClassifier())172])173 174pipeline.fit(X_train, y_train)175```176 177### Grid Search178 179```python180from sklearn.model_selection import GridSearchCV181 182param_grid = {183    'n_estimators': [100, 200, 500],184    'learning_rate': [0.01, 0.1, 0.2],185    'max_depth': [3, 6, 9]186}187 188grid_search = GridSearchCV(189    pkboost.PKBoostClassifier(),190    param_grid,191    cv=5,192    scoring='average_precision',193    n_jobs=-1194)195 196grid_search.fit(X_train, y_train)197print(f"Best parameters: {grid_search.best_params_}")198```199 200## Model Persistence201 202### Save and Load Models203 204```python205import joblib206 207# Save model208joblib.dump(model, 'pkboost_model.pkl')209 210# Load model211loaded_model = joblib.load('pkboost_model.pkl')212```213 214### Native PKBoost Serialization215 216```python217# Save model in native format218model.save_model('model.pkboost')219 220# Load native model221loaded_model = pkboost.PKBoostClassifier()222loaded_model.load_model('model.pkboost')223```224 225## Performance Tips226 2271. **Data Preprocessing**: Ensure numerical features are scaled and categorical features are encoded2282. **Early Stopping**: Always use early stopping to prevent overfitting2293. **Subsampling**: For large datasets, use `subsample < 1.0` for faster training2304. **Parallelism**: Set `n_jobs=-1` to use all available cores2315. **Memory**: Use `float32` data types for large datasets232 233## Troubleshooting234 235### Common Issues236 237**Memory Errors**: Reduce `n_estimators` or use smaller `subsample` value238**Slow Training**: Try reducing `max_depth` or increasing `learning_rate`239**Poor Performance**: Enable `auto_tune=True` or adjust class weights240 241### Debug Mode242 243```python244model = pkboost.PKBoostClassifier(verbose=10)245model.fit(X_train, y_train)246```247 248## API Reference249 250### Methods251 252- `fit(X, y, eval_set=None, verbose=False)`: Train the model253- `predict(X)`: Predict class labels254- `predict_proba(X)`: Predict class probabilities255- `score(X, y)`: Return accuracy score256- `get_feature_importances()`: Return feature importance scores257 258### Attributes259 260- `feature_importances_`: Array of feature importances261- `n_estimators_`: Number of estimators actually used262- `classes_`: Class labels263- `best_score_`: Best validation score during training264 265## Examples266 267See the `examples/` directory for complete working examples:268 269- `example_creditcard.py`: Credit card fraud detection270- `example_drift.py`: Concept drift handling271- `example_pipeline.py`: Full ML pipeline272- `example_hyperparameter_tuning.py`: Advanced tuning techniques273 274## Support275 276For issues and questions:277- GitHub Issues: [PKBoost Repository](https://github.com/Pushp-Kharat1/PkBoost)278- Documentation: [PKBoost Docs](https://pushp-kharat1.github.io/PkBoost/)279 280## Citation281 282If you use PKBoost in your research, please cite:283 284```bibtex285@software{pkboost2025,286  title={PKBoost: Adaptive Gradient Boosting for Concept Drift},287  author={Kharat, Pushp},288  year={2025},289  url={https://github.com/Pushp-Kharat1/PkBoost}290}291```292```