eunoia.euler

eunoia.euler(values: Mapping[str, float] | Mapping[str, Collection[str]] | NativeDataFrame | NativeLazyFrame | NativeIbis, *, input: Literal['exclusive', 'inclusive'] = 'exclusive', shape: Literal['circle'] = 'circle', seed: int | None = None, complement: float | None = None, loss: Literal['sum_squared', 'sum_absolute', 'sum_squared_region_error', 'sum_absolute_region_error', 'max_absolute', 'max_squared', 'root_mean_squared', 'stress', 'diag_error', 'log_sum_absolute'] | None = None, optimizer: Literal['levenberg_marquardt', 'lbfgs', 'nelder_mead', 'cma_es_lm', 'trf', 'cma_es_trf'] | None = None, tolerance: float | None = None, n_restarts: int | None = None, max_iterations: int | None = None) → EulerFit[Circle][source]
eunoia.euler(values: Mapping[str, float] | Mapping[str, Collection[str]] | NativeDataFrame | NativeLazyFrame | NativeIbis, *, input: Literal['exclusive', 'inclusive'] = 'exclusive', shape: Literal['ellipse'], seed: int | None = None, complement: float | None = None, loss: Literal['sum_squared', 'sum_absolute', 'sum_squared_region_error', 'sum_absolute_region_error', 'max_absolute', 'max_squared', 'root_mean_squared', 'stress', 'diag_error', 'log_sum_absolute'] | None = None, optimizer: Literal['levenberg_marquardt', 'lbfgs', 'nelder_mead', 'cma_es_lm', 'trf', 'cma_es_trf'] | None = None, tolerance: float | None = None, n_restarts: int | None = None, max_iterations: int | None = None) → EulerFit[Ellipse]
eunoia.euler(values: Mapping[str, float] | Mapping[str, Collection[str]] | NativeDataFrame | NativeLazyFrame | NativeIbis, *, input: Literal['exclusive', 'inclusive'] = 'exclusive', shape: Literal['square'], seed: int | None = None, complement: float | None = None, loss: Literal['sum_squared', 'sum_absolute', 'sum_squared_region_error', 'sum_absolute_region_error', 'max_absolute', 'max_squared', 'root_mean_squared', 'stress', 'diag_error', 'log_sum_absolute'] | None = None, optimizer: Literal['levenberg_marquardt', 'lbfgs', 'nelder_mead', 'cma_es_lm', 'trf', 'cma_es_trf'] | None = None, tolerance: float | None = None, n_restarts: int | None = None, max_iterations: int | None = None) → EulerFit[Square]
eunoia.euler(values: Mapping[str, float] | Mapping[str, Collection[str]] | NativeDataFrame | NativeLazyFrame | NativeIbis, *, input: Literal['exclusive', 'inclusive'] = 'exclusive', shape: Literal['rectangle'], seed: int | None = None, complement: float | None = None, loss: Literal['sum_squared', 'sum_absolute', 'sum_squared_region_error', 'sum_absolute_region_error', 'max_absolute', 'max_squared', 'root_mean_squared', 'stress', 'diag_error', 'log_sum_absolute'] | None = None, optimizer: Literal['levenberg_marquardt', 'lbfgs', 'nelder_mead', 'cma_es_lm', 'trf', 'cma_es_trf'] | None = None, tolerance: float | None = None, n_restarts: int | None = None, max_iterations: int | None = None) → EulerFit[Rectangle]

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, … — 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.

    For the latter two, 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.

  • shape – "circle" (default), "ellipse", "square" or "rectangle".

  • seed – Optional seed for the optimizer’s RNG (for reproducibility).

  • complement – Area outside every named set (the universe / “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_lm", "trf". 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).

Returns:

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

Return type:

EulerFit