# LightGBM Tools
[](https://github.com/telekom/lightgbm-tools/blob/main/LICENSE)
[](https://www.python.org)
[](https://pypi.python.org/pypi/lightgbm-tools)
This Python package implements tools for [LightGBM](https://lightgbm.readthedocs.io/).
In the current version lightgbm-tools focuses on binary classification metrics.
## What exact problem does this tool solve?
LightGBM has some [built-in metrics](https://lightgbm.readthedocs.io/en/v3.3.2/Parameters.html#metric) that can be used.
These are useful but limited. Some important metrics are missing.
These are, among others, the [F1-score](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.f1_score.html)
and the [average precision (AP)](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.average_precision_score.html).
These metrics can be easily added using this tool.
This happens through a mechanism built into LightGBM where we can assign a callback to the `feval` parameter of
`lightgbm.train` (see
[lightgbm.train](https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.train.html#lightgbm-train) documentation).
## Maintainers
[](https://www.welove.ai/)
<br/>
This project is maintained by the [One Conversation](https://www.welove.ai/)
team of [Deutsche Telekom AG](https://www.telekom.com/).
## Usage
You can find a fully functional example here: <https://github.com/telekom/lightgbm-tools/blob/main/examples/main_usage.py>
The easiest way is to use the predefined callback functions. These are:
- `lightgbm_tools.metrics.lgbm_f1_score_callback`
- `lightgbm_tools.metrics.lgbm_accuracy_score_callback`
- `lightgbm_tools.metrics.lgbm_average_precision_score_callback`
- `lightgbm_tools.metrics.lgbm_roc_auc_score_callback`
- `lightgbm_tools.metrics.lgbm_recall_score_callback`
- `lightgbm_tools.metrics.lgbm_precision_score_callback`
Here F1 is used as an example to show how the predefined callback functions can be used:
```python
import lightgbm
from lightgbm_tools.metrics import lgbm_f1_score_callback
bst = lightgbm.train(
params,
train_data,
valid_sets=val_data,
num_boost_round=6,
verbose_eval=False,
evals_result=evals_result,
feval=lgbm_f1_score_callback, # here we pass the callback to LightGBM
)
```
You can also reuse other implementations of metrics.
Here is an example of how to do this using the `balanced_accuracy_score` from scikit-learn:
```python
import lightgbm
from sklearn.metrics import balanced_accuracy_score
from lightgbm_tools.metrics import LightGbmEvalFunction, binary_eval_callback_factory
# define own custom eval (metric) function for balanced_accuracy_score
lgbm_balanced_accuracy = LightGbmEvalFunction(
name="balanced_accuracy",
function=balanced_accuracy_score,
is_higher_better=True,
needs_binary_predictions=True,
)
# use the factory function to create the callback
lgbm_balanced_accuracy_callback = binary_eval_callback_factory([lgbm_balanced_accuracy])
bst = lightgbm.train(
params,
train_data,
valid_sets=val_data,
num_boost_round=6,
verbose_eval=False,
evals_result=evals_result,
feval=lgbm_balanced_accuracy_callback, # here we pass the callback to LightGBM
)
```
This tool can also be used to calculate multiple metrics at the same time.
It can be done by passing several definitions of metrics (in a list) to the
`binary_eval_callback_factory`.
The followring predefined metric definitions (`LightGbmEvalFunction`) are available:
- `lightgbm_tools.metrics.lgbm_f1_score`
- `lightgbm_tools.metrics.lgbm_accuracy_score`
- `lightgbm_tools.metrics.lgbm_average_precision_score`
- `lightgbm_tools.metrics.lgbm_roc_auc_score`
- `lightgbm_tools.metrics.lgbm_recall_score`
- `lightgbm_tools.metrics.lgbm_precision_score`
Below is an example how to combine F1 and average precision:
```python
import lightgbm
from lightgbm_tools.metrics import (
binary_eval_callback_factory,
lgbm_average_precision_score,
lgbm_f1_score,
)
# use the factory function to create the callback
callback = binary_eval_callback_factory([lgbm_average_precision_score, lgbm_f1_score])
bst = lightgbm.train(
params,
train_data,
valid_sets=val_data,
num_boost_round=6,
verbose_eval=False,
evals_result=evals_result,
feval=callback, # here we pass the callback to LightGBM
)
```
## Installation
lightgbm-tools can be installed with pip:
```bash
pip install lightgbm-tools
```
To do development and run unit tests locally, ensure that you have installed all relevant requirements.
You will probably want to install it in "editable mode" if you are developing locally:
```bash
pip install -e .[all]
```
## Licensing
Copyright (c) 2022 [Philip May](https://may.la/), [Deutsche Telekom AG](https://www.telekom.com/)
Licensed under the **MIT License** (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License by reviewing the file
[LICENSE](https://github.com/telekom/lightgbm-tools/blob/main/LICENSE) in the repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/telekom/lightgbm-tools",
"name": "lightgbm-tools",
"maintainer": "Philip May",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "ml ai machine-learning metrics lightgbm",
"author": "Philip May",
"author_email": "philip@may.la",
"download_url": "https://files.pythonhosted.org/packages/ce/3f/5c3f0124df63af193a0e025fcefd2222a9d8dfef49fc5b00644e4a1be9fa/lightgbm_tools-0.0.2.tar.gz",
"platform": null,
"description": "# LightGBM Tools\n\n[](https://github.com/telekom/lightgbm-tools/blob/main/LICENSE)\n[](https://www.python.org)\n[](https://pypi.python.org/pypi/lightgbm-tools)\n\nThis Python package implements tools for [LightGBM](https://lightgbm.readthedocs.io/).\nIn the current version lightgbm-tools focuses on binary classification metrics.\n\n## What exact problem does this tool solve?\n\nLightGBM has some [built-in metrics](https://lightgbm.readthedocs.io/en/v3.3.2/Parameters.html#metric) that can be used.\nThese are useful but limited. Some important metrics are missing.\nThese are, among others, the [F1-score](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.f1_score.html)\nand the [average precision (AP)](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.average_precision_score.html).\n\nThese metrics can be easily added using this tool.\nThis happens through a mechanism built into LightGBM where we can assign a callback to the `feval` parameter of\n`lightgbm.train` (see\n[lightgbm.train](https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.train.html#lightgbm-train) documentation).\n\n## Maintainers\n\n[](https://www.welove.ai/)\n<br/>\nThis project is maintained by the [One Conversation](https://www.welove.ai/)\nteam of [Deutsche Telekom AG](https://www.telekom.com/).\n\n## Usage\n\nYou can find a fully functional example here: <https://github.com/telekom/lightgbm-tools/blob/main/examples/main_usage.py>\n\nThe easiest way is to use the predefined callback functions. These are:\n\n- `lightgbm_tools.metrics.lgbm_f1_score_callback`\n- `lightgbm_tools.metrics.lgbm_accuracy_score_callback`\n- `lightgbm_tools.metrics.lgbm_average_precision_score_callback`\n- `lightgbm_tools.metrics.lgbm_roc_auc_score_callback`\n- `lightgbm_tools.metrics.lgbm_recall_score_callback`\n- `lightgbm_tools.metrics.lgbm_precision_score_callback`\n\nHere F1 is used as an example to show how the predefined callback functions can be used:\n\n```python\nimport lightgbm\nfrom lightgbm_tools.metrics import lgbm_f1_score_callback\n\nbst = lightgbm.train(\n params,\n train_data,\n valid_sets=val_data,\n num_boost_round=6,\n verbose_eval=False,\n evals_result=evals_result,\n feval=lgbm_f1_score_callback, # here we pass the callback to LightGBM\n)\n```\n\nYou can also reuse other implementations of metrics.\nHere is an example of how to do this using the `balanced_accuracy_score` from scikit-learn:\n\n```python\nimport lightgbm\nfrom sklearn.metrics import balanced_accuracy_score\nfrom lightgbm_tools.metrics import LightGbmEvalFunction, binary_eval_callback_factory\n\n# define own custom eval (metric) function for balanced_accuracy_score\nlgbm_balanced_accuracy = LightGbmEvalFunction(\n name=\"balanced_accuracy\",\n function=balanced_accuracy_score,\n is_higher_better=True,\n needs_binary_predictions=True,\n)\n\n# use the factory function to create the callback\nlgbm_balanced_accuracy_callback = binary_eval_callback_factory([lgbm_balanced_accuracy])\n\nbst = lightgbm.train(\n params,\n train_data,\n valid_sets=val_data,\n num_boost_round=6,\n verbose_eval=False,\n evals_result=evals_result,\n feval=lgbm_balanced_accuracy_callback, # here we pass the callback to LightGBM\n)\n```\n\nThis tool can also be used to calculate multiple metrics at the same time.\nIt can be done by passing several definitions of metrics (in a list) to the\n`binary_eval_callback_factory`.\nThe followring predefined metric definitions (`LightGbmEvalFunction`) are available:\n\n- `lightgbm_tools.metrics.lgbm_f1_score`\n- `lightgbm_tools.metrics.lgbm_accuracy_score`\n- `lightgbm_tools.metrics.lgbm_average_precision_score`\n- `lightgbm_tools.metrics.lgbm_roc_auc_score`\n- `lightgbm_tools.metrics.lgbm_recall_score`\n- `lightgbm_tools.metrics.lgbm_precision_score`\n\nBelow is an example how to combine F1 and average precision:\n\n```python\nimport lightgbm\nfrom lightgbm_tools.metrics import (\n binary_eval_callback_factory,\n lgbm_average_precision_score,\n lgbm_f1_score,\n)\n\n# use the factory function to create the callback\ncallback = binary_eval_callback_factory([lgbm_average_precision_score, lgbm_f1_score])\n\nbst = lightgbm.train(\n params,\n train_data,\n valid_sets=val_data,\n num_boost_round=6,\n verbose_eval=False,\n evals_result=evals_result,\n feval=callback, # here we pass the callback to LightGBM\n)\n```\n\n## Installation\n\nlightgbm-tools can be installed with pip:\n\n```bash\npip install lightgbm-tools\n```\n\nTo do development and run unit tests locally, ensure that you have installed all relevant requirements.\nYou will probably want to install it in \"editable mode\" if you are developing locally:\n\n```bash\npip install -e .[all]\n```\n\n## Licensing\n\nCopyright (c) 2022 [Philip May](https://may.la/), [Deutsche Telekom AG](https://www.telekom.com/)\n\nLicensed under the **MIT License** (the \"License\"); you may not use this file except in compliance with the License.\nYou may obtain a copy of the License by reviewing the file\n[LICENSE](https://github.com/telekom/lightgbm-tools/blob/main/LICENSE) in the repository.\n",
"bugtrack_url": null,
"license": "",
"summary": "LightGM Tools",
"version": "0.0.2",
"split_keywords": [
"ml",
"ai",
"machine-learning",
"metrics",
"lightgbm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cfc640fdf972ff78106bfac246a9d6f67a12fbcf878fc1d437767c366cac3f9f",
"md5": "675de41c67db0b12522b5163fc3ede67",
"sha256": "904bd71c95a6b00e136348b6ba29542bce837af4cc24959b52070d4d3f855b92"
},
"downloads": -1,
"filename": "lightgbm_tools-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "675de41c67db0b12522b5163fc3ede67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5875,
"upload_time": "2023-01-05T21:07:03",
"upload_time_iso_8601": "2023-01-05T21:07:03.409577Z",
"url": "https://files.pythonhosted.org/packages/cf/c6/40fdf972ff78106bfac246a9d6f67a12fbcf878fc1d437767c366cac3f9f/lightgbm_tools-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce3f5c3f0124df63af193a0e025fcefd2222a9d8dfef49fc5b00644e4a1be9fa",
"md5": "e1f99094ba685e95153faed560fe3219",
"sha256": "efc17f88a9183e9c26bff0aabafbac3ce61b915f52e21725df212e0974d63be6"
},
"downloads": -1,
"filename": "lightgbm_tools-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e1f99094ba685e95153faed560fe3219",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6068,
"upload_time": "2023-01-05T21:07:05",
"upload_time_iso_8601": "2023-01-05T21:07:05.086329Z",
"url": "https://files.pythonhosted.org/packages/ce/3f/5c3f0124df63af193a0e025fcefd2222a9d8dfef49fc5b00644e4a1be9fa/lightgbm_tools-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-05 21:07:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "telekom",
"github_project": "lightgbm-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lightgbm-tools"
}
JSON
