***
gmr
***
Gaussian Mixture Models (GMMs) for clustering and regression in Python.
.. image:: https://api.travis-ci.org/AlexanderFabisch/gmr.png?branch=master
:target: https://travis-ci.org/AlexanderFabisch/gmr
:alt: Travis
.. image:: https://joss.theoj.org/papers/10.21105/joss.03054/status.svg
:target: https://doi.org/10.21105/joss.03054
:alt: DOI (JOSS)
.. image:: https://zenodo.org/badge/17119390.svg
:target: https://zenodo.org/badge/latestdoi/17119390
:alt: DOI (Zenodo)
.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/gmr.png
`(Source code of example) <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_regression.py>`_
* Source code repository: https://github.com/AlexanderFabisch/gmr
* License: `New BSD / BSD 3-clause <https://github.com/AlexanderFabisch/gmr/blob/master/LICENSE>`_
* Releases: https://github.com/AlexanderFabisch/gmr/releases
* `API documentation <https://alexanderfabisch.github.io/gmr/>`_
Documentation
=============
Installation
------------
Install from `PyPI`_:
.. code-block:: bash
pip install gmr
If you want to be able to run all examples, pip can install all necessary
examples with
.. code-block::
pip install gmr[all]
You can also install `gmr` from source:
.. code-block:: bash
python setup.py install
# alternatively: pip install -e .
.. _PyPi: https://pypi.python.org/pypi
Example
-------
Estimate GMM from samples, sample from GMM, and make predictions:
.. code-block:: python
import numpy as np
from gmr import GMM
# Your dataset as a NumPy array of shape (n_samples, n_features):
X = np.random.randn(100, 2)
gmm = GMM(n_components=3, random_state=0)
gmm.from_samples(X)
# Estimate GMM with expectation maximization:
X_sampled = gmm.sample(100)
# Make predictions with known values for the first feature:
x1 = np.random.randn(20, 1)
x1_index = [0]
x2_predicted_mean = gmm.predict(x1_index, x1)
For more details, see:
.. code-block:: python
help(gmr)
or have a look at the
`API documentation <https://alexanderfabisch.github.io/gmr/>`_.
How Does It Compare to scikit-learn?
------------------------------------
There is an implementation of Gaussian Mixture Models for clustering in
`scikit-learn <https://scikit-learn.org/stable/modules/classes.html#module-sklearn.mixture>`_
as well. Regression could not be easily integrated in the interface of
sklearn. That is the reason why I put the code in a separate repository.
It is possible to initialize GMR from sklearn though:
.. code-block:: python
from sklearn.mixture import GaussianMixture
from gmr import GMM
gmm_sklearn = GaussianMixture(n_components=3, covariance_type="diag")
gmm_sklearn.fit(X)
gmm = GMM(
n_components=3, priors=gmm_sklearn.weights_, means=gmm_sklearn.means_,
covariances=np.array([np.diag(c) for c in gmm_sklearn.covariances_]))
For model selection with sklearn we furthermore provide an optional
regressor interface.
Gallery
-------
.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/sklearn_initialization.png
:width: 60%
`Diagonal covariances <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_iris_from_sklearn.py>`_
.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/confidence_sampling.png
:width: 60%
`Sample from confidence interval <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_sample_mvn_confidence_interval.py>`_
.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/trajectories.png
:width: 60%
`Generate trajectories <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_trajectories.py>`_
.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/time_invariant_trajectories.png
:width: 60%
`Sample time-invariant trajectories <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_time_invariant_trajectories.py>`_
You can find `all examples here <https://github.com/AlexanderFabisch/gmr/tree/master/examples>`_.
Saving a Model
--------------
This library does not directly offer a function to store fitted models. Since
the implementation is pure Python, it is possible, however, to use standard
Python tools to store Python objects. For example, you can use pickle to
temporarily store a GMM:
.. code-block:: python
import numpy as np
import pickle
import gmr
gmm = gmr.GMM(n_components=2)
gmm.from_samples(X=np.random.randn(1000, 3))
# Save object gmm to file 'file'
pickle.dump(gmm, open("file", "wb"))
# Load object from file 'file'
gmm2 = pickle.load(open("file", "rb"))
It might be required to store models more permanently than in a pickle file,
which might break with a change of the library or with the Python version.
In this case you can choose a storage format that you like and store the
attributes `gmm.priors`, `gmm.means`, and `gmm.covariances`. These can be
used in the constructor of the GMM class to recreate the object and they can
also be used in other libraries that provide a GMM implementation. The
MVN class only needs the attributes `mean` and `covariance` to define the
model.
API Documentation
-----------------
API documentation is available
`here <https://alexanderfabisch.github.io/gmr/>`_.
Citation
--------
If you use the library gmr in a scientific publication, I would appreciate
citation of the following paper:
Fabisch, A., (2021). gmr: Gaussian Mixture Regression. Journal of Open Source
Software, 6(62), 3054, https://doi.org/10.21105/joss.03054
Bibtex entry:
.. code-block:: bibtex
@article{Fabisch2021,
doi = {10.21105/joss.03054},
url = {https://doi.org/10.21105/joss.03054},
year = {2021},
publisher = {The Open Journal},
volume = {6},
number = {62},
pages = {3054},
author = {Alexander Fabisch},
title = {gmr: Gaussian Mixture Regression},
journal = {Journal of Open Source Software}
}
Contributing
============
How can I contribute?
---------------------
If you discover bugs, have feature requests, or want to improve the
documentation, you can open an issue at the
`issue tracker <https://github.com/AlexanderFabisch/gmr/issues>`_
of the project.
If you want to contribute code, please open a pull request via
GitHub by forking the project, committing changes to your fork,
and then opening a
`pull request <https://github.com/AlexanderFabisch/gmr/pulls>`_
from your forked branch to the main branch of `gmr`.
Development Environment
-----------------------
I would recommend to install `gmr` from source in editable mode with `pip` and
install all dependencies:
.. code-block::
pip install -e .[all,test,doc]
You can now run tests with
nosetests --with-coverage
The option `--with-coverage` will print a coverage report and output an
HTML overview to the folder `cover/`.
Generate Documentation
----------------------
The API documentation is generated with
`pdoc3 <https://pdoc3.github.io/pdoc/>`_. If you want to regenerate it,
you can run
.. code-block:: bash
pdoc gmr --html --skip-errors
Related Publications
====================
The first publication that presents the GMR algorithm is
[1] Z. Ghahramani, M. I. Jordan, "Supervised learning from incomplete data via an EM approach," Advances in Neural Information Processing Systems 6, 1994, pp. 120-127, http://papers.nips.cc/paper/767-supervised-learning-from-incomplete-data-via-an-em-approach
but it does not use the term Gaussian Mixture Regression, which to my knowledge occurs first in
[2] S. Calinon, F. Guenter and A. Billard, "On Learning, Representing, and Generalizing a Task in a Humanoid Robot," in IEEE Transactions on Systems, Man, and Cybernetics, Part B (Cybernetics), vol. 37, no. 2, 2007, pp. 286-298, doi: `10.1109/TSMCB.2006.886952 <https://doi.org/10.1109/TSMCB.2006.886952>`_.
A recent survey on various regression models including GMR is the following:
[3] F. Stulp, O. Sigaud, "Many regression algorithms, one unified model: A review," in Neural Networks, vol. 69, 2015, pp. 60-79, doi: `10.1016/j.neunet.2015.05.005 <https://doi.org/10.1016/j.neunet.2015.05.005>`_.
Sylvain Calinon has a good introduction in his `slides on nonlinear regression <http://calinon.ch/misc/EE613/EE613-slides-9.pdf>`_ for his `machine learning course <http://calinon.ch/teaching_EPFL.htm>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/AlexanderFabisch/gmr",
"name": "gmr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Alexander Fabisch",
"author_email": "afabisch@googlemail.com",
"download_url": "https://files.pythonhosted.org/packages/db/30/083d51329bc78d83b14c746e1d58dac80791baa9954cf523fccfa88e29a3/gmr-1.6.2.tar.gz",
"platform": "",
"description": "***\ngmr\n***\n\n Gaussian Mixture Models (GMMs) for clustering and regression in Python.\n\n.. image:: https://api.travis-ci.org/AlexanderFabisch/gmr.png?branch=master\n :target: https://travis-ci.org/AlexanderFabisch/gmr\n :alt: Travis\n\n.. image:: https://joss.theoj.org/papers/10.21105/joss.03054/status.svg\n :target: https://doi.org/10.21105/joss.03054\n :alt: DOI (JOSS)\n\n.. image:: https://zenodo.org/badge/17119390.svg\n :target: https://zenodo.org/badge/latestdoi/17119390\n :alt: DOI (Zenodo)\n\n.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/gmr.png\n\n`(Source code of example) <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_regression.py>`_\n\n* Source code repository: https://github.com/AlexanderFabisch/gmr\n* License: `New BSD / BSD 3-clause <https://github.com/AlexanderFabisch/gmr/blob/master/LICENSE>`_\n* Releases: https://github.com/AlexanderFabisch/gmr/releases\n* `API documentation <https://alexanderfabisch.github.io/gmr/>`_\n\nDocumentation\n=============\n\nInstallation\n------------\n\nInstall from `PyPI`_:\n\n.. code-block:: bash\n\n pip install gmr\n\nIf you want to be able to run all examples, pip can install all necessary\nexamples with\n\n.. code-block::\n\n pip install gmr[all]\n\nYou can also install `gmr` from source:\n\n.. code-block:: bash\n\n python setup.py install\n # alternatively: pip install -e .\n\n.. _PyPi: https://pypi.python.org/pypi\n\nExample\n-------\n\nEstimate GMM from samples, sample from GMM, and make predictions:\n\n.. code-block:: python\n\n import numpy as np\n from gmr import GMM\n\n # Your dataset as a NumPy array of shape (n_samples, n_features):\n X = np.random.randn(100, 2)\n\n gmm = GMM(n_components=3, random_state=0)\n gmm.from_samples(X)\n\n # Estimate GMM with expectation maximization:\n X_sampled = gmm.sample(100)\n\n # Make predictions with known values for the first feature:\n x1 = np.random.randn(20, 1)\n x1_index = [0]\n x2_predicted_mean = gmm.predict(x1_index, x1)\n\n\nFor more details, see:\n\n.. code-block:: python\n\n help(gmr)\n\nor have a look at the\n`API documentation <https://alexanderfabisch.github.io/gmr/>`_.\n\n\nHow Does It Compare to scikit-learn?\n------------------------------------\n\nThere is an implementation of Gaussian Mixture Models for clustering in\n`scikit-learn <https://scikit-learn.org/stable/modules/classes.html#module-sklearn.mixture>`_\nas well. Regression could not be easily integrated in the interface of\nsklearn. That is the reason why I put the code in a separate repository.\nIt is possible to initialize GMR from sklearn though:\n\n.. code-block:: python\n\n from sklearn.mixture import GaussianMixture\n from gmr import GMM\n gmm_sklearn = GaussianMixture(n_components=3, covariance_type=\"diag\")\n gmm_sklearn.fit(X)\n gmm = GMM(\n n_components=3, priors=gmm_sklearn.weights_, means=gmm_sklearn.means_,\n covariances=np.array([np.diag(c) for c in gmm_sklearn.covariances_]))\n\nFor model selection with sklearn we furthermore provide an optional\nregressor interface.\n\n\nGallery\n-------\n\n.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/sklearn_initialization.png\n :width: 60%\n\n`Diagonal covariances <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_iris_from_sklearn.py>`_\n\n.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/confidence_sampling.png\n :width: 60%\n\n`Sample from confidence interval <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_sample_mvn_confidence_interval.py>`_\n\n.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/trajectories.png\n :width: 60%\n\n`Generate trajectories <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_trajectories.py>`_\n\n.. image:: https://raw.githubusercontent.com/AlexanderFabisch/gmr/master/doc/time_invariant_trajectories.png\n :width: 60%\n\n`Sample time-invariant trajectories <https://github.com/AlexanderFabisch/gmr/blob/master/examples/plot_time_invariant_trajectories.py>`_\n\nYou can find `all examples here <https://github.com/AlexanderFabisch/gmr/tree/master/examples>`_.\n\n\nSaving a Model\n--------------\n\nThis library does not directly offer a function to store fitted models. Since\nthe implementation is pure Python, it is possible, however, to use standard\nPython tools to store Python objects. For example, you can use pickle to\ntemporarily store a GMM:\n\n.. code-block:: python\n\n import numpy as np\n import pickle\n import gmr\n gmm = gmr.GMM(n_components=2)\n gmm.from_samples(X=np.random.randn(1000, 3))\n\n # Save object gmm to file 'file'\n pickle.dump(gmm, open(\"file\", \"wb\"))\n # Load object from file 'file'\n gmm2 = pickle.load(open(\"file\", \"rb\"))\n\nIt might be required to store models more permanently than in a pickle file,\nwhich might break with a change of the library or with the Python version.\nIn this case you can choose a storage format that you like and store the\nattributes `gmm.priors`, `gmm.means`, and `gmm.covariances`. These can be\nused in the constructor of the GMM class to recreate the object and they can\nalso be used in other libraries that provide a GMM implementation. The\nMVN class only needs the attributes `mean` and `covariance` to define the\nmodel.\n\n\nAPI Documentation\n-----------------\n\nAPI documentation is available\n`here <https://alexanderfabisch.github.io/gmr/>`_.\n\n\nCitation\n--------\n\nIf you use the library gmr in a scientific publication, I would appreciate\ncitation of the following paper:\n\nFabisch, A., (2021). gmr: Gaussian Mixture Regression. Journal of Open Source\nSoftware, 6(62), 3054, https://doi.org/10.21105/joss.03054\n\nBibtex entry:\n\n.. code-block:: bibtex\n\n @article{Fabisch2021,\n doi = {10.21105/joss.03054},\n url = {https://doi.org/10.21105/joss.03054},\n year = {2021},\n publisher = {The Open Journal},\n volume = {6},\n number = {62},\n pages = {3054},\n author = {Alexander Fabisch},\n title = {gmr: Gaussian Mixture Regression},\n journal = {Journal of Open Source Software}\n }\n\n\nContributing\n============\n\nHow can I contribute?\n---------------------\n\nIf you discover bugs, have feature requests, or want to improve the\ndocumentation, you can open an issue at the\n`issue tracker <https://github.com/AlexanderFabisch/gmr/issues>`_\nof the project.\n\nIf you want to contribute code, please open a pull request via\nGitHub by forking the project, committing changes to your fork,\nand then opening a\n`pull request <https://github.com/AlexanderFabisch/gmr/pulls>`_\nfrom your forked branch to the main branch of `gmr`.\n\n\nDevelopment Environment\n-----------------------\n\nI would recommend to install `gmr` from source in editable mode with `pip` and\ninstall all dependencies:\n\n.. code-block::\n\n pip install -e .[all,test,doc]\n\nYou can now run tests with\n\n nosetests --with-coverage\n\nThe option `--with-coverage` will print a coverage report and output an\nHTML overview to the folder `cover/`.\n\nGenerate Documentation\n----------------------\n\nThe API documentation is generated with\n`pdoc3 <https://pdoc3.github.io/pdoc/>`_. If you want to regenerate it,\nyou can run\n\n.. code-block:: bash\n\n pdoc gmr --html --skip-errors\n\n\nRelated Publications\n====================\n\nThe first publication that presents the GMR algorithm is\n\n [1] Z. Ghahramani, M. I. Jordan, \"Supervised learning from incomplete data via an EM approach,\" Advances in Neural Information Processing Systems 6, 1994, pp. 120-127, http://papers.nips.cc/paper/767-supervised-learning-from-incomplete-data-via-an-em-approach\n\nbut it does not use the term Gaussian Mixture Regression, which to my knowledge occurs first in\n\n [2] S. Calinon, F. Guenter and A. Billard, \"On Learning, Representing, and Generalizing a Task in a Humanoid Robot,\" in IEEE Transactions on Systems, Man, and Cybernetics, Part B (Cybernetics), vol. 37, no. 2, 2007, pp. 286-298, doi: `10.1109/TSMCB.2006.886952 <https://doi.org/10.1109/TSMCB.2006.886952>`_.\n\nA recent survey on various regression models including GMR is the following:\n\n [3] F. Stulp, O. Sigaud, \"Many regression algorithms, one unified model: A review,\" in Neural Networks, vol. 69, 2015, pp. 60-79, doi: `10.1016/j.neunet.2015.05.005 <https://doi.org/10.1016/j.neunet.2015.05.005>`_.\n\nSylvain Calinon has a good introduction in his `slides on nonlinear regression <http://calinon.ch/misc/EE613/EE613-slides-9.pdf>`_ for his `machine learning course <http://calinon.ch/teaching_EPFL.htm>`_.",
"bugtrack_url": null,
"license": "new BSD",
"summary": "Gaussian Mixture Regression",
"version": "1.6.2",
"project_urls": {
"Homepage": "https://github.com/AlexanderFabisch/gmr"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db30083d51329bc78d83b14c746e1d58dac80791baa9954cf523fccfa88e29a3",
"md5": "1141ff9f3195ef6288b10134fe8d0d5b",
"sha256": "953e3f350ac94557612a1832cba0c319389d4f857fe0cf8cd51a1706c3935e6d"
},
"downloads": -1,
"filename": "gmr-1.6.2.tar.gz",
"has_sig": false,
"md5_digest": "1141ff9f3195ef6288b10134fe8d0d5b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 249670,
"upload_time": "2021-10-25T20:32:29",
"upload_time_iso_8601": "2021-10-25T20:32:29.385334Z",
"url": "https://files.pythonhosted.org/packages/db/30/083d51329bc78d83b14c746e1d58dac80791baa9954cf523fccfa88e29a3/gmr-1.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-10-25 20:32:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AlexanderFabisch",
"github_project": "gmr",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "gmr"
}
JSON
