{"id":19505268,"url":"https://github.com/interpretml/fasterrisk","last_synced_at":"2025-07-18T01:06:54.223Z","repository":{"id":62593106,"uuid":"543630639","full_name":"interpretml/FasterRisk","owner":"interpretml","description":"Create sparse and accurate risk scoring systems!","archived":false,"fork":false,"pushed_at":"2024-08-03T03:50:05.000Z","size":2383,"stargazers_count":37,"open_issues_count":4,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-25T14:18:07.692Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interpretml.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-30T14:05:59.000Z","updated_at":"2025-04-27T07:42:02.000Z","dependencies_parsed_at":"2024-11-10T22:30:54.218Z","dependency_job_id":null,"html_url":"https://github.com/interpretml/FasterRisk","commit_stats":{"total_commits":107,"total_committers":4,"mean_commits":26.75,"dds":0.2429906542056075,"last_synced_commit":"78defb3d63ba48283513995fb681cb0947491717"},"previous_names":["interpretml/fasterrisk","jiachangliu/fasterrisk"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/interpretml/FasterRisk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interpretml%2FFasterRisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interpretml%2FFasterRisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interpretml%2FFasterRisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interpretml%2FFasterRisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interpretml","download_url":"https://codeload.github.com/interpretml/FasterRisk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interpretml%2FFasterRisk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265686837,"owners_count":23811212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T22:29:25.693Z","updated_at":"2025-07-18T01:06:54.176Z","avatar_url":"https://github.com/interpretml.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fasterrisk \u003c!-- omit in toc --\u003e\n\n[![docs](https://readthedocs.org/projects/fasterrisk/badge/?version=latest)](https://readthedocs.org/projects/fasterrisk/?badge=latest)\n[![pypi](https://img.shields.io/pypi/v/fasterrisk?color=blue)](https://pypi.org/project/fasterrisk/)\n[![license](https://img.shields.io/badge/License-BSD-brightgreen)](https://github.com/jiachangliu/FasterRisk/blob/main/LICENSE)\n[![Downloads](https://pepy.tech/badge/fasterrisk)](https://pepy.tech/project/fasterrisk)\n[![downloads](https://img.shields.io/pypi/dm/fasterrisk)](https://pypistats.org/packages/fasterrisk)\n[![arxiv badge](https://img.shields.io/badge/arXiv-2210.05846-red)](https://arxiv.org/abs/2210.05846)\n\nThis repository contains source code to our NeurIPS 2022 paper:\n\n[**FasterRisk: Fast and Accurate Interpretable Risk Scores**](https://arxiv.org/abs/2210.05846)\n\n- Documentation: [https://fasterrisk.readthedocs.io](https://fasterrisk.readthedocs.io)\n- GitHub: [https://github.com/jiachangliu/FasterRisk](https://github.com/jiachangliu/FasterRisk)\n- PyPI: [https://pypi.org/project/fasterrisk/](https://pypi.org/project/fasterrisk/)\n- Free and open source software: [BSD license](https://github.com/jiachangliu/FasterRisk/blob/main/LICENSE)\n\n# Table of Content \u003c!-- omit in toc --\u003e\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Python Usage](#python-usage)\n- [R tutorial](#r-tutorial)\n- [License](#license)\n- [Contributing](#contributing)\n\n\n# Introduction\nOver the last century, risk scores have been the most popular form of predictive model used in healthcare and criminal justice. Risk scores are sparse linear models with integer coefficients; often these models can be memorized or placed on an index card. Below is a risk score example created on the 3rd fold of the [adult dataset](https://github.com/ustunb/risk-slim/tree/master/examples/data) by FasterRisk, predicting salary\u003e 50K.\n\n|                            |             |       |\n| :---                       |    ---:     |  :--- |\n|1.  No High School Diploma  |   -4 points |   ... |\n|2.     High School Diploma  |   -2 points | + ... |\n|3.            Age 22 to 29  |   -2 points | + ... |\n|4.       Any Capital Gains  |    3 points | + ... |\n|5.                 Married  |    4 points | + ... |\n|                            |       SCORE | =     |\n\n|      |        |        |        |        |        |        |        |\n|:---  | :----: | :----: | :----: | :----: | :----: | :----: | :----: | \n|SCORE |  -8  |  -6  |  -5  |  -4  |  -3  |  -2  |  -1  |\n|RISK  |   0.1% |   0.4% |   0.7% |   1.2% |   2.3% |   4.2% |   7.6% |\n|SCORE |  0  |   1  |   2  |   3  |   4  |   5  |   7  |        \n|RISK  |  13.3% |  22.3% |  34.9% |  50.0% |  65.1% |  77.7% |  92.4% |\n\nTypically, risk scores have been created either without data or by rounding logistic regression coefficients, but these methods do not reliably produce high-quality risk scores. Recent work used mathematical programming, which is computationally slow.\n\nWe introduce an approach for efficiently producing a collection of high-quality risk scores learned from data. Specifically, our approach produces a pool of almost-optimal sparse continuous solutions, each with a different support set, using a beam-search algorithm. Each of these continuous solutions is transformed into a separate risk score through a \"star ray\" search, where a range of multipliers are considered before rounding the coefficients sequentially to maintain low logistic loss. Our algorithm returns all of these high-quality risk scores for the user to consider. This method completes within minutes and can be valuable in a broad variety of applications.\n\n# Installation\n\n```bash\nconda create -n FasterRisk python=3.9 # create a virtual environment\nconda activate FasterRisk # activate the virtual environment\npython -m pip install fasterrisk # pip install the fasterrisk package\n```\n\n\n# Python Usage\nPlease see the [example.ipynb](https://github.com/jiachangliu/FasterRisk/blob/main/docs/example.ipynb) jupyter notebook on GitHub or [Example Usage](https://fasterrisk.readthedocs.io/en/latest/example.html) on Read the Docs for a detailed tutorial on how to use FasterRisk in a python environment. The detailed descriptions of key functions can be found in the [API Reference](https://fasterrisk.readthedocs.io/en/latest/autoapi/index.html) on Read the Docs.\n\nThere are two major two classes for the users to interact with:\n- **RiskScoreOptimizer**\n```python\nsparsity = 5 # produce a risk score model with 5 nonzero coefficients \n\n# import data\nX_train, y_train = ...\n\n# initialize a risk score optimizer\nm = RiskScoreOptimizer(X = X_train, y = y_train, k = sparsity)\n\n# perform optimization\nm.optimize()\n\n# get all top m solutions from the final diverse pool\narr_multiplier, arr_intercept, arr_coefficients = m.get_models() # get m solutions from the diverse pool; Specifically, arr_multiplier.shape=(m, ), arr_intercept.shape=(m, ), arr_coefficients.shape=(m, p)\n\n# get the first solution from the final diverse pool by passing an optional model_index; models are ranked in order of increasing logistic loss\nmultiplier, intercept, coefficients = m.get_models(model_index = 0) # get the first solution (smallest logistic loss) from the diverse pool; Specifically, multiplier.shape=(1, ), intercept.shape=(1, ), coefficients.shape=(p, )\n\n```\n\n- **RiskScoreClassifier**\n```python\n# import data\nX_featureNames = ... # X_featureNames is a list of strings, each of which is the feature name\n\n# create a classifier\nclf = RiskScoreClassifier(multiplier = multiplier, intercept = intercept, coefficients = coefficients, featureNames = featureNames)\n\n# get the predicted label\ny_pred = clf.predict(X = X_train)\n\n# get the probability of predicting y[i] with label +1\ny_pred_prob = clf.predict_prob(X = X_train)\n\n# compute the logistic loss\nlogisticLoss_train = clf.compute_logisticLoss(X = X_train, y = y_train)\n\n# get accuracy and area under the ROC curve (AUC)\nacc_train, auc_train = clf.get_acc_and_auc(X = X_train, y = y_train) \n\n# print the risk score model card\nm.print_model_card()\n```\n\n# R tutorial\nFasterRisk can also be easily used inside R. See the [R tutorial](https://github.com/jiachangliu/FasterRisk/blob/main/R_tutorial/README.md) on how to apply FasterRisk on an example dataset. \n\n# License\n\n`fasterrisk` was created by Jiachang Liu. It is licensed under the terms of the BSD 3-Clause license.\n\n# Contributing\n\nInterested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.\n\n# Credits \u003c!-- omit in toc --\u003e\n\n`fasterrisk` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).\n\n# Citing Our Work \u003c!-- omit in toc --\u003e\n\nIf you find our work useful in your research, please consider citing the following paper:\n\n```BibTeX\n@article{liu2022fasterrisk,\n  title={FasterRisk: Fast and Accurate Interpretable Risk Scores},\n  author={Liu, Jiachang and Zhong, Chudi and Li, Boxuan and Seltzer, Margo and Rudin, Cynthia},\n  booktitle={Proceedings of Neural Information Processing Systems},\n  year={2022}\n}\n```\n\n\u003c!-- # How to Build and Push to pypi-test and pypi\n```terminal\nrm dist/*\npoetry build\npoetry config repositories.test-pypi https://test.pypi.org/legacy/\n\n# push to pypi-test\npoetry publish -r test-pypi -u __token__ -p pypi-TOKEN\npython -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple fasterrisk\n\n# push to pypi\npoetry publish -u __token__ -p pypi-TOKEN\n\n``` --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterpretml%2Ffasterrisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterpretml%2Ffasterrisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterpretml%2Ffasterrisk/lists"}