{"id":13869888,"url":"https://github.com/lupalab/ace","last_synced_at":"2025-07-15T18:32:22.234Z","repository":{"id":48293310,"uuid":"337157794","full_name":"lupalab/ace","owner":"lupalab","description":"Official code for the paper \"Arbitrary Conditional Distributions with Energy\".","archived":false,"fork":false,"pushed_at":"2023-07-07T16:32:01.000Z","size":80,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-06T21:21:57.458Z","etag":null,"topics":["arbitrary-conditioning","density-estimation","energy-based-model"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2102.04426","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/lupalab.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-08T17:39:45.000Z","updated_at":"2024-07-19T08:47:31.000Z","dependencies_parsed_at":"2024-01-16T07:23:39.073Z","dependency_job_id":"cfdc01e6-979a-4e80-84d4-92ea13e4155a","html_url":"https://github.com/lupalab/ace","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupalab%2Face","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupalab%2Face/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupalab%2Face/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupalab%2Face/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lupalab","download_url":"https://codeload.github.com/lupalab/ace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226062969,"owners_count":17567930,"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":["arbitrary-conditioning","density-estimation","energy-based-model"],"created_at":"2024-08-05T20:01:20.882Z","updated_at":"2024-11-23T15:32:12.101Z","avatar_url":"https://github.com/lupalab.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"[1]: https://arxiv.org/abs/2102.04426\n\n# Arbitrary Conditioning with Energy\n\nThis is the official repository for the paper [\"Arbitrary Conditional Distributions\nwith Energy\"][1].\n\nArbitrary Conditioning with Energy (ACE) is a method that can simultaneously estimate\nthe distribution `p(x_u | x_o)` for all possible subsets of features `x_u` and `x_o`. \nACE achieves state-of-the-art for arbitrary conditional and marginal likelihood\nestimation and for tabular data imputation.\n\nIn this repository, we provide a simple and accessible implementation of the most\nstraightforward version of ACE. The model is implemented in TensorFlow as a\n`tf.keras.Model` in order to facilitate easy custom use.\n\n## Installation\n\nThe `ace` package can be installed by cloning this repository then running\n```\npip install .\n```\nin the directory of this README file. This should ensure all necessary dependencies\nare installed.\n\n### UCI Datasets\n\nThe UCI datasets that are used in the paper can be installed as \n[TensorFlow Datasets](https://www.tensorflow.org/datasets). To install one of the\ndatasets, navigate to that dataset's directory (e.g. [`datasets/gas`](datasets/gas)),\nthe run:\n```\ntfds build\n```\nThis will download and prepare the dataset so that it can be accessed via\nTensorFlow Datasets when the training script is run.\n\n## Usage\n\n### Training\n\nModels can be trained using the command-line interface accessed with:\n```\npython -m ace.train --help\n```\nWe use [Gin](https://github.com/google/gin-config) to configure model and training\nsettings. Example configuration files are provided in [`configs/`](configs). For\nexample, you can train a model on the Gas dataset with:\n```\npython -m ace.train --config config/gas.gin --logdir logs/gas\n```\nModel weights and TensorBoard summaries will be saved within the directory specified by\nthe `--logdir` option.\n\n### Evaluation\n\nAn interface for simple evaluations of models on test data is accessed with:\n```\npython -m ace.test --help\n```\n\nFor example, you could evaluate a model's imputation performance with:\n```\npython -m ace.test --model_dir path/to/model/dir/ --run imputation --num_importance_samples 20000\n```\nThe path provided to the `--model_dir` option should be the directory that was created\nby the training script to house the model.\n\nEvaluation results will be saved within an `evaluations/` directory inside the model's\ndirectory. The pertinent metrics will be in files called `results.json`.\n\n### Custom Use\n\nUsing an ACE model in your own code can be easily accomplished as follows:\n```python\nfrom ace import ACEModel\n\n# When creating an ACE model, the dimensionality of the data must be provided (e.g., 8)\nmodel = ACEModel(num_features=8)\n```\n\nThis class implements the standard version of ACE that is for use with continuous data.\nHowever, it can be adapted to work with discrete data with some small modification, as\ndescribed in the paper.\n\nThe model is called with `x` (the data) and `b` (the binary mask indicating which\nfeatures are observed) as mandatory inputs. A `missing_mask` can optionally be provided\nto indicate which features are missing (i.e., will be neither observed nor unobserved).\nAn `ACEOutputs` object will be returned, which contains various outputs of the model.\n\n```python\n# Use your real data here in practice.\nx = np.random.normal(size=(32, 8))\nb = np.random.choice(2, size=(32, 8))\n\noutputs = model(\n    [x, b],\n    missing_mask=None,\n    num_importance_samples=10,\n    training=False,\n)\n```\n\nThe class also provides methods for computing autoregressive likelihoods, sampling, and\nimputing.\n\n```python\nenergy_log_probs, proposal_log_probs = model.log_prob(x, b)\nsamples = model.sample(x, b)\nenergy_imputations, proposal_imputations = model.impute(x, b)\n```\n\nThe model can be trained with `model.fit()` (see [`train.py`](ace/train.py) for an\nexample).\n\nIn order to train with data that has missing values, the `tf.data.Dataset` that is\nprovided to the `fit` method should have three tensors instead of just two (the third\nbeing the binary mask to indicate which values are missing).\n\n## Citation\n\n```\n@misc{strauss2021arbitrary,\n      title={Arbitrary Conditional Distributions with Energy}, \n      author={Ryan R. Strauss and Junier B. Oliva},\n      year={2021},\n      eprint={2102.04426},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flupalab%2Face","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flupalab%2Face","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flupalab%2Face/lists"}