{"id":18317186,"url":"https://github.com/ibotta/mr_uplift","last_synced_at":"2026-03-07T05:33:09.256Z","repository":{"id":39728848,"uuid":"251754430","full_name":"Ibotta/mr_uplift","owner":"Ibotta","description":"Multiple Response Uplift (or heterogeneous treatment effects) package that builds and evaluates tradeoffs with multiple treatments and multiple responses","archived":false,"fork":false,"pushed_at":"2024-07-30T21:28:34.000Z","size":584,"stargazers_count":66,"open_issues_count":2,"forks_count":9,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-09T23:10:45.905Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ibotta.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2020-03-31T22:09:37.000Z","updated_at":"2024-08-30T10:41:41.000Z","dependencies_parsed_at":"2023-01-23T03:01:09.266Z","dependency_job_id":null,"html_url":"https://github.com/Ibotta/mr_uplift","commit_stats":null,"previous_names":["ibotta/ibotta_uplift"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ibotta%2Fmr_uplift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ibotta%2Fmr_uplift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ibotta%2Fmr_uplift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ibotta%2Fmr_uplift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ibotta","download_url":"https://codeload.github.com/Ibotta/mr_uplift/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125609,"owners_count":21051770,"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-05T18:05:20.524Z","updated_at":"2026-03-07T05:33:09.203Z","avatar_url":"https://github.com/Ibotta.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. figure:: https://github.com/Ibotta/mr_uplift/blob/master/doc/images/mr_uplift_logo.png\n   :alt: mr_erupt\n\nmr_uplift: Machine learning Uplift Package\n========================================================\n\n\nIntroduction\n-----------------\nThere are currently several packages for uplift models (see `EconML \u003chttps://github.com/microsoft/EconML\u003e`__ ,  `GRF \u003chttps://github.com/grf-labs/grf\u003e`__, `PTE \u003chttps://cran.r-project.org/web/packages/PTE/index.html\u003e`__). They tend to focus on interesting ways of estimating the heterogeneous treatment effect. However models in their current state tend to focus on the single response, singe treatment scenario. In addition the metrics they use do not give estimates to the expectations of response variables if the models were used in practice (PTE is an exception).\n\nThis package attempts to build an automated solution for Uplift modeling that includes the following features:\n\n#. It allows for Multiple Treatments. In addition one can incorporate meta features for each treatment. For example; a particular treatment might have several shared features with other bonuses. Instead of creating a dummy indicator for each bonus the user can create a vector of categorial or continuous variables to represent the treatment.\n#. `ERUPT \u003chttps://medium.com/building-ibotta/erupt-expected-response-under-proposed-treatments-ff7dd45c84b4\u003e`__ functionality that estimates model performance on OOS data. This metric calculates the expected response if the model were given to the average user similar to .\n#. Support for multiple responses. This allows estimation of tradeoffs between maximizing / minimizing weighted sums of responses. An example can be found `here \u003chttps://medium.com/building-ibotta/estimating-and-visualizing-business-tradeoffs-in-uplift-models-80ff845a5698\u003e`__\n\nIt does so by estimating a neural network of the form y ∼ f(t,x) where y, x, and t are the response, explanatory variables and treatment variables. If `optim_loss=True` then an experimental loss function is used to estimate the function (see `here \u003chttps://github.com/Ibotta/mr_uplift/blob/master/examples/mr_uplift_new_optimized_loss.ipynb\u003e`__). If the treatment was not randomly assigned there is functionality for propensity scores (see `here \u003chttps://github.com/Ibotta/mr_uplift/blob/master/examples/mr_uplift_propensity_score.ipynb\u003e`__). There is functionality to predict counterfactuals for all treatments and calculates ERUPT metrics on out of sample data. \n\n\nQuick Start Example\n-------------------\n\nIn a python enviornment :\n\n.. code-block:: python\n\n    import numpy as np\n    import pandas as pd\n\n    from mr_uplift.dataset.data_simulation import get_simple_uplift_data\n    from mr_uplift.mr_uplift import MRUplift\n\n    #Generate Data\n    y, x, t = get_simple_uplift_data(10000)\n    y = pd.DataFrame(y)\n    y.columns = ['revenue','cost', 'noise']\n    y['profit'] = y['revenue'] - y['cost']\n\n    #Build / Gridsearch model\n    uplift_model = MRUplift()\n    param_grid = dict(num_nodes=[8], dropout=[.1, .5], activation=[\n                          'relu'], num_layers=[1, 2], epochs=[25], batch_size=[30])\n    uplift_model.fit(x, y, t.reshape(-1,1), param_grid = param_grid, n_jobs = 1)\n\n    #OOS ERUPT Curves\n    erupt_curves, dists = uplift_model.get_erupt_curves()\n\n    #predict optimal treatments with new observations\n    _, x_new ,_  = get_simple_uplift_data(5)\n    uplift_model.predict_optimal_treatments(x_new, objective_weights = np.array([.6,-.4,0,0]).reshape(1,-1))\n\n\n.. figure:: https://github.com/Ibotta/mr_uplift/blob/master/doc/images/erupt_curves.png\n   :alt: erupt-curves\n\nRelevant Papers and Blog Posts\n------------------------------\n\nFor Discussion on the metric used to calculate how model performs see:\n\n`ERUPT: Expected Response Under Proposed Treatments \u003chttps://medium.com/building-ibotta/erupt-expected-response-under-proposed-treatments-ff7dd45c84b4\u003e`__\n\n`Uplift Modeling with Multiple Treatments and General Response Types \u003chttps://arxiv.org/pdf/1705.08492.pdf\u003e`__\n\n`Heterogeneous Treatment Effects and Optimal Targeting Policy Evaluation \u003chttps://papers.ssrn.com/sol3/papers.cfm?abstract_id=3111957\u003e`__\n\n`A comparison of methods for model selection when estimating individual treatment effects \u003chttps://arxiv.org/pdf/1804.05146.pdf\u003e`__\n\n`Inference for the Effectiveness of Personalized Medicine with Software \u003chttps://arxiv.org/pdf/1404.7844.pdf\u003e`__\n\nFor tradeoff analysis see:\n\n`Estimating and Visualizing Business Tradeoffs in Uplift Models \u003chttps://medium.com/building-ibotta/estimating-and-visualizing-business-tradeoffs-in-uplift-models-80ff845a5698\u003e`__\n\n`Experimental Evaluation of Individualized Treatment Rules \u003chttps://imai.fas.harvard.edu/research/files/indtreat.pdf\u003e`__\n\nFor optimized loss see:\n\n`Maximizing The ERUPT Metric for Uplift Models \u003chttps://medium.com/building-ibotta/maximizing-the-erupt-metric-for-uplift-models-f8d7e57bfdf2\u003e`__\n\n`Methods for Individual Treatment Assignment: An Application and Comparison for Playlist Generation \u003chttps://arxiv.org/pdf/2004.11532.pdf\u003e`__\n\nAcknowledgements\n~~~~~~~~~~~~~~~~\nThanks to `Evan Harris \u003chttps://github.com/denver1117\u003e`__, `Andrew Tilley \u003chttps://github.com/tilleyand\u003e`__, `Matt Johnson \u003chttps://github.com/mattsgithub\u003e`__, and `Nicole Woytarowicz \u003chttps://github.com/nicolele\u003e`__  for internal review before open source. Thanks to `James Foley \u003chttps://github.com/chadfoley36\u003e`__ for logo artwork.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibotta%2Fmr_uplift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibotta%2Fmr_uplift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibotta%2Fmr_uplift/lists"}