# Engression
Engression is a neural network-based distributional regression method proposed in the paper "[*Engression: Extrapolation through the Lens of Distributional Regression?*](https://arxiv.org/abs/2307.00835)" by Xinwei Shen and Nicolai Meinshausen (2023). This repository contains the software implementations of engression in both R and Python.
Consider targets $Y\in\mathbb{R}^k$ and predictors $X\in\mathbb{R}^d$; both variables can be univariate or multivariate, continuous or discrete. Engression can be used to
* estimate the conditional mean $\mathbb{E}[Y|X=x]$ (as in least-squares regression),
* estimate the conditional quantiles of $Y$ given $X=x$ (as in quantile regression), and
* sample from the fitted conditional distribution of $Y$ given $X=x$ (as a generative model).
The results in the paper show the advantages of engression over existing regression approaches in terms of extrapolation.
## Installation
The latest release of the Python package can be installed through pip:
```sh
pip install engression
```
The development version can be installed from github:
```sh
pip install -e "git+https://github.com/xwshen51/engression#egg=engression&subdirectory=engression-python"
```
## Usage Example
### Python
Below is one simple demonstration. See [this tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_simu.ipynb) for more details on simulated data and [this tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_air.ipynb) for a real data example. We demonstrate in [another tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_bag.ipynb) how to fit a bagged engression model, which also helps with hyperparameter tuning.
```python
from engression import engression
from engression.data.simulator import preanm_simulator
## Simulate data
x, y = preanm_simulator("square", n=10000, x_lower=0, x_upper=2, noise_std=1, train=True, device=device)
x_eval, y_eval_med, y_eval_mean = preanm_simulator("square", n=1000, x_lower=0, x_upper=4, noise_std=1, train=False, device=device)
## Fit an engression model
engressor = engression(x, y, lr=0.01, num_epoches=500, batch_size=1000, device="cuda")
## Summarize model information
engressor.summary()
## Evaluation
print("L2 loss:", engressor.eval_loss(x_eval, y_eval_mean, loss_type="l2"))
print("correlation between predicted and true means:", engressor.eval_loss(x_eval, y_eval_mean, loss_type="cor"))
## Predictions
y_pred_mean = engressor.predict(x_eval, target="mean") ## for the conditional mean
y_pred_med = engressor.predict(x_eval, target="median") ## for the conditional median
y_pred_quant = engressor.predict(x_eval, target=[0.025, 0.5, 0.975]) ## for the conditional 2.5% and 97.5% quantiles
```
## Contact information
If you meet any problems with the code, please submit an issue or contact [Xinwei Shen](mailto:xinwei.shen@stat.math.ethz.ch).
Raw data
{
"_id": null,
"home_page": "https://github.com/xwshen51/engression",
"name": "engression",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Xinwei Shen and Nicolai Meinshausen",
"author_email": "xinwei.shen@stat.math.ethz.ch",
"download_url": "https://files.pythonhosted.org/packages/b0/ec/6921c34b3fb976e11e7b119dd7ed7fcfab5fa478981682ba7c0ec35e42b2/engression-0.1.11.tar.gz",
"platform": null,
"description": "# Engression\n\nEngression is a neural network-based distributional regression method proposed in the paper \"[*Engression: Extrapolation through the Lens of Distributional Regression?*](https://arxiv.org/abs/2307.00835)\" by Xinwei Shen and Nicolai Meinshausen (2023). This repository contains the software implementations of engression in both R and Python. \n\nConsider targets $Y\\in\\mathbb{R}^k$ and predictors $X\\in\\mathbb{R}^d$; both variables can be univariate or multivariate, continuous or discrete. Engression can be used to \n* estimate the conditional mean $\\mathbb{E}[Y|X=x]$ (as in least-squares regression), \n* estimate the conditional quantiles of $Y$ given $X=x$ (as in quantile regression), and \n* sample from the fitted conditional distribution of $Y$ given $X=x$ (as a generative model).\n\nThe results in the paper show the advantages of engression over existing regression approaches in terms of extrapolation. \n\n\n## Installation\nThe latest release of the Python package can be installed through pip:\n```sh\npip install engression\n```\n\nThe development version can be installed from github:\n\n```sh\npip install -e \"git+https://github.com/xwshen51/engression#egg=engression&subdirectory=engression-python\" \n```\n\n\n## Usage Example\n\n### Python\n\nBelow is one simple demonstration. See [this tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_simu.ipynb) for more details on simulated data and [this tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_air.ipynb) for a real data example. We demonstrate in [another tutorial](https://github.com/xwshen51/engression/blob/main/engression-python/examples/example_bag.ipynb) how to fit a bagged engression model, which also helps with hyperparameter tuning.\n```python\nfrom engression import engression\nfrom engression.data.simulator import preanm_simulator\n\n## Simulate data\nx, y = preanm_simulator(\"square\", n=10000, x_lower=0, x_upper=2, noise_std=1, train=True, device=device)\nx_eval, y_eval_med, y_eval_mean = preanm_simulator(\"square\", n=1000, x_lower=0, x_upper=4, noise_std=1, train=False, device=device)\n\n## Fit an engression model\nengressor = engression(x, y, lr=0.01, num_epoches=500, batch_size=1000, device=\"cuda\")\n## Summarize model information\nengressor.summary()\n\n## Evaluation\nprint(\"L2 loss:\", engressor.eval_loss(x_eval, y_eval_mean, loss_type=\"l2\"))\nprint(\"correlation between predicted and true means:\", engressor.eval_loss(x_eval, y_eval_mean, loss_type=\"cor\"))\n\n## Predictions\ny_pred_mean = engressor.predict(x_eval, target=\"mean\") ## for the conditional mean\ny_pred_med = engressor.predict(x_eval, target=\"median\") ## for the conditional median\ny_pred_quant = engressor.predict(x_eval, target=[0.025, 0.5, 0.975]) ## for the conditional 2.5% and 97.5% quantiles\n```\n\n\n## Contact information\nIf you meet any problems with the code, please submit an issue or contact [Xinwei Shen](mailto:xinwei.shen@stat.math.ethz.ch).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Engression Modelling",
"version": "0.1.11",
"project_urls": {
"Homepage": "https://github.com/xwshen51/engression"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27911b078efee5277eb347d504b7f48d103ea60303ea65de299f686d4152a1ae",
"md5": "1e80e2c7b67c1c893e5fca687c8f10b0",
"sha256": "9451059d6bbb10b53788dfc983f65c855abb35f5ca46c53a2d570253e97c464a"
},
"downloads": -1,
"filename": "engression-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e80e2c7b67c1c893e5fca687c8f10b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20533,
"upload_time": "2024-09-08T07:17:05",
"upload_time_iso_8601": "2024-09-08T07:17:05.490077Z",
"url": "https://files.pythonhosted.org/packages/27/91/1b078efee5277eb347d504b7f48d103ea60303ea65de299f686d4152a1ae/engression-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b0ec6921c34b3fb976e11e7b119dd7ed7fcfab5fa478981682ba7c0ec35e42b2",
"md5": "d24f64ccd10537a3b658ac68ee507670",
"sha256": "a35b745aaf631b1ed730fadf8b41b1da33c05e6c46c2bae124cb66fb516aa746"
},
"downloads": -1,
"filename": "engression-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "d24f64ccd10537a3b658ac68ee507670",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17272,
"upload_time": "2024-09-08T07:17:07",
"upload_time_iso_8601": "2024-09-08T07:17:07.131066Z",
"url": "https://files.pythonhosted.org/packages/b0/ec/6921c34b3fb976e11e7b119dd7ed7fcfab5fa478981682ba7c0ec35e42b2/engression-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-08 07:17:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xwshen51",
"github_project": "engression",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "engression"
}
JSON
