Eunoia for Python · python · 0.6.0

eunoia.euler

Source: python/eunoia/_fit.py

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.