Metadata-Version: 2.2
Name: ogboost
Version: 0.5.1
Summary: Ordinal Gradient Boosting
Author-email: "Alireza S. Mahani, Mansour T.A. Sharabiani" <alireza.s.mahani@gmail.com>
License: MIT License
        
        Copyright (c) 2024 asmahani
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: ordinal regression,gradient boosting,machine learning,scikit-learn
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: pydantic
Requires-Dist: pytest

# Ordinal Gradient Boosting (`OGBoost`)

`OGBoost` is a scikit-learn-compatible, Python package designed for gradient boosting tailored to ordinal regression problems. It does so by alternating between 1) fitting a base learner - which is, by default, a `DecisionTreeRegressor` - to predict a latent score that specifies the mean of a probability density function (PDF), and 2) fitting a set of thresholds that generate discrete outcomes from the PDF. In other words, `OGBoost` implements coordinate-descent optimization that combines functional gradient descent (the boosting stage) with ordinary gradient descent (for adjusting thresholds).

The main class in the package, `GradientBoostingOrdinal`, supports custom link functions, sample weighting, early stopping criteria, and staged predictions. In addition to methods for predicting class labels and probabilities, similar to nominal classifiers, the `decision_function` method of the class predicts the latent score, which can be used to achieve superior performance in discreiminative/ranking tasks.

## Features
- Fully compatible with scikit-learn pipelines.
- Customizable link functions: Probit, Logit, and Complementary Log-Log.
- Sample weighting for robust handling of imbalanced datasets.
- Subsampling for stochastic gradient boosting.
- Early stopping based on validation-set loss.
- Utility for downlaoding and using the `wine-quality` dataset from the [UCI ML repository](https://archive.ics.uci.edu/dataset/186/wine+quality).

## Installation
```bash
pip install ogboost
```

## Quick Start
### Load the Wine Quality Dataset
The package includes a utility to load the wine quality dataset from the UCI repository.

```python
from ogboost import load_wine_quality

# Load data
red_wine, white_wine = load_wine_quality()
X = red_wine.drop(columns="quality")
y = red_wine["quality"]
```

### Train a Gradient Boosting Ordinal Model
```python
from ogboost import GradientBoostingOrdinal

# Initialize and fit the model
model = GradientBoostingOrdinal(n_estimators=100, link_function='logit', verbose=1)
model.fit(X, y)

# Predict class labels and probabilities
predicted_labels = model.predict(X)
predicted_probabilities = model.predict_proba(X)

# Evaluate using the concordance index
from ogboost import concordance_index
c_index = concordance_index(y, model.decision_function(X))
print(f"Concordance Index: {c_index:.3f}")
```

## License
This package is licensed under the [MIT License](./LICENSE).
