{"id":27775287,"url":"https://github.com/amazon-science/auction-gym","last_synced_at":"2025-04-30T03:49:41.481Z","repository":{"id":49793751,"uuid":"506742955","full_name":"amazon-science/auction-gym","owner":"amazon-science","description":"AuctionGym is a simulation environment that enables reproducible evaluation of bandit and reinforcement learning methods for online advertising auctions.","archived":false,"fork":false,"pushed_at":"2025-04-24T07:23:33.000Z","size":124,"stargazers_count":169,"open_issues_count":3,"forks_count":40,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-30T03:49:36.172Z","etag":null,"topics":["advertising","machine-learning","real-time-bidding","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/amazon-science.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-23T18:04:40.000Z","updated_at":"2025-04-24T07:23:31.000Z","dependencies_parsed_at":"2023-01-31T07:31:16.671Z","dependency_job_id":"43043b9b-63e5-4551-a882-b8a4eec13a0f","html_url":"https://github.com/amazon-science/auction-gym","commit_stats":null,"previous_names":["amazon-science/auction-gym"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fauction-gym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fauction-gym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fauction-gym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fauction-gym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amazon-science","download_url":"https://codeload.github.com/amazon-science/auction-gym/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251638760,"owners_count":21619663,"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":["advertising","machine-learning","real-time-bidding","reinforcement-learning"],"created_at":"2025-04-30T03:49:40.948Z","updated_at":"2025-04-30T03:49:41.472Z","avatar_url":"https://github.com/amazon-science.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"## AuctionGym: Simulating Online Advertising Auctions\n\nThis repository contains the source code for AuctionGym: a simulation environment that enables reproducible offline evaluation of bandit and reinforcement learning approaches to ad allocation and bidding in online advertising auctions.\n\nAuctionGym was released in the context of our [\"Off-Policy Learning to Bid with AuctionGym\"](https://dl.acm.org/doi/10.1145/3580305.3599877) publication in the Applied Data Science Track of the [2023 ACM SIGKDD Conference](https://kdd.org/kdd2023/).\nAn [earlier version of our work](https://www.amazon.science/publications/learning-to-bid-with-auctiongym) was presented at the [AdKDD '22 workshop](https://www.adkdd.org/), where it received a Best Paper Award.\n\nOffline evaluation of \"learning to bid\" approaches is not straightforward, because of multiple reasons:\n(1) observational data suffers from unobserved confounding and experimental data with broad interventions is costly to obtain,\n(2) offline experiments suffer from Goodhart's Law: \" *when a measure becomes a target, it ceases to be a good measure* \", and \n(3) at the time of writing and to the best of our knowledge -- there are no publicly available datasets to researchers that can be used for this purpose.\nAs a result, reliable and reproducible validation of novel \"learning to bid\" methods is hindered, and so is open scientific progress in this field.\n\nAuctionGym aims to mitigate this problem, by providing a unified framework that practitioners and research can use to benchmark novel methods and gain insights into their inner workings.\n\n\n## Getting Started\n\nWe provide two introductory and exploratory notebooks. To open them, run `jupyter notebook` in the main directory and navigate to `src`.\n\n\" *Getting Started with AuctionGym (1. Effects of Competition)* \" simulates second-price auctions with varying levels of competition, visualising the effects on advertiser welfare and surplus, and revenue for the auctioneer.\nAnalogosuly, \" *Getting Started with AuctionGym (2. Effects of Bid Shading)* \" simulates first-price auctions where bidders bid truthfully vs. when they shade their bids in a value-based manner.\n\n\n## Reproducing Research Results\n\nThis section provides instructions to reproduce the results reported in our paper.\n\nWe provide a script that takes as input a configuration file detailing the environment and bidders (in JSON format), and outputs raw logged metrics over repeated auction rounds in .csv-files, along with visualisations.\nTo reproduce the results for truthful bidders in a second-price auction reported in Fig. 1 in the paper, run:\n\n```\npython src/main.py config/SP_Oracle.json\n```\n\nA `results`-directory will be created, with a subdirectory per configuration file that was ran. This subdirectory will contain .csv-files with raw metrics, and .pdf-files with general visualisations.\nOther configuration files will generate results for other environments, and other bidder behaviour.\nSee [configuration](CONFIG.md) for more detail on the structure of the configuration files.\n\n\n\n## Citing\n\n\nPlease cite the [accompanying research paper](https://dl.acm.org/doi/10.1145/3580305.3599877) if you use AuctionGym in your work:\n\n```BibTeX\n\t@inproceedings{10.1145/3580305.3599877,\n\t\tauthor = {Jeunen, Olivier and Murphy, Sean and Allison, Ben},\n\t\ttitle = {Off-Policy Learning-to-Bid with AuctionGym},\n\t\tyear = {2023},\n\t\tisbn = {9798400701030},\n\t\tpublisher = {Association for Computing Machinery},\n\t\taddress = {New York, NY, USA},\n\t\turl = {https://doi.org/10.1145/3580305.3599877},\n\t\tdoi = {10.1145/3580305.3599877},\n\t\tbooktitle = {Proceedings of the 29th ACM SIGKDD Conference on Knowledge Discovery and Data Mining},\n\t\tpages = {4219–4228},\n\t\tnumpages = {10},\n\t\tkeywords = {online advertising, counterfactual inference, off-policy learning},\n\t\tlocation = {Long Beach, CA, USA},\n\t\tseries = {KDD '23}\n\t}\n```\n\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Fauction-gym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famazon-science%2Fauction-gym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Fauction-gym/lists"}