EulerDiagram

EulerDiagram(subset_sizes, int | float], ...)

Create an area-proportional Euler diagram visualising the relationships between two or more sets given the subset sizes.

EulerDiagram.from_sets(sets, *args, **kwargs)

Instantiate the set diagram from a list of sets, rather than subset sizes.

EulerDiagram.as_wordcloud(sets[, ...])

Generate a set diagram with word clouds displaying the subset items.
class matplotlib_set_diagrams.EulerDiagram(subset_sizes: ~typing.Mapping[~typing.Tuple[bool], int | float], subset_labels: ~typing.Mapping[~typing.Tuple[bool], str] | None = None, subset_label_formatter: ~typing.Callable[[~typing.Tuple[bool], int | float], str] = <function EulerDiagram.<lambda>>, set_labels: list[str] | None = None, set_colors: list[tuple[float, float, float] | str | tuple[float, float, float, float] | tuple[tuple[float, float, float] | str, float] | tuple[tuple[float, float, float, float], float]] | None = None, cost_function_objective: str = 'inverse', verbose: bool = False, ax: ~matplotlib.axes._axes.Axes | None = None)[source]

Create an area-proportional Euler diagram visualising the relationships between two or more sets given the subset sizes.

Sets are represented through overlapping circles, and the relative arrangement of these circles is determined through a minimisation procedure that attempts to match subset sizes to the corresponding areas formed by circle overlaps in the diagram.

Parameters:
subset_sizesMapping[Tuple[bool], int | float]

A dictionary mapping each subset to its desired size. Subsets are represented by tuples of booleans using the inclusion/exclusion nomenclature, i.e. each entry in the tuple indicates if the corresponding set is a superset of the subset. For example, given the sets A, B, C, the subset (1, 1, 1) corresponds to the intersection of all three sets, whereas (1, 1, 0) is the subset formed by the difference between the intersection of A with B, and C.

subset_labelsOptional[Mapping[Tuple[bool], str]]

A dictionary mapping each subset to its desired label or None. If None, the subset_label_formatter is used create subset labels based on the subset sizes.

subset_label_formatterCallable[[Tuple[bool], int | float], str]

The formatter used to create subset labels based on the subset sizes. The argument is ignored if subset_labels are not None.

set_labelsOptional[list[str]]

A list of set labels. If none, defaults to the letters of the alphabet (capitalized).

set_colorsOptional[list[ColorType]]

A corresponding list of matplotlib colors. If none, defaults to the default matplotlib color cycle.

cost_function_objectivestr

The cost function objective; one of:

  • ‘simple’ : |x - y|

  • ‘squared’ : (x - y)^2

  • ‘logarithmic’ : |log(x + 1) - log(y + 1)|

  • ‘relative’ : 1 - min(x/y, y/x)

  • ‘inverse’ : |1 / (x + epsilon) - 1 / (y + epsilon)|

verbosebool

Print a report of the optimisation process.

axOptional[plt.Axes]

The matplotlib axis instance to draw onto. If none provided, a new figure with a single axis is instantiated.

Attributes:
originsNDArray

The circle origins.

radiiNDArray

The circle radii.

subset_geometriesdict[Tuple[bool], shapely.geometry.polygon.Polygon]

The dictionary mapping each subset to its shapely geometry.

subset_artistsdict[tuple[bool], plt.Polygon]

The matplotlib Polygon patches representing each subset.

subset_label_artistsdict[tuple[bool], plt.Text]

The matplotlib text objects used to label each subset.

set_label_artistslist[plt.Text]

The matplotlib text objects used to label each set.

axplt.Axes

The matplotlib axis instance.

classmethod EulerDiagram.from_sets(sets, *args, **kwargs)[source]

Instantiate the set diagram from a list of sets, rather than subset sizes.

Parameters:
setslist[set]

The sets.

subset_labelsOptional[Mapping[Tuple[bool], str]]

A dictionary mapping each subset to its desired label or None. If None, the subset_label_formatter is used create subset labels based on the subset sizes.

subset_label_formatterCallable[[Tuple[bool], int | float], str]

