{"id":23325015,"url":"https://github.com/birkhoffg/jax-relax","last_synced_at":"2025-09-10T08:32:09.741Z","repository":{"id":183316362,"uuid":"669925796","full_name":"BirkhoffG/jax-relax","owner":"BirkhoffG","description":"Recourse Explanation Library in JAX","archived":false,"fork":false,"pushed_at":"2024-05-28T23:30:24.000Z","size":17736,"stargazers_count":6,"open_issues_count":7,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-05-29T12:33:39.399Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://birkhoffg.github.io/jax-relax/","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/BirkhoffG.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-23T21:56:11.000Z","updated_at":"2024-08-13T21:45:54.306Z","dependencies_parsed_at":null,"dependency_job_id":"5ec26ccb-400a-4a40-bda5-c96319259297","html_url":"https://github.com/BirkhoffG/jax-relax","commit_stats":null,"previous_names":["birkhoffg/relax-core"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BirkhoffG%2Fjax-relax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BirkhoffG%2Fjax-relax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BirkhoffG%2Fjax-relax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BirkhoffG%2Fjax-relax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BirkhoffG","download_url":"https://codeload.github.com/BirkhoffG/jax-relax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232374881,"owners_count":18513593,"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-12-20T18:29:10.533Z","updated_at":"2025-01-04T20:38:02.390Z","avatar_url":"https://github.com/BirkhoffG.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReLax\n\n\n\u003c!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! --\u003e\n\n![Python](https://img.shields.io/pypi/pyversions/jax-relax.svg) ![CI\nstatus](https://github.com/BirkhoffG/jax-relax/actions/workflows/test.yaml/badge.svg)\n![Docs](https://github.com/BirkhoffG/jax-relax/actions/workflows/deploy.yaml/badge.svg)\n![pypi](https://img.shields.io/pypi/v/jax-relax.svg) ![GitHub\nLicense](https://img.shields.io/github/license/BirkhoffG/jax-relax.svg)\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.06567/status.svg)](https://doi.org/10.21105/joss.06567)\n\n[**Overview**](#overview) \\| [**Installation**](#installation) \\|\n[**Tutorials**](https://birkhoffg.github.io/jax-relax/tutorials/getting_started.html)\n\\| [**Documentation**](https://birkhoffg.github.io/jax-relax/) \\|\n[**Citing ReLax**](#citing-relax)\n\n## Overview\n\n`ReLax` (**Re**course Explanation **L**ibrary in J**ax**) is an\nefficient and scalable benchmarking library for recourse and\ncounterfactual explanations, built on top of\n[jax](https://jax.readthedocs.io/en/latest/). By leveraging language\nprimitives such as *vectorization*, *parallelization*, and\n*just-in-time* compilation in\n[jax](https://jax.readthedocs.io/en/latest/), `ReLax` offers massive\nspeed improvements in generating individual (or local) explanations for\npredictions made by Machine Learning algorithms.\n\nSome of the key features are as follows:\n\n- 🏃 **Fast and scalable** recourse generation.\n\n- 🚀 **Accelerated** over `cpu`, `gpu`, `tpu`.\n\n- 🪓 **Comprehensive** set of recourse methods implemented for\n  benchmarking.\n\n- 👐 **Customizable** API to enable the building of entire modeling and\n  interpretation pipelines for new recourse algorithms.\n\n## Installation\n\n``` bash\npip install jax-relax\n# Or install the latest version of `jax-relax`\npip install git+https://github.com/BirkhoffG/jax-relax.git \n```\n\nTo futher unleash the power of accelerators (i.e., GPU/TPU), we suggest\nto first install this library via `pip install jax-relax`. Then, follow\nsteps in the [official install\nguidelines](https://github.com/google/jax#installation) to install the\nright version for GPU or TPU.\n\n## Dive into `ReLax`\n\n`ReLax` is a recourse explanation library for explaining (any) JAX-based\nML models. We believe that it is important to give users flexibility to\nchoose how to use `ReLax`. You can\n\n- only use methods implemeted in `ReLax` (as a recourse methods\n  library);\n- build a pipeline using `ReLax` to define data module, training ML\n  models, and generating CF explanation (for constructing recourse\n  benchmarking pipeline).\n\n### `ReLax` as a Recourse Explanation Library\n\nWe introduce basic use cases of using methods in `ReLax` to generate\nrecourse explanations. For more advanced usages of methods in `ReLax`,\nSee this [tutorials](tutorials/methods.ipynb).\n\n``` python\nfrom relax.methods import VanillaCF\nfrom relax import DataModule, MLModule, generate_cf_explanations, benchmark_cfs\nfrom sklearn.datasets import make_classification\nfrom sklearn.model_selection import train_test_split\nimport functools as ft\nimport jax\n```\n\nLet’s first generate synthetic data:\n\n``` python\nxs, ys = make_classification(n_samples=1000, n_features=10, random_state=42)\ntrain_xs, test_xs, train_ys, test_ys = train_test_split(xs, ys, random_state=42)\n```\n\nNext, we fit an MLP model for this data. Note that this model can be any\nmodel implmented in JAX. We will use the\n[`MLModule`](https://birkhoffg.github.io/jax-relax/ml_model.html#mlmodule)\nin `ReLax` as an example.\n\n``` python\nmodel = MLModule()\nmodel.train((train_xs, train_ys), epochs=10, batch_size=64)\n```\n\nGenerating recourse explanations are straightforward. We can simply call\n`generate_cf` of an implemented recourse method to generate *one*\nrecourse explanation:\n\n``` python\nvcf = VanillaCF(config={'n_steps': 1000, 'lr': 0.05})\ncf = vcf.generate_cf(test_xs[0], model.pred_fn)\nassert cf.shape == test_xs[0].shape\n```\n\nOr generate a bunch of recourse explanations with `jax.vmap`:\n\n``` python\ngenerate_fn = ft.partial(vcf.generate_cf, pred_fn=model.pred_fn)\ncfs = jax.vmap(generate_fn)(test_xs)\nassert cfs.shape == test_xs.shape\n```\n\n### `ReLax` for Building Recourse Explanation Pipelines\n\nThe above example illustrates the usage of the decoupled `relax.methods`\nto generate recourse explanations. However, users are required to write\nboilerplate code for tasks such as data preprocessing, model training,\nand generating recourse explanations with feature constraints.\n\n`ReLax` additionally offers a one-liner framework, streamlining the\nprocess and helping users in building a standardized pipeline for\ngenerating recourse explanations. You can write three lines of code to\nbenchmark recourse explanations:\n\n``` python\ndata_module = DataModule.from_numpy(xs, ys)\nexps = generate_cf_explanations(vcf, data_module, model.pred_fn)\nbenchmark_cfs([exps])\n```\n\nSee [Getting Started with\nReLax](https://birkhoffg.github.io/jax-relax/tutorials/getting_started.html)\nfor an end-to-end example of using `ReLax`.\n\n## Supported Recourse Methods\n\n`ReLax` currently provides implementations of 9 recourse explanation\nmethods.\n\n| Method                                                                                     | Type            | Paper Title                                                                                    | Ref                                       |\n|--------------------------------------------------------------------------------------------|-----------------|------------------------------------------------------------------------------------------------|-------------------------------------------|\n| [`VanillaCF`](https://birkhoffg.github.io/jax-relax/methods/vanilla.html#vanillacf)        | Non-Parametric  | Counterfactual Explanations without Opening the Black Box: Automated Decisions and the GDPR.   | [\\[1\\]](https://arxiv.org/abs/1711.00399) |\n| [`DiverseCF`](https://birkhoffg.github.io/jax-relax/methods/dice.html#diversecf)           | Non-Parametric  | Explaining Machine Learning Classifiers through Diverse Counterfactual Explanations.           | [\\[2\\]](https://arxiv.org/abs/1905.07697) |\n| [`ProtoCF`](https://birkhoffg.github.io/jax-relax/methods/proto.html#protocf)              | Semi-Parametric | Interpretable Counterfactual Explanations Guided by Prototypes.                                | [\\[3\\]](https://arxiv.org/abs/1907.02584) |\n| [`CounterNet`](https://birkhoffg.github.io/jax-relax/methods/counternet.html#counternet)   | Parametric      | CounterNet: End-to-End Training of Prediction Aware Counterfactual Explanations.               | [\\[4\\]](https://arxiv.org/abs/2109.07557) |\n| [`GrowingSphere`](https://birkhoffg.github.io/jax-relax/methods/sphere.html#growingsphere) | Non-Parametric  | Inverse Classification for Comparison-based Interpretability in Machine Learning.              | [\\[5\\]](https://arxiv.org/abs/1712.08443) |\n| [`CCHVAE`](https://birkhoffg.github.io/jax-relax/methods/cchvae.html#cchvae)               | Semi-Parametric | Learning Model-Agnostic Counterfactual Explanations for Tabular Data.                          | [\\[6\\]](https://arxiv.org/abs/1910.09398) |\n| [`VAECF`](https://birkhoffg.github.io/jax-relax/methods/vaecf.html#vaecf)                  | Parametric      | Preserving Causal Constraints in Counterfactual Explanations for Machine Learning Classifiers. | [\\[7\\]](https://arxiv.org/abs/1912.03277) |\n| [`CLUE`](https://birkhoffg.github.io/jax-relax/methods/clue.html#clue)                     | Semi-Parametric | Getting a CLUE: A Method for Explaining Uncertainty Estimates.                                 | [\\[8\\]](https://arxiv.org/abs/2006.06848) |\n| [`L2C`](https://birkhoffg.github.io/jax-relax/methods/l2c.html#l2c)                        | Parametric      | Feature-based Learning for Diverse and Privacy-Preserving Counterfactual Explanations          | [\\[9\\]](https://arxiv.org/abs/2209.13446) |\n\n## Citing `ReLax`\n\nTo cite this repository:\n\n``` latex\n@software{relax2023github,\n  author = {Hangzhi Guo and Xinchang Xiong and Amulya Yadav},\n  title = {{R}e{L}ax: Recourse Explanation Library in Jax},\n  url = {http://github.com/birkhoffg/jax-relax},\n  version = {0.2.0},\n  year = {2023},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbirkhoffg%2Fjax-relax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbirkhoffg%2Fjax-relax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbirkhoffg%2Fjax-relax/lists"}