Eunoia

eunoia.euler

Python · python · 0.6.0

euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["circle"] = ...,
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Circle]
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["ellipse"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Ellipse]
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["square"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Square]
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["rectangle"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Rectangle]
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["rotated_rectangle"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.RotatedRectangle]

Fit an area-proportional Euler diagram.

Parameters

values:

One of three forms:

  • a mapping from set-combination labels (e.g. "A", "A&B") to their areas;

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

  • a DataFrame (pandas, polars, or anything narwhals supports) treated as a membership matrix: each column is a set, each row an observation, and a truthy cell denotes membership. Columns must be boolean or 0/1 numeric.

  • a numpy boolean array used as a membership matrix (the matrix idiom from eulerr): a 2-D (n_observations, n_sets) array, or a 1-D array read as a single set. Values must be boolean or 0/1 numeric; NaN cells count as non-members. Set names come from names or are generated ("A", "B", …).

For the membership-list, DataFrame, and array forms, each element/row is counted into the canonical region of the sets it belongs to, yielding exclusive per-region counts (so input must stay "exclusive").

input:

"exclusive" (default): values are per-region areas, with no overlap from other sets included. "inclusive": values are total set sizes that include overlaps; the eunoia core converts internally.

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, so the fit retains who is in each region (surfaced as members and drawable with plot(members=True)). Only valid for array and DataFrame input: pass a sequence with one entry per row (array or DataFrame), or, for a DataFrame, the name of a column to read the identifiers from and exclude from the sets. Membership-list input carries its members intrinsically (no ids needed); passing ids with any other form raises.

shape:

"circle" (default), "ellipse", "square", "rectangle", or "rotated_rectangle".

seed:

Optional seed for the optimizer's RNG (for reproducibility).

complement:

Area outside every named set (the universe or "complement"). When given, the core jointly fits a container box and the result carries a container. Requires every set to overlap into one cluster.

loss:

The objective the optimizer minimizes. None (default) uses the core default, "sum_squared" (normalized sum of squared region residuals). Other options trade off how error is distributed across regions, e.g. "sum_absolute", "stress" (venneuler-style), "diag_error" (eulerAPE worst-region), the region-error variants, and the max-error variants. See Loss.

optimizer:

The final-stage optimizer the core uses. None (default) keeps the core default, "cma_es_trf" (CMA-ES global escape with a bounded trust-region-reflective polish). Other options trade robustness for speed: "levenberg_marquardt", "lbfgs", "nelder_mead", "cma_es", "cma_es_lm", "trf", "mads" (a derivative-free mesh-adaptive direct search). See Optimizer.

tolerance:

Cost-change convergence tolerance for the final-stage optimizer. None keeps the core default (1e-3); smaller values fit more tightly at the cost of more iterations.

n_restarts:

Number of full-pipeline restarts (fresh initialization + optimization), keeping the lowest-loss result. None keeps the core default (10). Higher values better approach the global optimum but cost proportionally more; 1 disables restarts.

max_iterations:

Maximum optimizer iterations per fit. None keeps the core default (200).

n_threads:

Number of threads used to run the n_restarts restarts in parallel. None (default) uses all available logical cores; a positive integer caps the thread pool, and 1 runs serially. This does not affect the result of a seeded fit (the lowest-loss restart is selected regardless of completion order), only how fast it is computed. The default pool also honors the RAYON_NUM_THREADS environment variable.

Returns

EulerFit

A fit result with shapes, original/fitted values, residuals, region error, diag_error, stress, and loss.