====================================================
Venn diagram plotting routines for Python/Matplotlib
====================================================
.. image:: https://travis-ci.org/konstantint/matplotlib-venn.png?branch=master
:target: https://travis-ci.org/konstantint/matplotlib-venn
Routines for plotting area-weighted two- and three-circle venn diagrams.
Installation
------------
Install the package as usual via ``pip``::
$ python -m pip install matplotlib-venn
Since version 1.1.0 the package includes an extra "cost based" layout algorithm for `venn3` diagrams,
that relies on the `shapely` package, which is not installed as a default dependency. If you need the
new algorithm (or just have nothing against installing `shapely` along the way), instead do::
$ python -m pip install "matplotlib-venn[shapely]"
It is quite probable that `shapely` will become a required dependency eventually in one of the future versions.
Dependencies
------------
- ``numpy``,
- ``scipy``,
- ``matplotlib``,
- ``shapely`` (optional).
Usage
-----
The package provides four main functions: ``venn2``,
``venn2_circles``, ``venn3`` and ``venn3_circles``.
The functions ``venn2`` and ``venn2_circles`` accept as their only
required argument a 3-element tuple ``(Ab, aB, AB)`` of subset sizes,
and draw a two-circle venn diagram with respective region areas, e.g.::
venn2(subsets = (3, 2, 1))
In this example, the region, corresponding to subset ``A and not B`` will
be three times larger in area than the region, corresponding to subset ``A and B``.
You can also provide a tuple of two ``set`` or ``Counter`` (i.e. multi-set)
objects instead (new in version 0.7), e.g.::
venn2((set(['A', 'B', 'C', 'D']), set(['D', 'E', 'F'])))
Similarly, the functions ``venn3`` and ``venn3_circles`` take a
7-element tuple of subset sizes ``(Abc, aBc, ABc, abC, AbC, aBC,
ABC)``, and draw a three-circle area-weighted Venn
diagram:
.. image:: https://user-images.githubusercontent.com/13646666/87874366-96924800-c9c9-11ea-8b06-ac1336506b59.png
Alternatively, a tuple of three ``set`` or ``Counter`` objects may be provided.
The functions ``venn2`` and ``venn3`` draw the diagrams as a collection of colored
patches, annotated with text labels. The functions ``venn2_circles`` and
``venn3_circles`` draw just the circles.
The functions ``venn2_circles`` and ``venn3_circles`` return the list of ``matplotlib.patch.Circle`` objects that may be tuned further
to your liking. The functions ``venn2`` and ``venn3`` return an object of class ``VennDiagram``,
which gives access to constituent patches, text elements, and (since
version 0.7) the information about the centers and radii of the
circles.
Basic Example::
from matplotlib_venn import venn2
venn2(subsets = (3, 2, 1))
For the three-circle case::
from matplotlib_venn import venn3
venn3(subsets = (1, 1, 1, 2, 1, 2, 2), set_labels = ('Set1', 'Set2', 'Set3'))
A more elaborate example::
from matplotlib import pyplot as plt
import numpy as np
from matplotlib_venn import venn3, venn3_circles
plt.figure(figsize=(4,4))
v = venn3(subsets=(1, 1, 1, 1, 1, 1, 1), set_labels = ('A', 'B', 'C'))
v.get_patch_by_id('100').set_alpha(1.0)
v.get_patch_by_id('100').set_color('white')
v.get_label_by_id('100').set_text('Unknown')
v.get_label_by_id('A').set_text('Set "A"')
c = venn3_circles(subsets=(1, 1, 1, 1, 1, 1, 1), linestyle='dashed')
c[0].set_lw(1.0)
c[0].set_ls('dotted')
plt.title("Sample Venn diagram")
plt.annotate('Unknown set', xy=v.get_label_by_id('100').get_position() - np.array([0, 0.05]), xytext=(-70,-70),
ha='center', textcoords='offset points', bbox=dict(boxstyle='round,pad=0.5', fc='gray', alpha=0.1),
arrowprops=dict(arrowstyle='->', connectionstyle='arc3,rad=0.5',color='gray'))
plt.show()
An example with multiple subplots::
from matplotlib_venn import venn2, venn2_circles
figure, axes = plt.subplots(2, 2)
venn2(subsets={'10': 1, '01': 1, '11': 1}, set_labels = ('A', 'B'), ax=axes[0][0])
venn2_circles((1, 2, 3), ax=axes[0][1])
venn3(subsets=(1, 1, 1, 1, 1, 1, 1), set_labels = ('A', 'B', 'C'), ax=axes[1][0])
venn3_circles({'001': 10, '100': 20, '010': 21, '110': 13, '011': 14}, ax=axes[1][1])
plt.show()
Perhaps the most common use case is generating a Venn diagram given
three sets of objects::
set1 = set(['A', 'B', 'C', 'D'])
set2 = set(['B', 'C', 'D', 'E'])
set3 = set(['C', 'D',' E', 'F', 'G'])
venn3([set1, set2, set3], ('Set1', 'Set2', 'Set3'))
plt.show()
Tuning the diagram layout
-------------------------
Note that for a three-circle venn diagram it is not in general
possible to achieve exact correspondence between the required set
sizes and region areas. The default layout algorithm aims to correctly represent:
* Relative areas of the full individual sets (A, B, C).
* Relative areas of pairwise intersections of sets (A&B, A&C, B&C, not to be confused with the regions
A&B&~C, A&~B&C, ~A&B&C, on the diagram).
Sometimes the result is unsatisfactory and either the area weighting or the layout logic needs
to be tuned.
The area weighing can be adjusted by providing a `fixed_subset_sizes` argument to the `DefaultLayoutAlgorithm`::
from matplotlib_venn.layout.venn2 import DefaultLayoutAlgorithm
venn2((1,2,3), layout_algorithm=DefaultLayoutAlgorithm(fixed_subset_sizes=(1,1,1)))
from matplotlib_venn.layout.venn3 import DefaultLayoutAlgorithm
venn3((7,6,5,4,3,2,1), layout_algorithm=DefaultLayoutAlgorithm(fixed_subset_sizes=(1,1,1,1,1,1,1)))
In the above examples the diagram regions will be plotted as if `venn2((1,1,1))` and `venn3((1,1,1,1,1,1,1))` were
invoked, yet the actual numbers will be `(1,2,3)` and `(7,6,5,4,3,2,1)` respectively.
The diagram can be tuned further by switching the layout algorithm to a different implementation.
At the moment the package offers an alternative layout algorithm for `venn3` diagrams that lays the circles out by
optimizing a user-provided *cost function*. The following examples illustrate its usage::
from matplotlib_venn.layout.venn3 import cost_based
subset_sizes = (100,200,10000,10,20,3,1)
venn3(subset_sizes, layout_algorithm=cost_based.LayoutAlgorithm())
alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.WeightedAggregateCost(transform_fn=lambda x: x))
venn3(subset_sizes, layout_algorithm=alg)
alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.WeightedAggregateCost(weights=(0,0,0,1,1,1,1)))
venn3(subset_sizes, layout_algorithm=alg)
The default "pairwise" algorithm is, theoretically, a special case of the cost-based method with the respective cost function::
alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.pairwise_cost)
venn3(subset_sizes, layout_algorithm=alg)
(The latter plot will be close, but not perfectly equal to the outcome of `DefaultLayoutAlgorithm()`).
Note that the import::
from matplotlib_venn.layout.venn3 import cost_based
will fail unless you have the optional `shapely` package installed (see "Installation" above).
Questions
---------
* If you ask your questions at `StackOverflow <http://stackoverflow.com/>`_ and tag them
`matplotlib-venn <http://stackoverflow.com/questions/tagged/matplotlib-venn>`_, chances are high you could get
an answer from the maintainer of this package.
See also
--------
* Report issues and submit fixes at Github:
https://github.com/konstantint/matplotlib-venn
Check out the ``DEVELOPER-README.rst`` for development-related notes.
* Some alternative means of plotting a Venn diagram (as of
October 2012) are reviewed in the blog post:
http://fouryears.eu/2012/10/13/venn-diagrams-in-python/
* The `matplotlib-subsets
<https://pypi.python.org/pypi/matplotlib-subsets>`_ package
visualizes a hierarchy of sets as a tree of rectangles.
* The `matplotlib_set_diagrams <https://pypi.org/project/matplotlib-set-diagrams>`_ package
is a GPL-licensed alternative that offers a different layout algorithm, which supports more than
three sets and provides a cool ability to incorporate wordclouds into your Venn (Euler) diagrams.
Raw data
{
"_id": null,
"home_page": "https://github.com/konstantint/matplotlib-venn",
"name": "matplotlib-venn",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "matplotlib plotting charts venn-diagrams",
"author": "Konstantin Tretyakov",
"author_email": "kt@umn.ee",
"download_url": "https://files.pythonhosted.org/packages/fe/a7/6e34cd021e9b668671909f67745cc062526c22e1c3971618d93d767dce5f/matplotlib-venn-1.1.1.tar.gz",
"platform": "Platform Independent",
"description": "====================================================\nVenn diagram plotting routines for Python/Matplotlib\n====================================================\n\n.. image:: https://travis-ci.org/konstantint/matplotlib-venn.png?branch=master\n :target: https://travis-ci.org/konstantint/matplotlib-venn\n\nRoutines for plotting area-weighted two- and three-circle venn diagrams.\n\nInstallation\n------------\n\nInstall the package as usual via ``pip``::\n\n $ python -m pip install matplotlib-venn\n\nSince version 1.1.0 the package includes an extra \"cost based\" layout algorithm for `venn3` diagrams,\nthat relies on the `shapely` package, which is not installed as a default dependency. If you need the\nnew algorithm (or just have nothing against installing `shapely` along the way), instead do::\n\n $ python -m pip install \"matplotlib-venn[shapely]\"\n\nIt is quite probable that `shapely` will become a required dependency eventually in one of the future versions.\n\nDependencies\n------------\n\n- ``numpy``,\n- ``scipy``,\n- ``matplotlib``,\n- ``shapely`` (optional).\n\nUsage\n-----\nThe package provides four main functions: ``venn2``,\n``venn2_circles``, ``venn3`` and ``venn3_circles``.\n\nThe functions ``venn2`` and ``venn2_circles`` accept as their only\nrequired argument a 3-element tuple ``(Ab, aB, AB)`` of subset sizes,\nand draw a two-circle venn diagram with respective region areas, e.g.::\n\n venn2(subsets = (3, 2, 1))\n\nIn this example, the region, corresponding to subset ``A and not B`` will\nbe three times larger in area than the region, corresponding to subset ``A and B``.\n\nYou can also provide a tuple of two ``set`` or ``Counter`` (i.e. multi-set)\nobjects instead (new in version 0.7), e.g.::\n\n venn2((set(['A', 'B', 'C', 'D']), set(['D', 'E', 'F'])))\n\nSimilarly, the functions ``venn3`` and ``venn3_circles`` take a\n7-element tuple of subset sizes ``(Abc, aBc, ABc, abC, AbC, aBC,\nABC)``, and draw a three-circle area-weighted Venn\ndiagram: \n\n.. image:: https://user-images.githubusercontent.com/13646666/87874366-96924800-c9c9-11ea-8b06-ac1336506b59.png\n\nAlternatively, a tuple of three ``set`` or ``Counter`` objects may be provided.\n\nThe functions ``venn2`` and ``venn3`` draw the diagrams as a collection of colored\npatches, annotated with text labels. The functions ``venn2_circles`` and\n``venn3_circles`` draw just the circles.\n\nThe functions ``venn2_circles`` and ``venn3_circles`` return the list of ``matplotlib.patch.Circle`` objects that may be tuned further\nto your liking. The functions ``venn2`` and ``venn3`` return an object of class ``VennDiagram``,\nwhich gives access to constituent patches, text elements, and (since\nversion 0.7) the information about the centers and radii of the\ncircles.\n\nBasic Example::\n\n from matplotlib_venn import venn2\n venn2(subsets = (3, 2, 1))\n\nFor the three-circle case::\n\n from matplotlib_venn import venn3\n venn3(subsets = (1, 1, 1, 2, 1, 2, 2), set_labels = ('Set1', 'Set2', 'Set3'))\n\nA more elaborate example::\n\n from matplotlib import pyplot as plt\n import numpy as np\n from matplotlib_venn import venn3, venn3_circles\n plt.figure(figsize=(4,4))\n v = venn3(subsets=(1, 1, 1, 1, 1, 1, 1), set_labels = ('A', 'B', 'C'))\n v.get_patch_by_id('100').set_alpha(1.0)\n v.get_patch_by_id('100').set_color('white')\n v.get_label_by_id('100').set_text('Unknown')\n v.get_label_by_id('A').set_text('Set \"A\"')\n c = venn3_circles(subsets=(1, 1, 1, 1, 1, 1, 1), linestyle='dashed')\n c[0].set_lw(1.0)\n c[0].set_ls('dotted')\n plt.title(\"Sample Venn diagram\")\n plt.annotate('Unknown set', xy=v.get_label_by_id('100').get_position() - np.array([0, 0.05]), xytext=(-70,-70),\n ha='center', textcoords='offset points', bbox=dict(boxstyle='round,pad=0.5', fc='gray', alpha=0.1),\n arrowprops=dict(arrowstyle='->', connectionstyle='arc3,rad=0.5',color='gray'))\n plt.show()\n\nAn example with multiple subplots::\n\n from matplotlib_venn import venn2, venn2_circles\n figure, axes = plt.subplots(2, 2)\n venn2(subsets={'10': 1, '01': 1, '11': 1}, set_labels = ('A', 'B'), ax=axes[0][0])\n venn2_circles((1, 2, 3), ax=axes[0][1])\n venn3(subsets=(1, 1, 1, 1, 1, 1, 1), set_labels = ('A', 'B', 'C'), ax=axes[1][0])\n venn3_circles({'001': 10, '100': 20, '010': 21, '110': 13, '011': 14}, ax=axes[1][1])\n plt.show()\n\nPerhaps the most common use case is generating a Venn diagram given\nthree sets of objects::\n\n set1 = set(['A', 'B', 'C', 'D'])\n set2 = set(['B', 'C', 'D', 'E'])\n set3 = set(['C', 'D',' E', 'F', 'G'])\n\n venn3([set1, set2, set3], ('Set1', 'Set2', 'Set3'))\n plt.show()\n\nTuning the diagram layout\n-------------------------\n\nNote that for a three-circle venn diagram it is not in general\npossible to achieve exact correspondence between the required set\nsizes and region areas. The default layout algorithm aims to correctly represent:\n\n * Relative areas of the full individual sets (A, B, C).\n * Relative areas of pairwise intersections of sets (A&B, A&C, B&C, not to be confused with the regions\n A&B&~C, A&~B&C, ~A&B&C, on the diagram).\n\nSometimes the result is unsatisfactory and either the area weighting or the layout logic needs\nto be tuned.\n\nThe area weighing can be adjusted by providing a `fixed_subset_sizes` argument to the `DefaultLayoutAlgorithm`::\n\n from matplotlib_venn.layout.venn2 import DefaultLayoutAlgorithm\n venn2((1,2,3), layout_algorithm=DefaultLayoutAlgorithm(fixed_subset_sizes=(1,1,1)))\n\n from matplotlib_venn.layout.venn3 import DefaultLayoutAlgorithm\n venn3((7,6,5,4,3,2,1), layout_algorithm=DefaultLayoutAlgorithm(fixed_subset_sizes=(1,1,1,1,1,1,1)))\n\nIn the above examples the diagram regions will be plotted as if `venn2((1,1,1))` and `venn3((1,1,1,1,1,1,1))` were\ninvoked, yet the actual numbers will be `(1,2,3)` and `(7,6,5,4,3,2,1)` respectively.\n\nThe diagram can be tuned further by switching the layout algorithm to a different implementation.\nAt the moment the package offers an alternative layout algorithm for `venn3` diagrams that lays the circles out by\noptimizing a user-provided *cost function*. The following examples illustrate its usage::\n\n from matplotlib_venn.layout.venn3 import cost_based\n subset_sizes = (100,200,10000,10,20,3,1)\n venn3(subset_sizes, layout_algorithm=cost_based.LayoutAlgorithm())\n\n alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.WeightedAggregateCost(transform_fn=lambda x: x))\n venn3(subset_sizes, layout_algorithm=alg)\n\n alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.WeightedAggregateCost(weights=(0,0,0,1,1,1,1)))\n venn3(subset_sizes, layout_algorithm=alg)\n\nThe default \"pairwise\" algorithm is, theoretically, a special case of the cost-based method with the respective cost function::\n\n alg = cost_based.LayoutAlgorithm(cost_fn=cost_based.pairwise_cost)\n venn3(subset_sizes, layout_algorithm=alg)\n\n(The latter plot will be close, but not perfectly equal to the outcome of `DefaultLayoutAlgorithm()`).\n\nNote that the import::\n\n from matplotlib_venn.layout.venn3 import cost_based\n\nwill fail unless you have the optional `shapely` package installed (see \"Installation\" above).\n\n\nQuestions\n---------\n\n* If you ask your questions at `StackOverflow <http://stackoverflow.com/>`_ and tag them \n `matplotlib-venn <http://stackoverflow.com/questions/tagged/matplotlib-venn>`_, chances are high you could get\n an answer from the maintainer of this package.\n\nSee also\n--------\n\n* Report issues and submit fixes at Github:\n https://github.com/konstantint/matplotlib-venn\n \n Check out the ``DEVELOPER-README.rst`` for development-related notes.\n* Some alternative means of plotting a Venn diagram (as of\n October 2012) are reviewed in the blog post:\n http://fouryears.eu/2012/10/13/venn-diagrams-in-python/\n* The `matplotlib-subsets\n <https://pypi.python.org/pypi/matplotlib-subsets>`_ package\n visualizes a hierarchy of sets as a tree of rectangles.\n* The `matplotlib_set_diagrams <https://pypi.org/project/matplotlib-set-diagrams>`_ package\n is a GPL-licensed alternative that offers a different layout algorithm, which supports more than\n three sets and provides a cool ability to incorporate wordclouds into your Venn (Euler) diagrams.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Functions for plotting area-proportional two- and three-way Venn diagrams in matplotlib.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/konstantint/matplotlib-venn"
},
"split_keywords": [
"matplotlib",
"plotting",
"charts",
"venn-diagrams"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fea76e34cd021e9b668671909f67745cc062526c22e1c3971618d93d767dce5f",
"md5": "48d563bccb0fd3930e832952347f933a",
"sha256": "d885bc015f5091a4b8a8138ff20a7ed166c33b5c36dbc0489f95a5cbc76a2ae5"
},
"downloads": -1,
"filename": "matplotlib-venn-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "48d563bccb0fd3930e832952347f933a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40280,
"upload_time": "2024-07-31T22:06:35",
"upload_time_iso_8601": "2024-07-31T22:06:35.500475Z",
"url": "https://files.pythonhosted.org/packages/fe/a7/6e34cd021e9b668671909f67745cc062526c22e1c3971618d93d767dce5f/matplotlib-venn-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 22:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "konstantint",
"github_project": "matplotlib-venn",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "matplotlib-venn"
}
JSON
