{"id":22929620,"url":"https://github.com/sb-ai-lab/hypex","last_synced_at":"2025-04-04T22:00:22.477Z","repository":{"id":205992877,"uuid":"712815595","full_name":"sb-ai-lab/HypEx","owner":"sb-ai-lab","description":"Fast and customizable framework for automatic and quick Causal Inference in Python","archived":false,"fork":false,"pushed_at":"2025-03-27T14:24:24.000Z","size":65774,"stargazers_count":109,"open_issues_count":13,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-28T09:29:14.215Z","etag":null,"topics":["ab-testing","causal-inference","causalinference","data-science","faiss","kaggle","matching","python","statistics"],"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/sb-ai-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-01T08:58:57.000Z","updated_at":"2025-03-25T14:14:33.000Z","dependencies_parsed_at":"2023-12-11T09:29:04.678Z","dependency_job_id":"6376847f-d896-48d4-a43d-d23ae6ec2bb2","html_url":"https://github.com/sb-ai-lab/HypEx","commit_stats":null,"previous_names":["sb-ai-lab/hypex"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sb-ai-lab%2FHypEx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sb-ai-lab%2FHypEx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sb-ai-lab%2FHypEx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sb-ai-lab%2FHypEx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sb-ai-lab","download_url":"https://codeload.github.com/sb-ai-lab/HypEx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256093,"owners_count":20909240,"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":["ab-testing","causal-inference","causalinference","data-science","faiss","kaggle","matching","python","statistics"],"created_at":"2024-12-14T10:09:07.825Z","updated_at":"2025-04-04T22:00:22.436Z","avatar_url":"https://github.com/sb-ai-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HypEx: Advanced Causal Inference and AB Testing Toolkit\n\n![Last release](https://img.shields.io/badge/pypi-v0.1.10-darkgreen)\n[![Telegram](https://img.shields.io/badge/chat-on%20Telegram-2ba2d9.svg)](https://t.me/hypexchat)\n![Pypi downloads](https://img.shields.io/badge/downloads-70K-1E782B)\n![Python versions](https://img.shields.io/badge/python-3.8_|_3.9_|_3.10_|_3.11_|_3.12-blue)\n![Pypi downloads\\month](https://img.shields.io/badge/downloads\\month-\u003e10K-1E782B)\n\n# Moving to a New Architecture! ⚠️\n\n## ❗ ВАЖНОЕ ОБНОВЛЕНИЕ: HypEx переходит на новую архитектуру! ❗\n\n## 🔥 What's changing? / Что изменится?\n\nNew interface! Import paths, class methods, and overall API structure will be different.\n\nOld version (0.1.10) will no longer be supported.\n\nNew tutorials are available to help you migrate: Check them\nout [here](https://github.com/sb-ai-lab/HypEx/tree/master/examples/tutorials).\n\nTry the new version now by installing the beta release:\n\n```\npip install --upgrade --pre hypex\n```\n\nPrefer the old version? You can still use it, but it won't receive updates:\n\n```\npip install hypex==0.1.10\n```\n\n🔗 Learn more: [Telegram Chat](t.me/hypexchat)\n\n## Introduction\n\nHypEx (Hypotheses and Experiments) is a comprehensive library crafted to streamline the causal inference and AB testing\nprocesses in data analytics. Developed for efficiency and effectiveness, HypEx employs Rubin's Causal Model (RCM) for\nmatching closely related pairs, ensuring equitable group comparisons when estimating treatment effects.\n\nBoasting a fully automated pipeline, HypEx adeptly calculates the Average Treatment Effect (ATE), Average Treatment\nEffect on the Treated (ATT), and Average Treatment Effect on the Control (ATC). It offers a standardized interface for\nexecuting these estimations, providing insights into the impact of interventions across various population subgroups.\n\nBeyond causal inference, HypEx is equipped with robust AB testing tools, including Difference-in-Differences (\nDiff-in-Diff) and CUPED methods, to rigorously test hypotheses and validate experimental results.\n\n## Features\n\n- **Faiss KNN Matching**: Utilizes Faiss for efficient and precise nearest neighbor searches, aligning with RCM for\n  optimal pair matching.\n- **Data Filters**: Built-in outlier and Spearman filters ensure data quality for matching.\n- **Result Validation**: Offers multiple validation methods, including random treatment, feature, and subset\n  validations.\n- **Data Tests**: Incorporates SMD, KS, PSI, and Repeats tests to affirm the robustness of effect estimations.\n- **Feature Selection**: Employs LGBM and Catboost feature selection to pinpoint the most impactful features for causal\n  analysis.\n- **AB Testing Suite**: Features a suite of AB testing tools for comprehensive hypothesis evaluation.\n- **Stratification support**: Stratify groups for nuanced analysis\n- **Weights support**:  Empower your analysis by assigning custom weights to features, enhancing the matching precision\n  to suit your specific research needs\n\n## Warnings\n\nSome functions in HypEx can facilitate solving specific auxiliary tasks but cannot automate decisions on experiment\ndesign. Below, we will discuss features that are implemented in HypEx but do not automate the design of experiments.\n\n**Note:** For Matching, it's recommended not to use more than 7 features as it might result in the curse of\ndimensionality, making the results unrepresentative.\n\n### Feature Selection\n\n**Feature selection** models the significance of features for the accuracy of target approximation. However, it does not\nrule out the possibility of overlooked features, the complex impact of features on target description, or the\nsignificance of features from a business logic perspective. The algorithm will not function correctly if there are data\nleaks.\n\nPoints to consider when selecting features:\n\n* Data leaks - these should not be present.\n* Influence on treatment distribution - features should not affect the treatment distribution.\n* The target should be describable by features.\n* All features significantly affecting the target should be included.\n* The business rationale of features.\n* The feature selection function can be useful for addressing these tasks, but it does not solve them nor does it\n  absolve the user of the responsibility for their selection, nor does it justify it.\n\n[Link to ReadTheDocs](https://hypex.readthedocs.io/en/latest/pages/modules/selectors.html#selector-classes)\n\n### Random Treatment\n\n**Random Treatment** algorithm randomly shuffles the actual treatment. It is expected that the treatment's effect on the\ntarget will be close to 0.\n\nThese method is not sufficiently accurate marker of a successful experiment.\n\n[Link to ReadTheDocs](https://hypex.readthedocs.io/en/latest/pages/modules/utils.html#validators)\n\n## Installation\n\n```bash\npip install -U hypex\n```\n\n## Quick start\n\nExplore usage examples and tutorials [here](https://github.com/sb-ai-lab/Hypex/blob/master/examples/tutorials/).\n\n### Matching example\n\n```python\nfrom hypex.dataset import Dataset, InfoRole, TreatmentRole, TargetRole, DefaultRole, FeatureRole\nfrom hypex import Matching\n\ndata = Dataset(\n    roles={\n        \"user_id\": InfoRole(int),  # InfoRole for ID\n        \"treat\": TreatmentRole(int),  # TreatmentRole is for identify user group (control or target)\n        \"post_spends\": TargetRole(float)  # TargetRole for Target :)\n    },\n    data=\"data.csv\",\n    default_role=FeatureRole(),  # All remaining columns will be of type FeatureRole (searching for similar ones)\n)\n\ntest = Matching()  # Classic Matching (maha distance + full metrics)\ntest = Matching(metric=\"att\")  # Calc only ATT\ntest = Matching(distance=\"l2\")  # Choose distance here\n\nresult = test.execute(data)\nresult.resume  # Resume of results \nresult.full_data  # old df_matched. Wide df with pairs\nresult.indexes  # Only indexed pairs (good for join)\n\n```  \nMore about Matching [here](https://github.com/sb-ai-lab/HypEx/tree/master/examples/tutorials/MatchingTutorial.ipynb)\n\n### AA-test example\n\n```python\nfrom hypex.dataset import Dataset, InfoRole, TreatmentRole, TargetRole, StratificationRole\nfrom hypex import AATest\n\ndata = Dataset(\n    roles={\n        \"user_id\": InfoRole(int),  # InfoRole for ID.\n        \"pre_spends\": TargetRole(),  # TargetRole for check homogeneity\n        \"post_spends\": TargetRole(),  # TargetRole for check homogeneity\n        \"gender\": StratificationRole(str)  # StratificationRole for strata\n    }, data=\"data.csv\",\n)\n\naa = AATest(n_iterations=10)\nres = aa.execute(data)\n\nres.resume  # Resume for all test\nres.aa_score  # AA score \nres.best_split  # The best homogeneity split\nres.best_split_statistic  # Statistics for best split \n```\nMore about AA test [here](https://github.com/sb-ai-lab/HypEx/tree/master/examples/tutorials/AATestTutorial.ipynb)\n\n### AB-test example\n\n```python\nfrom hypex.dataset import Dataset, InfoRole, TreatmentRole, TargetRole\nfrom hypex import ABTest\n\ndata = Dataset(\n    roles={\n        \"user_id\": InfoRole(int),  # InfoRole use for ID\n        \"treat\": TreatmentRole(),  # TreatmentRole is for identify user group (control or target)\n        \"pre_spends\": TargetRole(),  # Target for A/B(n) Tests\n        \"post_spends\": TargetRole(),  # Target for A/B(n) Tests\n    }, data=\"data.csv\",\n)\n\ntest = ABTest()  # Classic A/B test\ntest = ABTest(multitest_method=\"bonferroni\")  # A/Bn test with Bonferroni corrections\ntest = ABTest(additional_tests=['t-test', 'u-test', 'chi2-test'])  # Use can choose tests\n\nresult = test.execute(data)\nresult.resume  # Resume of results\n```\nMore about A/B test [here](https://github.com/sb-ai-lab/HypEx/tree/master/examples/tutorials/ABTestTutorial.ipynb)\n\n## Documentation\n\nFor more detailed information about the library and its features, visit\nour [documentation on ReadTheDocs](https://hypex.readthedocs.io/en/latest/).\n\nYou'll find comprehensive guides and tutorials that will help you get started with HypEx, as well as detailed API\ndocumentation for advanced use cases.\n\n## Contributions\n\nJoin our vibrant community! For guidelines on contributing, reporting issues, or seeking support, please refer to\nour [Contributing Guidelines](https://github.com/sb-ai-lab/Hypex/blob/master/.github/CONTRIBUTING.md).\n\n## More Information \u0026 Resources\n\n[Habr (ru)](https://habr.com/ru/companies/sberbank/articles/778774/) - discover how HypEx is revolutionizing causal\ninference in various fields.      \n[A/B testing seminar](https://www.youtube.com/watch?v=B9BE_yk8CjA\u0026t=53s\u0026ab_channel=NoML) - Seminar in NoML about\nmatching and A/B testing       \n[Matching with HypEx: Simple Guide](https://www.kaggle.com/code/kseniavasilieva/matching-with-hypex-simple-guide) -\nSimple matching guide with explanation           \n[Matching with HypEx: Grouping](https://www.kaggle.com/code/kseniavasilieva/matching-with-hypex-grouping) - Matching\nwith grouping guide    \n[HypEx vs Causal Inference and DoWhy](https://www.kaggle.com/code/kseniavasilieva/hypex-vs-causal-inference-and-dowhy) -\ndiscover why HypEx is the best solution for causal inference           \n[HypEx vs Causal Inference and DoWhy: part 2](https://www.kaggle.com/code/kseniavasilieva/hypex-vs-causal-inference-part-2) -\ndiscover why HypEx is the best solution for causal inference\n\n### Testing different libraries for the speed of matching\n\nVisit [this](https://www.kaggle.com/code/kseniavasilieva/hypex-vs-causal-inference-part-2) notebook ain Kaggle and\nestimate results by yourself.\n\n| Group size             | 32 768 | 65 536 | 131 072 | 262 144 | 524 288 | 1 048 576 | 2 097 152 | 4 194 304 |\n|------------------------|--------|--------|---------|---------|---------|-----------|-----------|-----------|\n| Causal Inference       | 46s    | 169s   | None    | None    | None    | None      | None      | None      |\n| DoWhy                  | 9s     | 19s    | 40s     | 77s     | 159s    | 312s      | 615s      | 1 235s    |\n| HypEx with grouping    | 2s     | 6s     | 16s     | 42s     | 167s    | 509s      | 1 932s    | 7 248s    |\n| HypEx without grouping | 2s     | 7s     | 21s     | 101s    | 273s    | 982s      | 3 750s    | 14 720s   |\n\n## Join Our Community\n\nHave questions or want to discuss HypEx? Join our [Telegram chat](https://t.me/HypExChat) and connect with the community\nand the developers.\n\n## Conclusion\n\nHypEx stands as an indispensable resource for data analysts and researchers delving into causal inference and AB\ntesting. With its automated capabilities, sophisticated matching techniques, and thorough validation procedures, HypEx\nis poised to unravel causal relationships in complex datasets with unprecedented speed and precision.\n\n##                                                                                \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsb-ai-lab%2Fhypex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsb-ai-lab%2Fhypex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsb-ai-lab%2Fhypex/lists"}