<a id="Eunoia.euler"></a>

<a id="Eunoia.euler-Tuple{AbstractDict}"></a>

# Eunoia.euler

Julia · 1.0.1

[Source](<https://github.com/jolars/Eunoia.jl/blob/db1275ffc768591b8c9271c56d8dfa2f3351bfcd/src/Eunoia.jl>)

```julia
euler(
    values::AbstractDict;
    shape::AbstractString = "circle",
    input_type::AbstractString = "exclusive",
    complement::Union{Nothing, Real} = nothing,
    seed::Union{Nothing, Integer} = nothing,
    max_sets::Union{Nothing, Integer} = nothing,
    loss::Union{Nothing, AbstractString} = nothing,
    loss_eps::Union{Nothing, Real} = nothing,
    n_restarts::Union{Nothing, Integer} = nothing,
    optimizer::Union{Nothing, AbstractString} = nothing,
    mds_solver::Union{Nothing, AbstractString} = nothing,
    initial_sampler::Union{Nothing, AbstractString} = nothing,
    cmaes_fallback_threshold::Union{Nothing, Real} = nothing,
    max_iterations::Union{Nothing, Integer} = nothing,
    tolerance::Union{Nothing, Real} = nothing,
    xtol::Union{Nothing, Real} = nothing,
    ftol::Union{Nothing, Real} = nothing,
    gtol::Union{Nothing, Real} = nothing,
    jobs::Union{Nothing, Integer} = nothing,
    n_vertices::Union{Nothing, Integer} = nothing,
    label_precision::Union{Nothing, Real} = nothing,
    sliver_threshold::Union{Nothing, Real} = nothing
)
```

<a id="methods"></a>

## Methods

<a id="method-47eb4e091fa71038114de66dafb86469eb229be71264881e2eabd8d299f06d30"></a>

### `euler(
    values::AbstractDict;
    shape::AbstractString = "circle",
    input_type::AbstractString = "exclusive",
    complement::Union{Nothing, Real} = nothing,
    seed::Union{Nothing, Integer} = nothing,
    max_sets::Union{Nothing, Integer} = nothing,
    loss::Union{Nothing, AbstractString} = nothing,
    loss_eps::Union{Nothing, Real} = nothing,
    n_restarts::Union{Nothing, Integer} = nothing,
    optimizer::Union{Nothing, AbstractString} = nothing,
    mds_solver::Union{Nothing, AbstractString} = nothing,
    initial_sampler::Union{Nothing, AbstractString} = nothing,
    cmaes_fallback_threshold::Union{Nothing, Real} = nothing,
    max_iterations::Union{Nothing, Integer} = nothing,
    tolerance::Union{Nothing, Real} = nothing,
    xtol::Union{Nothing, Real} = nothing,
    ftol::Union{Nothing, Real} = nothing,
    gtol::Union{Nothing, Real} = nothing,
    jobs::Union{Nothing, Integer} = nothing,
    n_vertices::Union{Nothing, Integer} = nothing,
    label_precision::Union{Nothing, Real} = nothing,
    sliver_threshold::Union{Nothing, Real} = nothing
)`

[Source](<https://github.com/jolars/Eunoia.jl/blob/db1275ffc768591b8c9271c56d8dfa2f3351bfcd/src/Eunoia.jl>)

```julia
euler(values; shape="circle", input_type="exclusive",
      complement=nothing, seed=nothing, loss=nothing, …)
```

Fit an area-proportional Euler diagram. `values` is one of: 

- a mapping from combination strings to areas, where a key is a single set (`"A"`) or an `&`-joined intersection (`"A&B"`):
  
  ```julia
  euler(Dict("A" => 5, "B" => 3, "A&B" => 1.5))
  ```
- a mapping from set names to **membership collections** (vector/set/tuple); each element is counted into the canonical region of the sets it belongs to, yielding exclusive per-region counts (so `input_type` must stay `"exclusive"`):
  
  ```julia
  euler(Dict("A" => ["x", "y"], "B" => ["y", "z"]))
  ```

Keyword arguments: 

- `shape`: `"circle"` (default), `"ellipse"`, `"square"`, `"rectangle"`, or `"rotated_rectangle"`.
- `input_type`: `"exclusive"` (default; per-region areas) or `"inclusive"` (set sizes that include overlaps; the core converts internally and the reported `fitted_values`/`residuals` are reconstructed in the inclusive scale).
- `complement`: target "universe" area outside every set (opts into container fitting); `nothing` to disable.
- `seed`: RNG seed for reproducible restarts; `nothing` for default.
- `max_sets`: raise the set-count ceiling above the core default (`32`); clamped core-side to the hard cap (`63`). `nothing` keeps the default. Note that a fully-overlapping `n`-set diagram has `2^n - 1` regions, so large dense inputs remain intractable regardless.

Fitting knobs (all optional; `nothing` keeps the core default). Invalid string tokens are rejected by the native core and surface as an error: 

- `loss`: objective function. One of `"sum_squared"` (default), `"sum_absolute"`, `"sum_absolute_region_error"`, `"sum_squared_region_error"`, `"max_absolute"`, `"max_squared"`, `"root_mean_squared"`, `"stress"`, `"diag_error"`, `"log_sum_absolute"`, or a C¹-smooth surrogate `"smooth_sum_absolute"`, `"smooth_sum_absolute_region_error"`, `"smooth_max_absolute"`, `"smooth_max_squared"`, `"smooth_diag_error"`, `"smooth_log_sum_absolute"`.
- `loss_eps`: smoothing parameter for the six `smooth_*` losses (default `1e-3`); ignored by the non-smooth losses.
- `n_restarts`: number of randomly seeded restarts (default `10`).
- `optimizer`: final-layout solver. One of `"levenberg_marquardt"`, `"lbfgs"`, `"nelder_mead"`, `"mads"`, `"trf"`, `"cmaes"`, `"cmaes_lm"`, or `"cmaes_trf"` (default).
- `mds_solver`: initial-layout (MDS) solver, `"levenberg_marquardt"` (default) or `"lbfgs"`.
- `initial_sampler`: restart-position sampler, `"uniform"` (default) or `"latin_hypercube"`.
- `cmaes_fallback_threshold`: loss above which the `cmaes_*` optimizers fire their global escape stage (default `1e-3`).
- `max_iterations`: per-optimizer iteration cap (default `200`).
- `tolerance`: unified convergence tolerance (default `1e-3`).
- `xtol`, `ftol`, `gtol`: fine-grained Levenberg-Marquardt tolerances overriding the defaults derived from `tolerance`.
- `jobs`: thread count for the restart loop; a pure wall-time knob, the chosen layout is identical regardless of value.

Plot-tuning knobs (all optional; `nothing` keeps the core default). These shape the `plot_data` geometry used for rendering, not the fit: 

- `n_vertices`: vertices per polygonized shape/region outline (default `200`). Lower values give coarser outlines; higher values, smoother ones.
- `label_precision`: pole-of-inaccessibility search precision for label anchors, in coordinate units (default `0.01`).
- `sliver_threshold`: minimum region-piece area, as a fraction of the largest piece, below which a piece is rejected as a polygonization artifact (default `1e-3`); `0.0` disables the filter.

Returns an [`EulerFit`](<4ed69989ba26556a9f6f1924004c8ef9d3a879be2533c31ba480a63a0d640b42>) carrying the fitted `shapes`, the `original_values`/`fitted_values`/`residuals` per region, the per-region `region_error`, the scalar fit metrics, and—if a `complement` was given—a `container`.