Eunoia for Python · python · 0.6.0

eunoia.venn

Source: python/eunoia/_venn.py

venn(sets: VennInput, *, shape: typing.Literal["ellipse"] = ..., complement: float | None = ..., input: typing.Literal["exclusive", "inclusive"] = ..., names: Sequence[str] | None = ..., ids: str | Sequence[object] | None = ...) -> eunoia.VennFit[eunoia.Ellipse]

venn(sets: VennInput, *, shape: typing.Literal["circle"], complement: float | None = ..., input: typing.Literal["exclusive", "inclusive"] = ..., names: Sequence[str] | None = ..., ids: str | Sequence[object] | None = ...) -> eunoia.VennFit[eunoia.Circle]

venn(sets: VennInput, *, shape: typing.Literal["square"], complement: float | None = ..., input: typing.Literal["exclusive", "inclusive"] = ..., names: Sequence[str] | None = ..., ids: str | Sequence[object] | None = ...) -> eunoia.VennFit[eunoia.Square]

venn(sets: VennInput, *, shape: typing.Literal["rectangle"], complement: float | None = ..., input: typing.Literal["exclusive", "inclusive"] = ..., names: Sequence[str] | None = ..., ids: str | Sequence[object] | None = ...) -> eunoia.VennFit[eunoia.Rectangle]

venn(sets: VennInput, *, shape: typing.Literal["rotated_rectangle"], complement: float | None = ..., input: typing.Literal["exclusive", "inclusive"] = ..., names: Sequence[str] | None = ..., ids: str | Sequence[object] | None = ...) -> eunoia.VennFit[eunoia.RotatedRectangle]

Lay out a (non-proportional) Venn diagram.

Unlike euler, every set intersection is always drawn, regardless of area. The arrangement is topological: the shapes come from the eunoia core's canonical Venn layouts, not from numerical optimization.

Parameters

• sets:

  The sets to show. One of:

  • an int n: n sets with default names "A", "B", …;

  • a sequence of set names, e.g. ["cat", "dog", "fish"];

  • a mapping from set-combination labels (e.g. "A", "A&B") to per-region quantities, where the layout stays topological but the values are kept as original_values so plot() can label each region (this is the common "Venn diagram with subset sizes" case);

  • a mapping from set names to membership collections ({"A": ["x", "y"], "B": ["y", "z"]}), counted into per-region quantities;

  • a DataFrame (pandas, polars, … via narwhals) treated as a membership matrix; its column names are the sets and each row is counted into a region;

  • a numpy boolean array used as a membership matrix (2-D, or 1-D for a single set); set names come from names or are generated.

  For int and plain name-sequence input there are no quantities, so original_values is empty.

• shape:

  "ellipse" (default), "circle", "square", "rectangle", or "rotated_rectangle". Ellipses support 1--5 sets; circles, squares, and rectangles 1--3; rotated rectangles 1--4 (the 4-set layout uses rotated rectangles to open all 15 regions). An unsupported set count raises EunoiaError.

• complement:

  Optional universe area outside every set. For a Venn diagram this only adds a visual container box (the padded bounding box); it does not drive optimization.

• input:

  How to read the supplied quantities. "exclusive" (default): each value is a per-region count with no overlap included. "inclusive": values are total set sizes that include overlaps. Only meaningful for the region-area mapping form; membership-list and DataFrame input are always exclusive (passing "inclusive" raises EunoiaError).

• names:

  Set names for numpy-array input, one per column (or a single name for a 1-D array). Defaults to "A", "B", …. Only valid for array input; other forms carry their own names and passing names raises.

• ids:

  Per-observation member identifiers, retained as members and drawable with plot(members=True). Only valid for array and DataFrame input: a sequence with one entry per row, or, for a DataFrame, a column name to read identifiers from and exclude from the sets. Membership-list input carries its members intrinsically; passing ids with any other form raises.

Returns

• VennFit

  A topological fit whose plot() works like EulerFit. When quantities were supplied they are kept in original_values and shown by plot() automatically; otherwise fitted_values holds the geometric area of every region.