{"id":33248793,"url":"https://github.com/charmlab/mace","last_synced_at":"2025-11-21T16:01:40.038Z","repository":{"id":40983100,"uuid":"192914582","full_name":"charmlab/mace","owner":"charmlab","description":"Model Agnostic Counterfactual Explanations","archived":false,"fork":false,"pushed_at":"2022-09-30T18:53:58.000Z","size":3145,"stargazers_count":87,"open_issues_count":8,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-17T19:44:12.161Z","etag":null,"topics":["counterfactual-explanations","explainable-ai","explainable-ml","interpretable-machine-learning","machine-learning","xai"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charmlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-20T12:17:26.000Z","updated_at":"2024-10-14T10:22:45.000Z","dependencies_parsed_at":"2022-09-18T14:13:46.175Z","dependency_job_id":null,"html_url":"https://github.com/charmlab/mace","commit_stats":null,"previous_names":["charmlab/mace","amirhk/mace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/charmlab/mace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmlab%2Fmace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmlab%2Fmace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmlab%2Fmace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmlab%2Fmace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charmlab","download_url":"https://codeload.github.com/charmlab/mace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmlab%2Fmace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285645303,"owners_count":27207370,"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","status":"online","status_checked_at":"2025-11-21T02:00:06.175Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["counterfactual-explanations","explainable-ai","explainable-ml","interpretable-machine-learning","machine-learning","xai"],"created_at":"2025-11-16T22:00:40.599Z","updated_at":"2025-11-21T16:01:40.026Z","avatar_url":"https://github.com/charmlab.png","language":"Python","funding_links":[],"categories":["Github Repos"],"sub_categories":[],"readme":"# General\n\nThis repository provides code and examples for generating nearest counterfactual explanations and minimal consequential interventions. The following papers are supported:\n\n- [2017.06 Feature Tweaking](https://arxiv.org/abs/1706.06691) (4c691b4 @ https://github.com/upura/featureTweakPy)\n- [2019.01 Actionable Recourse](https://arxiv.org/pdf/1809.06514) (9387e6c @ https://github.com/ustunb/actionable-recourse)\n- [2019.07 Minimum  Observable](https://arxiv.org/abs/1907.04135)\n- [2019.05 MACE](https://arxiv.org/abs/1905.11190)\n- [2020.02 MINT](https://arxiv.org/abs/2002.06278)\n\n\n\n# Code Pre-requisites\n\nFirst,\n```console\n$ git clone https://github.com/amirhk/mace.git\n$ pip install virtualenv\n$ cd mace\n$ virtualenv -p python3 _venv\n$ source _venv/bin/activate\n$ pip install -r pip_requirements.txt\n$ pysmt-install --z3 --confirm-agreement\n```\n\n\nThen refer to\n```console\n$ python batchTest.py  --help\n```\n\nand run as follows\n```console\n$ python batchTest.py -d *dataset* -m *model* -n *norm* -a *approach* -b 0 -s *numSamples*\n```\n\nFor instance, you may run\n```console\n$ python batchTest.py -d adult -m lr -n zero_norm -a AR -b 0 -s 1\n$ python batchTest.py -d credit -m mlp -n one_norm -a MACE_eps_1e-3 -b 0 -s 1\n$ python batchTest.py -d german -m tree -n two_norm -a MINT__eps_1e-3 -b 0 -s 1\n$ python batchTest.py -d mortgage -m forest -n infty_norm -a MINT__eps_1e-3 -b 0 -s 1\n```\n\nFinally, view the results under the _experiments folder.\n\n\n\n# Specific considerations for _minimal interventions_\n\nFor mortgage data, where a causal structure governs the world, AND all variables\nare actionable and mutable, we should expect to see `int_dist \u003c= ? \u003e= cfe_dist`,\nbut `cfe_dist \u003c= scf_dist`. You can assert this by running the following:\n\n```console\n$ python batchTest.py -d mortgage -m lr -n one_norm -a MINT_eps_1e-5 MACE_eps_1e-5 -b 0 -s 10\n```\n\nThen you can compare the distances resulting fron MACE and MINT as outputted in the console. Do make sure to run `batchTest.py` with `loadData.loadDataset(load_from_cache = True)` so that MACE and MINT use the same data and the resulting comparison is fair.\n\n\n\n# Using git-hooks script for sanity checking\n\nThere is a `pre-push` script under `_hooks/` which can be used to check MACE under different setups.\nSpecifically, it checks for successfully running of the code and the closeness of the generated CFEs\nto the previously-saved (approximately) optimal ones. You can either manually call the script from MACE root directory by\n`_hooks/pre-push` or place it under your local `.git/hooks/` directory to run automatically before every push.\nIn this case, please remember to give it the required permissions:\n\n```console\n$ chmod +x .git/hooks/pre-push\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmlab%2Fmace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharmlab%2Fmace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmlab%2Fmace/lists"}