Metadata-Version: 2.4
Name: xgbordinal
Version: 1.0.1
Summary: XGBOrdinal: An XGBoost Extension for Ordinal Data
Project-URL: Homepage, https://github.com/digital-medicine/XGBOrdinal
Project-URL: Repository, https://github.com/digital-medicine/XGBOrdinal
Project-URL: Issues, https://github.com/digital-medicine/XGBOrdinal/issues
Author-email: Fabian Kahl <fabian.kahl@ukbonn.de>
License: Software License
        1. Subject to the terms and conditions of this License, the Licensor hereby grants the Licensee a royalty-free, non-sublicensable, non-exclusive, revocable right to to use the Software exclusively for non-commercial purposes.
        2. The Licensee may install, use, copy and pass on the software as long as these conditions are complied with:
        i. The Software may not be used for commercial purposes.
        ii. The Licensee may not make any changes to the Software or create derivative works.
        iii. The Licensee must enclose this License with any transfer of the Software.
        3. Nothing in this License constitutes or may be construed as permission to assert or imply that the use of the Software is connected with, or sponsored, endorsed, or granted by the Licensor or others designated.
        4. The Licensor remains the sole owner of all right, title and interest in and to the Software, including all copyrights, patents and trademarks. Patent and trademark rights are not licensed under this License.
        5. To the extent possible, the Licensor waives any right to collect royalties for the exercise of the licensed rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Software is used other than for non commercial purposes.
        6. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Software as-is and as-available, and makes no representations or warranties of any kind concerning the Software, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. To the extent possible, in no event will the Licensor be liable on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this License or use of the Software, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply. 
        7. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. The Licensee uses the Software at his own risk.
        8. This License shall remain in force as long as the Licensee complies with the terms of this License. In the event of a breach of these terms, the License shall automatically terminate and the Licensee must immediately uninstall the Software and delete all copies thereof.
        9. This License shall be governed by and construed in accordance with the laws of the Federal Republic of Germany, excluding the conflict of laws rules of German private international law.
        10. To the extent possible, if any provision of this License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this License without affecting the enforceability of the remaining terms and conditions.
License-File: LICENSE.txt
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0.3
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: xgboost>=2.0.3
Description-Content-Type: text/markdown

# XGBOrdinal

This GitHub repository contains the code used in the paper:

> [_**XGBOrdinal: An XGBoost Extension for Ordinal Data**_](https://doi.org/10.3233/shti250380)  
> **Fabian Kahl, Iris Kahl, Stephan M. Jonas**  
> **Presented at MIE 2025**  
> Published in _Studies in Health Technology and Informatics_, Volume 327, Pages 462–466  

### Citation
```bibtex
@article{kahl2025xgbordinal,
  title={XGBOrdinal: An XGBoost Extension for Ordinal Data},
  author={Kahl, Fabian and Kahl, Iris and Jonas, Stephan M},
  journal={Studies in health technology and informatics},
  volume={327},
  pages={462--466},
  year={2025}
}
```

## Requirements
To install the required packages, run the following command:
```bash
git clone https://github.com/digital-medicine/XGBOrdinal.git
cd XGBOrdinal
pip install -r requirements.txt
```

## Demos
- `./demo.ipynb` to run XGBOrdinal with and without GridSearchCV in Jupyter Notebook.
- `./demo.py` to run XGBOrdinal with and without GridSearchCV in Python.

## Parameters
**`XGBOrdinal(aggregation='weighted', norm=True, **extra_params)`**
- `aggregation: str`
    - **Description**: Defines the method for aggregating model across the classifiers.
    - **Purpose**: Controls how to combine the classifiers. Supported values:
        - `'weighted'`: Uses class distribution-based weights.
        - `'equal'`: Uses equal weights for all classifiers.
    - **Default**: `'weighted'`.
- `norm: bool`
    - **Description**: Whether to replace all negative outcomes with zero and normalize them so they sum to 1.
    - **Purpose**: Ensures the outputs are probabilities for each sample.
    - **Default**: `True`.
- `**extra_params`:
    - **Description**: Additional parameters passed to the underlying `XGBClassifier`s.
    - **Purpose**: Customize the underlying classifiers in terms of hyperparameters.
    - **Example**: `'learning_rate'=0.1`, `'max_depth'=3`.

## Methods
- `fit(X, y, **fit_params)`
    - **Description**: Trains multiple binary classifiers based on the ordinal thresholds derived from `unique_classes`.
    - **Parameters**:
        - `X`: The feature matrix for training.
        - `y`: The target vector for training.
        - `**fit_params`: Additional parameters passed to the underlying `XGBClassifier`s (e.g., `eval_set`).
- `predict(X)`
    - **Description**: Predicts the class label for each sample based on the highest predicted probability.
    - **Parameters**:
        - `X`: The feature matrix for prediction.
    - **Returns**: The predicted class labels.
- `predict_proba(X)`
    - **Description**: Predicts the probabilities for each ordinal class.
    - **Parameters**:
        - `X`: The feature matrix for prediction.
    - **Returns**: A 2D array where each row contains the predicted probabilities for each class.
    - **Note**: If `norm=True`, the probabilities will sum to 1 for each sample.
- `feature_importance(importance_type='gain')`
    - **Description**: Computes feature importance across all classifiers, aggregated using the specified `aggregation` strategy.
    - **Parameters**:
        - `importance_type`: Type of `XGBoost` importance to compute (e.g., `'gain'`, `'weight'`, `'cover'`).
    - **Returns**: A dictionary of feature importance scores.

## Folder Structure
- `./experiments` contains the experiments of the paper.