The formatter used to create subset labels based on the subset sizes. The argument is ignored if subset_labels are not None.

set_labelsOptional[list[str]]

A list of set labels. If none, defaults to the letters of the alphabet (capitalized).

set_colorsOptional[list[ColorType]]

A corresponding list of matplotlib colors. If none, defaults to the default matplotlib color cycle.

cost_function_objectivestr

The cost function objective; one of:

  • ‘simple’ : |x - y|

  • ‘squared’ : (x - y)^2

  • ‘logarithmic’ : |log(x + 1) - log(y + 1)|

  • ‘relative’ : 1 - min(x/y, y/x)

  • ‘inverse’ : |1 / (x + epsilon) - 1 / (y + epsilon)|

Only applicable when instantiating an EulerDiagram.

verbosebool

Print a report of the optimisation process. Only applicable when instantiating an EulerDiagram.

axOptional[plt.Axes]

The matplotlib axis instance to draw onto. If none provided, a new figure with a single axis is instantiated.

Attributes:
originsNDArray

The circle origins.

radiiNDArray

The circle radii.

subset_geometriesdict[Tuple[bool], shapely.geometry.polygon.Polygon]

The dictionary mapping each subset to its shapely geometry.

subset_artistsdict[tuple[bool], plt.Polygon]

The matplotlib Polygon patches representing each subset.

subset_label_artistsdict[tuple[bool], plt.Text]

The matplotlib text objects used to label each subset.

set_label_artistslist[plt.Text]

The matplotlib text objects used to label each set.

axplt.Axes

The matplotlib axis instance.

classmethod EulerDiagram.as_wordcloud(sets, minimum_resolution=300, wordcloud_kwargs={}, *args, **kwargs)[source]

Generate a set diagram with word clouds displaying the subset items.

Parameters:
setslist[set]

The sets.

minimum_resolutionint

The minimum extent of the wordcloud image in pixels (i.e. min(width, height)). Larger images take significantly longer to generate.

wordcloud_kwargsdict[str, Any]

Key word arguments passed through to wordcloud.WordCloud. Consult the wordcloud documentation [1] for a complete list. However, the following arguments are reserved:

  • mode = 'RGBA'

  • background = None

  • color_func = lambda *args, **kwargs : subset_color

subset_labelsOptional[Mapping[Tuple[bool], str]]

A dictionary mapping each subset to its desired label or None. If None, the subset_label_formatter is used create subset labels based on the subset sizes.

subset_label_formatterCallable[[Tuple[bool], int | float], str]

The formatter used to create subset labels based on the subset sizes. The argument is ignored if subset_labels are not None.

set_labelsOptional[list[str]]

A list of set labels. If none, defaults to the letters of the alphabet (capitalized).

set_colorsOptional[list[ColorType]]

A corresponding list of matplotlib colors. If none, defaults to the default matplotlib color cycle.

cost_function_objectivestr

The cost function objective; one of:

  • ‘simple’ : |x - y|

  • ‘squared’ : (x - y)^2

  • ‘logarithmic’ : |log(x + 1) - log(y + 1)|

  • ‘relative’ : 1 - min(x/y, y/x)

  • ‘inverse’ : |1 / (x + epsilon) - 1 / (y + epsilon)|

Only applicable when instantiating an EulerDiagram.

verbosebool

Print a report of the optimisation process. Only applicable when instantiating an EulerDiagram.

axOptional[plt.Axes]

The matplotlib axis instance to draw onto. If none provided, a new figure with a single axis is instantiated.

Attributes:
originsNDArray

The circle origins.

radiiNDArray

The circle radii.

subset_geometriesdict[Tuple[bool], shapely.geometry.polygon.Polygon]

The dictionary mapping each subset to its shapely geometry.

subset_artistsdict[tuple[bool], plt.Polygon]

The matplotlib Polygon patches representing each subset.

subset_label_artistsdict[tuple[bool], plt.Text]

The matplotlib text objects used to label each subset.

set_label_artistslist[plt.Text]

The matplotlib text objects used to label each set.

axplt.Axes

The matplotlib axis instance.

wordcloudmatplotlib.image.AxesImage

The WordCloud image.

References