DPPy: Sampling Determinantal Point Processes with Python
========================================================
|Documentation Status| |Build Status| |Coverage Status| |PyPI package|
.. |Documentation Status| image:: https://readthedocs.org/projects/dppy/badge/?version=latest
:target: https://dppy.readthedocs.io/en/latest/?badge=latest
.. |Build Status| image:: https://travis-ci.com/guilgautier/DPPy.svg?branch=master
:target: https://travis-ci.com/guilgautier/DPPy
.. |Coverage Status| image:: https://coveralls.io/repos/github/guilgautier/DPPy/badge.svg?branch=master
:target: https://coveralls.io/github/guilgautier/DPPy?branch=master
.. |PyPI package| image:: https://img.shields.io/pypi/v/dppy?color=blue
:target: https://pypi.org/project/dppy/
.. |Google Colab| image:: https://badgen.net/badge/Launch/on%20Google%20Colab/blue?icon=terminal
:target: https://colab.research.google.com/github/guilgautier/DPPy/blob/master/notebooks/Tuto_DPPy.ipynb
*"Anything that can go wrong, will go wrong"* − `Murphy's Law <http://phdcomics.com/comics/archive.php?comicid=1867>`_
Introduction
------------
Determinantal point processes (DPPs) are specific probability
distributions over clouds of points that have been popular as models or
computational tools across physics, probability, statistics, and more
recently of booming interest in machine learning. Sampling from DPPs is
a nontrivial matter, and many approaches have been proposed. DPPy is a
`Python <https://www.python.org/>`__ library that puts together all
exact and approximate sampling algorithms for DPPs.
Installation
------------
DPPy works with `Python 3.6+ <http://docs.python.org/3/>`__.
Dependencies
~~~~~~~~~~~~
This project depends on the following libraries, which are automatically downloaded during installation:
- `NumPy <http://www.numpy.org>`__
- `SciPy <http://www.scipy.org/>`__
- `Matplotlib <http://matplotlib.org/>`__
The following dependencies are optional, and unlock extra functionality if installed:
- `Networkx <http://networkx.github.io/>`__ to play with `uniform
spanning
trees <https://dppy.readthedocs.io/en/latest/exotic_dpps/index.html#uniform-spanning-trees>`__ .
- `CVXOPT <http://cvxopt.org>`__ to use the ``zono_sampling`` MCMC
sampler for finite DPPs. **CVXOPT itself requires**
`GCC <http://gcc.gnu.org>`__,
- On MAC it comes with
`Xcode <https://developer.apple.com/xcode/>`__
- On UNIX, use your package manager (``apt``, ``yum`` etc)
.. code:: bash
sudo apt install -qq gcc g++
- `Sphinx <http://www.sphinx-doc.org/en/master/>`__ to modify and rebuild the documentation
Installation instructions
~~~~~~~~~~~~~~~~~~~~~~~~~
DPPy is now available on `PyPI <https://pypi.org/project/dppy/>`__ |PyPI package|
.. code:: bash
pip install dppy
For a full installation, including extra dependencies and dependencies necessary to build the documentation (see above), use :code:`pip install dppy['zonotope','trees','docs']`.
Note that only stable DPPy releases are available on PyPI, and recently included improvements might only be available on the git master branch. If you want to work with the latest version of DPPy
1. If you have a GitHub account please consider forking DPPy and use git to clone your copy of the repo
.. code:: bash
cd <directory_of_your_choice>
git clone https://github.com/<username>/DPPy.git
2. If you only use git, clone this repository
.. code:: bash
cd <directory_of_your_choice>
git clone https://github.com/guilgautier/DPPy.git
3. Otherwise simply download the project
4. In any case, install the project with
.. code:: bash
cd DPPy
pip install .
Use :code:`pip install .['zonotope','trees','docs']` to perform a full install from a local source tree.
How to use it
-------------
The main DPPy documentation is available online at `http://dppy.readthedocs.io <http://dppy.readthedocs.io>`_.
There are also some interactive tutorials using Jupyter available at https://github.com/guilgautier/DPPy/blob/master/notebooks/.
For more details, check below.
Tutorials in `Jupyter notebooks <https://github.com/guilgautier/DPPy/blob/master/notebooks/>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can read and work on these interactive tutorial `Notebooks <https://github.com/guilgautier/DPPy/blob/master/notebooks/>`_, directly from your
web browser, without having to download or install Python or anything.
Just click, wait a little bit, and play with the notebook!
Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~
The
`documentation <http://dppy.readthedocs.io/>`__
is generated locally with
`Sphinx <http://www.sphinx-doc.org/en/master/>`__ and then built online
by `ReadTheDocs <https://readthedocs.org/projects/dppy/>`__.
If you wish to contribute to the documentation or just play with it
locally, you can install the necessary dependencies and then:
- Generate the docs locally
.. code:: bash
cd DPPy/docs
make html
- Open the local HTML version of the documentation located at
``DPPy/docs/_build/html/index.html``
.. code:: bash
open _build/html/index.html
How to cite this work?
~~~~~~~~~~~~~~~~~~~~~~
`We wrote a companion paper to DPPy which got accepted for publication in the Machine Learning Open Source Software track of JMLR <http://jmlr.org/papers/v20/19-179.html>`__.
If you use the DPPy toolbox, please consider citing it with this piece of
BibTeX:
.. code:: bibtex
@article{GPBV19,
author = {Gautier, Guillaume and Polito, Guillermo and Bardenet, R{\'{e}}mi and Valko, Michal},
journal = {Journal of Machine Learning Research - Machine Learning Open Source Software (JMLR-MLOSS)},
title = {{DPPy: DPP Sampling with Python}},
keywords = {Computer Science - Machine Learning, Computer Science - Mathematical Software, Statistics - Machine Learning},
url = {http://jmlr.org/papers/v20/19-179.html},
year = {2019},
archivePrefix = {arXiv},
arxivId = {1809.07258},
note = {Code at http://github.com/guilgautier/DPPy/ Documentation at http://dppy.readthedocs.io/}
}
Many of the algorithms implemented in DPPy also have associated literature that you should consider citing.
Please refer to the `bibliography on the documentation page <https://dppy.readthedocs.io/en/latest/bibliography/>`__ and docstrings of each specific DPP sampler for details.
Reproducibility
---------------
We would like to thank `Guillermo Polito <https://guillep.github.io/>`__
for leading our reproducible research
`workgroup <https://github.com/CRIStAL-PADR/reproducible-research-SE-notes>`__,
this project owes him a lot.
Take a look at the corresponding
`booklet <https://github.com/CRIStAL-PADR/reproducible-research-SE-notes>`__
to learn more on how to make your research reproducible!
Raw data
{
"_id": null,
"home_page": "https://github.com/guilgautier/DPPy",
"name": "dppy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Determinantal Point Processes, sampling schemes, random matrices",
"author": "Guillaume Gautier",
"author_email": "guillaume.gga@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ab/74/a2bbcb284764a9ad739bda4a082770c304d977cb0b672790b9b149e8d475/dppy-0.3.3.tar.gz",
"platform": null,
"description": "DPPy: Sampling Determinantal Point Processes with Python\n========================================================\n\n|Documentation Status| |Build Status| |Coverage Status| |PyPI package|\n\n.. |Documentation Status| image:: https://readthedocs.org/projects/dppy/badge/?version=latest\n :target: https://dppy.readthedocs.io/en/latest/?badge=latest\n\n.. |Build Status| image:: https://travis-ci.com/guilgautier/DPPy.svg?branch=master\n :target: https://travis-ci.com/guilgautier/DPPy\n\n.. |Coverage Status| image:: https://coveralls.io/repos/github/guilgautier/DPPy/badge.svg?branch=master\n :target: https://coveralls.io/github/guilgautier/DPPy?branch=master\n\n.. |PyPI package| image:: https://img.shields.io/pypi/v/dppy?color=blue\n :target: https://pypi.org/project/dppy/\n\n.. |Google Colab| image:: https://badgen.net/badge/Launch/on%20Google%20Colab/blue?icon=terminal\n :target: https://colab.research.google.com/github/guilgautier/DPPy/blob/master/notebooks/Tuto_DPPy.ipynb\n\n*\"Anything that can go wrong, will go wrong\"* \u2212 `Murphy's Law <http://phdcomics.com/comics/archive.php?comicid=1867>`_\n\nIntroduction\n------------\n\nDeterminantal point processes (DPPs) are specific probability\ndistributions over clouds of points that have been popular as models or\ncomputational tools across physics, probability, statistics, and more\nrecently of booming interest in machine learning. Sampling from DPPs is\na nontrivial matter, and many approaches have been proposed. DPPy is a\n`Python <https://www.python.org/>`__ library that puts together all\nexact and approximate sampling algorithms for DPPs.\n\nInstallation\n------------\n\nDPPy works with `Python 3.6+ <http://docs.python.org/3/>`__.\n\nDependencies\n~~~~~~~~~~~~\n\nThis project depends on the following libraries, which are automatically downloaded during installation:\n\n- `NumPy <http://www.numpy.org>`__\n- `SciPy <http://www.scipy.org/>`__\n- `Matplotlib <http://matplotlib.org/>`__\n\nThe following dependencies are optional, and unlock extra functionality if installed:\n\n- `Networkx <http://networkx.github.io/>`__ to play with `uniform\n spanning\n trees <https://dppy.readthedocs.io/en/latest/exotic_dpps/index.html#uniform-spanning-trees>`__ .\n- `CVXOPT <http://cvxopt.org>`__ to use the ``zono_sampling`` MCMC\n sampler for finite DPPs. **CVXOPT itself requires**\n `GCC <http://gcc.gnu.org>`__,\n\n - On MAC it comes with\n `Xcode <https://developer.apple.com/xcode/>`__\n - On UNIX, use your package manager (``apt``, ``yum`` etc)\n\n .. code:: bash\n\n sudo apt install -qq gcc g++\n\n- `Sphinx <http://www.sphinx-doc.org/en/master/>`__ to modify and rebuild the documentation\n\nInstallation instructions\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDPPy is now available on `PyPI <https://pypi.org/project/dppy/>`__ |PyPI package|\n\n.. code:: bash\n\n pip install dppy\n\nFor a full installation, including extra dependencies and dependencies necessary to build the documentation (see above), use :code:`pip install dppy['zonotope','trees','docs']`.\n\nNote that only stable DPPy releases are available on PyPI, and recently included improvements might only be available on the git master branch. If you want to work with the latest version of DPPy\n\n1. If you have a GitHub account please consider forking DPPy and use git to clone your copy of the repo\n\n .. code:: bash\n\n cd <directory_of_your_choice>\n git clone https://github.com/<username>/DPPy.git\n\n2. If you only use git, clone this repository\n\n .. code:: bash\n\n cd <directory_of_your_choice>\n git clone https://github.com/guilgautier/DPPy.git\n\n3. Otherwise simply download the project\n\n4. In any case, install the project with\n\n .. code:: bash\n\n cd DPPy\n pip install .\n\nUse :code:`pip install .['zonotope','trees','docs']` to perform a full install from a local source tree.\n\nHow to use it\n-------------\n\nThe main DPPy documentation is available online at `http://dppy.readthedocs.io <http://dppy.readthedocs.io>`_.\nThere are also some interactive tutorials using Jupyter available at https://github.com/guilgautier/DPPy/blob/master/notebooks/.\nFor more details, check below.\n\nTutorials in `Jupyter notebooks <https://github.com/guilgautier/DPPy/blob/master/notebooks/>`_\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can read and work on these interactive tutorial `Notebooks <https://github.com/guilgautier/DPPy/blob/master/notebooks/>`_, directly from your\nweb browser, without having to download or install Python or anything.\nJust click, wait a little bit, and play with the notebook!\n\nBuilding the documentation\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe\n`documentation <http://dppy.readthedocs.io/>`__\nis generated locally with\n`Sphinx <http://www.sphinx-doc.org/en/master/>`__ and then built online\nby `ReadTheDocs <https://readthedocs.org/projects/dppy/>`__.\nIf you wish to contribute to the documentation or just play with it\nlocally, you can install the necessary dependencies and then:\n\n- Generate the docs locally\n\n .. code:: bash\n\n cd DPPy/docs\n make html\n\n- Open the local HTML version of the documentation located at\n ``DPPy/docs/_build/html/index.html``\n\n .. code:: bash\n\n open _build/html/index.html\n\nHow to cite this work?\n~~~~~~~~~~~~~~~~~~~~~~\n\n`We wrote a companion paper to DPPy which got accepted for publication in the Machine Learning Open Source Software track of JMLR <http://jmlr.org/papers/v20/19-179.html>`__.\n\nIf you use the DPPy toolbox, please consider citing it with this piece of\nBibTeX:\n\n.. code:: bibtex\n\n @article{GPBV19,\n author = {Gautier, Guillaume and Polito, Guillermo and Bardenet, R{\\'{e}}mi and Valko, Michal},\n journal = {Journal of Machine Learning Research - Machine Learning Open Source Software (JMLR-MLOSS)},\n title = {{DPPy: DPP Sampling with Python}},\n keywords = {Computer Science - Machine Learning, Computer Science - Mathematical Software, Statistics - Machine Learning},\n url = {http://jmlr.org/papers/v20/19-179.html},\n year = {2019},\n archivePrefix = {arXiv},\n arxivId = {1809.07258},\n note = {Code at http://github.com/guilgautier/DPPy/ Documentation at http://dppy.readthedocs.io/}\n }\n\nMany of the algorithms implemented in DPPy also have associated literature that you should consider citing.\nPlease refer to the `bibliography on the documentation page <https://dppy.readthedocs.io/en/latest/bibliography/>`__ and docstrings of each specific DPP sampler for details.\n\nReproducibility\n---------------\n\nWe would like to thank `Guillermo Polito <https://guillep.github.io/>`__\nfor leading our reproducible research\n`workgroup <https://github.com/CRIStAL-PADR/reproducible-research-SE-notes>`__,\nthis project owes him a lot.\n\nTake a look at the corresponding\n`booklet <https://github.com/CRIStAL-PADR/reproducible-research-SE-notes>`__\nto learn more on how to make your research reproducible!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "DPPy is a Python library for exact and approximate sampling of Determinantal Point Processes.",
"version": "0.3.3",
"project_urls": {
"Companion paper": "https://github.com/guilgautier/DPPy_paper",
"Coverage": "https://coveralls.io/github/guilgautier/DPPy?branch=master",
"Documentation": "https://dppy.readthedocs.io/en/latest/",
"Homepage": "https://github.com/guilgautier/DPPy",
"Source code": "https://github.com/guilgautier/DPPy",
"Travis": "https://travis-ci.com/guilgautier/DPPy",
"arXiv": "https://arxiv.org/abs/1809.07258"
},
"split_keywords": [
"determinantal point processes",
" sampling schemes",
" random matrices"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0edcb04624d24be1f5512a2f48b9028b9fdc474907f84b5e2e3e4bf204b74757",
"md5": "1890f35649bc1d53da787a49cb35a3ed",
"sha256": "a770d6b906a9939a156e8e6f86d9d3b880edc1df8639106bff60b18fc1b483ab"
},
"downloads": -1,
"filename": "dppy-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1890f35649bc1d53da787a49cb35a3ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 83822,
"upload_time": "2024-08-14T20:46:04",
"upload_time_iso_8601": "2024-08-14T20:46:04.740072Z",
"url": "https://files.pythonhosted.org/packages/0e/dc/b04624d24be1f5512a2f48b9028b9fdc474907f84b5e2e3e4bf204b74757/dppy-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ab74a2bbcb284764a9ad739bda4a082770c304d977cb0b672790b9b149e8d475",
"md5": "8e3dfc416b7141e9af0f7f949e372fc6",
"sha256": "cfd381b29c535e62dfb347636a54cb0a5e18fb5ca4f55e206dc9c5b14e3ba980"
},
"downloads": -1,
"filename": "dppy-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "8e3dfc416b7141e9af0f7f949e372fc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 93261,
"upload_time": "2024-08-14T20:46:06",
"upload_time_iso_8601": "2024-08-14T20:46:06.447704Z",
"url": "https://files.pythonhosted.org/packages/ab/74/a2bbcb284764a9ad739bda4a082770c304d977cb0b672790b9b149e8d475/dppy-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-14 20:46:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guilgautier",
"github_project": "DPPy",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "cvxopt",
"specs": [
[
"==",
"1.2.1"
]
]
},
{
"name": "networkx",
"specs": []
},
{
"name": "sphinxcontrib-bibtex",
"specs": []
},
{
"name": "sphinx_rtd_theme",
"specs": []
}
],
"lcname": "dppy"
}
JSON
