# PyPARC - A Python Package for Piecewise Affine Regression and Classification
# Contents
* [Package description](#description)
* [Installation](#install)
* [Basic usage](#basic-usage)
* [Contributors](#contributors)
* [Citing PARC](#bibliography)
* [License](#license)
<a name="description"></a>
## Package description
**PyPARC** is a package for solving multivariate regression and classification problems using piecewise linear (affine) predictors over a polyhedral partition of the feature space. The underlying algorithm is called PARC (Piecewise Affine Regression and Classification) and is described in the following paper:
<a name="cite-Bem23"><a>
> [1] A. Bemporad, "[A piecewise linear regression and classification algorithm with application to learning and model predictive control of hybrid systems](http://cse.lab.imtlucca.it/~bemporad/publications/papers/ieeetac-parc.pdf)," *IEEE Transactions on Automatic Control*, vol. 68, pp. 3194–3209, June 2023. [[bib entry](#ref1)]
The algorithm alternates between:
1. Solving ridge regression problems (for numeric targets) and softmax regression problems (for categorical targets), and either softmax regression or cluster centroid computation for piecewise linear separation
2. Assigning the training points to different clusters on the basis of a criterion that balances prediction accuracy and piecewise-linear separability.
For earlier Python versions of the code, see <a href="http://cse.lab.imtlucca.it/~bemporad/parc/">here</a>.
<a name="install"></a>
## Installation
~~~python
pip install pyparc
~~~
<a name="basic-usage"></a>
## Basic usage
Say we want to fit a piecewise affine model on a dataset of 1000 samples $(x,y)$, where $x=(x_1,x_2)$ has two numeric components randomly generated between 0 and 1, and $y$ is obtained by the following nonlinear function of $x$
$$y(x_1,x_2)=\sin\left(4x_{1}-5\left(x_{2}-\frac{1}{2}\right)^2\right)+2x_2$$
<img src="http://cse.lab.imtlucca.it/~bemporad/parc/fig4.png" alt="drawing" width=55%/>
<img src="http://cse.lab.imtlucca.it/~bemporad/parc/fig1.png" alt="drawing" width=40%/>
We use 80% of the data for training (`X_train`,`Y_train`) and 20% for testing the model (`X_test`,`Y_test`).
We want to train a piecewise affine model on a polyhedral partition with maximum 10 regions, with $\ell_2$-regularization coefficient $\alpha=10^{-4}$ and maximum 15 block-coordinate descent iterations of the algorithm:
~~~python
from parc.parc import PARC
predictor = PARC(K=10, alpha=1.0e-4, maxiter=15) # initialize PARC object
categorical = False # targets are numeric
# fit piecewise linear predictor
predictor.fit(X_train, Y_train)
# make predictions on test data
Yhtest, _ = predictor.predict(X_test)
# compute R2 scores
score_train = predictor.score(X_train, Y_train)
score_test = predictor.score(X_test, Y_test)
~~~
The resulting PWA model leads to the following partition
<img src="http://cse.lab.imtlucca.it/~bemporad/parc/fig3.png" alt="drawing" width=65%/>
and PWA function
<img src="http://cse.lab.imtlucca.it/~bemporad/parc/fig5.png" alt="drawing" width=50%/>
<img src="http://cse.lab.imtlucca.it/~bemporad/parc/fig2.png" alt="drawing" width=40%/>
<a name="contributors"><a>
## Contributors
This package was coded by Alberto Bemporad.
This software is distributed without any warranty. Please cite the above papers if you use this software.
<a name="bibliography"><a>
## Citing PARC
<a name="ref1"></a>
```
@article{Bem23,
author={A. Bemporad},
title={A Piecewise Linear Regression and Classification Algorithm with Application to Learning and Model Predictive Control of Hybrid Systems},
journal={IEEE Transactions on Automatic Control},
year=2023,
month=jun,
volume=68,
number=6,
pages={3194--3209},
}
```
<a name="license"><a>
## License
Apache 2.0
(C) 2021-2023 A. Bemporad
Raw data
{
"_id": null,
"home_page": "",
"name": "pyparc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "piecewise linear regression,piecewise linear classification,multivariate regression,multivariate classification,supervised learning",
"author": "",
"author_email": "Alberto Bemporad <alberto.bemporad@imtlucca.it>",
"download_url": "https://files.pythonhosted.org/packages/d6/43/0b896ea88246776ef61be0cdf51affbfd8eaae440848f1597c1b06064915/pyparc-2.0.4.tar.gz",
"platform": null,
"description": "# PyPARC - A Python Package for Piecewise Affine Regression and Classification\n\n# Contents\n\n* [Package description](#description)\n\n* [Installation](#install)\n\n* [Basic usage](#basic-usage)\n\n* [Contributors](#contributors)\n\n* [Citing PARC](#bibliography)\n\n* [License](#license)\n\n\n<a name=\"description\"></a>\n## Package description \n\n**PyPARC** is a package for solving multivariate regression and classification problems using piecewise linear (affine) predictors over a polyhedral partition of the feature space. The underlying algorithm is called PARC (Piecewise Affine Regression and Classification) and is described in the following paper:\n\n<a name=\"cite-Bem23\"><a>\n> [1] A. Bemporad, \"[A piecewise linear regression and classification algorithm with application to learning and model predictive control of hybrid systems](http://cse.lab.imtlucca.it/~bemporad/publications/papers/ieeetac-parc.pdf),\" *IEEE Transactions on Automatic Control*, vol. 68, pp. 3194\u20133209, June 2023. [[bib entry](#ref1)]\n\nThe algorithm alternates between:\n\n1. Solving ridge regression problems (for numeric targets) and softmax regression problems (for categorical targets), and either softmax regression or cluster centroid computation for piecewise linear separation\n2. Assigning the training points to different clusters on the basis of a criterion that balances prediction accuracy and piecewise-linear separability.\n\nFor earlier Python versions of the code, see <a href=\"http://cse.lab.imtlucca.it/~bemporad/parc/\">here</a>.\n\n<a name=\"install\"></a>\n## Installation\n\n~~~python\npip install pyparc\n~~~\n\n<a name=\"basic-usage\"></a>\n## Basic usage\n\nSay we want to fit a piecewise affine model on a dataset of 1000 samples $(x,y)$, where $x=(x_1,x_2)$ has two numeric components randomly generated between 0 and 1, and $y$ is obtained by the following nonlinear function of $x$ \n\n$$y(x_1,x_2)=\\sin\\left(4x_{1}-5\\left(x_{2}-\\frac{1}{2}\\right)^2\\right)+2x_2$$\n\n<img src=\"http://cse.lab.imtlucca.it/~bemporad/parc/fig4.png\" alt=\"drawing\" width=55%/>\n<img src=\"http://cse.lab.imtlucca.it/~bemporad/parc/fig1.png\" alt=\"drawing\" width=40%/>\n\n\nWe use 80% of the data for training (`X_train`,`Y_train`) and 20% for testing the model (`X_test`,`Y_test`).\n\nWe want to train a piecewise affine model on a polyhedral partition with maximum 10 regions, with $\\ell_2$-regularization coefficient $\\alpha=10^{-4}$ and maximum 15 block-coordinate descent iterations of the algorithm:\n\n~~~python\nfrom parc.parc import PARC\n\npredictor = PARC(K=10, alpha=1.0e-4, maxiter=15) # initialize PARC object\n\ncategorical = False # targets are numeric\n\n# fit piecewise linear predictor\npredictor.fit(X_train, Y_train) \n\n# make predictions on test data\nYhtest, _ = predictor.predict(X_test) \n\n# compute R2 scores\nscore_train = predictor.score(X_train, Y_train) \nscore_test = predictor.score(X_test, Y_test) \n~~~\n\nThe resulting PWA model leads to the following partition\n<img src=\"http://cse.lab.imtlucca.it/~bemporad/parc/fig3.png\" alt=\"drawing\" width=65%/>\n\nand PWA function\n\n<img src=\"http://cse.lab.imtlucca.it/~bemporad/parc/fig5.png\" alt=\"drawing\" width=50%/>\n<img src=\"http://cse.lab.imtlucca.it/~bemporad/parc/fig2.png\" alt=\"drawing\" width=40%/>\n \n<a name=\"contributors\"><a>\n## Contributors\n\nThis package was coded by Alberto Bemporad.\n\n\nThis software is distributed without any warranty. Please cite the above papers if you use this software.\n\n<a name=\"bibliography\"><a>\n## Citing PARC\n\n<a name=\"ref1\"></a>\n\n```\n@article{Bem23,\n author={A. Bemporad},\n title={A Piecewise Linear Regression and Classification Algorithm with Application to Learning and Model Predictive Control of Hybrid Systems},\n journal={IEEE Transactions on Automatic Control},\n year=2023,\n month=jun,\n volume=68,\n number=6,\n pages={3194--3209},\n}\n```\n\n\n<a name=\"license\"><a>\n## License\n\nApache 2.0\n\n(C) 2021-2023 A. Bemporad\n",
"bugtrack_url": null,
"license": "",
"summary": "PARC - Piecewise Affine Regression and Classification",
"version": "2.0.4",
"project_urls": {
"Homepage": "http://cse.lab.imtlucca.it/~bemporad/parc"
},
"split_keywords": [
"piecewise linear regression",
"piecewise linear classification",
"multivariate regression",
"multivariate classification",
"supervised learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86d9c3fd95c0756ed869a10ec657c8e0516eb07ca524d80170b38e9244357d12",
"md5": "0d1f6dfa73fb4ff304ffdb3e956a5e78",
"sha256": "04c822f369ac523a1d1453f6a8cae4095d853d80ff68bdf5adb4e77e25cdae4f"
},
"downloads": -1,
"filename": "pyparc-2.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0d1f6dfa73fb4ff304ffdb3e956a5e78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18207,
"upload_time": "2023-07-04T12:24:53",
"upload_time_iso_8601": "2023-07-04T12:24:53.348729Z",
"url": "https://files.pythonhosted.org/packages/86/d9/c3fd95c0756ed869a10ec657c8e0516eb07ca524d80170b38e9244357d12/pyparc-2.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6430b896ea88246776ef61be0cdf51affbfd8eaae440848f1597c1b06064915",
"md5": "abbcd084de076904bae40627d74d8e98",
"sha256": "00727f1dce62a1a2bc7e662f1907f39ed1270a2cd52d2dc9fd464f1c30d32119"
},
"downloads": -1,
"filename": "pyparc-2.0.4.tar.gz",
"has_sig": false,
"md5_digest": "abbcd084de076904bae40627d74d8e98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20258,
"upload_time": "2023-07-04T12:24:55",
"upload_time_iso_8601": "2023-07-04T12:24:55.172774Z",
"url": "https://files.pythonhosted.org/packages/d6/43/0b896ea88246776ef61be0cdf51affbfd8eaae440848f1597c1b06064915/pyparc-2.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-04 12:24:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyparc"
}
JSON