% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/euler.R
\name{euler}
\alias{euler}
\alias{euler.default}
\alias{euler.data.frame}
\alias{euler.matrix}
\alias{euler.table}
\alias{euler.list}
\title{Area-proportional Euler diagrams}
\usage{
euler(combinations, ...)

\method{euler}{default}(
  combinations,
  input = c("disjoint", "union"),
  shape = c("circle", "ellipse", "rectangle", "square"),
  loss = c("sum_squared", "sum_absolute", "sum_absolute_region_error",
    "sum_squared_region_error", "max_absolute", "max_squared", "root_mean_squared",
    "stress", "diag_error"),
  loss_aggregator = NULL,
  complement = NULL,
  control = list(),
  ...
)

\method{euler}{data.frame}(
  combinations,
  weights = NULL,
  by = NULL,
  sep = "_",
  factor_names = TRUE,
  ...
)

\method{euler}{matrix}(combinations, ...)

\method{euler}{table}(combinations, ...)

\method{euler}{list}(combinations, ...)
}
\arguments{
\item{combinations}{set relationships as a named numeric vector, matrix, or
data.frame (see \strong{methods (by class)})}

\item{...}{arguments passed down to other methods}

\item{input}{type of input: disjoint identities
(\code{'disjoint'}) or unions (\code{'union'}).}

\item{shape}{geometric shape used in the diagram}

\item{loss}{type of loss to minimize over. The default,
\code{"sum_squared"}, minimizes the sum of squared errors. The available
options mirror the loss functions exposed by the \code{eunoia} Rust crate
that powers the optimizer:
\itemize{
\item \code{"sum_squared"} --- normalized sum of squared errors (default).
\item \code{"sum_absolute"} --- normalized sum of absolute errors.
\item \code{"sum_absolute_region_error"} --- normalized sum of absolute
region errors.
\item \code{"sum_squared_region_error"} --- normalized sum of squared region
errors.
\item \code{"max_absolute"} --- normalized maximum absolute error.
\item \code{"max_squared"} --- normalized maximum squared error.
\item \code{"root_mean_squared"} --- normalized root-mean-squared error.
\item \code{"stress"} --- venneuler-style stress.
\item \code{"diag_error"} --- eulerAPE-style \code{diagError}.
}}

\item{loss_aggregator}{deprecated; use \code{loss} directly instead. Pre-1.0
code that combined \code{loss} (\code{"square"}/\code{"abs"}/\code{"region"}) with
\code{loss_aggregator} (\code{"sum"}/\code{"max"}) still works but emits a warning;
the combination is mapped to the equivalent new \code{loss} value.}

\item{complement}{an optional single non-negative number giving the area
of the \emph{complement} — that is, the universe outside every named set.
When supplied, the fitter jointly optimizes a containing rectangle
together with the diagram shapes so that the area of the rectangle
minus the union of (clipped) shapes matches \code{complement}. This is the
classical "everything not in any set" region; see \code{\link[=plot.euler]{plot.euler()}} for
how it is rendered. Defaults to \code{NULL} (no container; classical
shape-only fit). Not supported for \code{\link[=venn]{venn()}}.}

\item{control}{a list of control parameters.
\itemize{
\item \code{extraopt}: should the global-search fallback optimizer (CMA-ES) kick
in when the primary optimizer's \code{diagError} exceeds \code{extraopt_threshold}?
The default is \code{TRUE} for three-set ellipse fits and \code{FALSE} otherwise.
\item \code{extraopt_threshold}: threshold, in terms of \code{diagError}, for when
the CMA-ES fallback kicks in. A value of 0 means it will kick in for
\emph{any} error; a value of 1 means it will never kick in. Default \code{0.001}.
\item \code{tolerance}: convergence tolerance passed to the underlying solver.
Tighter values give more accurate fits at higher cost. Default \code{1e-8}.
\item \code{max_sets}: maximum number of sets the underlying engine will accept.
Defaults to \code{NULL}, which uses the engine's built-in default of 32.
Region masks are stored in a bitset, so values may be raised up to 63
(the absolute hard cap). Going higher is rarely useful in practice
since fully-overlapping diagrams have \code{2^n - 1} regions.
}}

\item{weights}{a numeric vector of weights of the same length as
the number of rows in \code{combinations}.}

\item{by}{a factor or character matrix to be used in \code{\link[base:by]{base::by()}} to
split the data.frame or matrix of set combinations}

\item{sep}{a character to use to separate the dummy-coded factors
if there are factor or character vectors in 'combinations'.}

\item{factor_names}{whether to include factor names when
constructing dummy codes}
}
\value{
A list object of class \code{'euler'} with the following parameters.
\item{shapes}{a data frame of fitted shape parameters. One row per set
with a \code{type} column (one of \code{"circle"}, \code{"ellipse"}, \code{"rectangle"},
\code{"square"}), the center coordinates \code{h} and \code{k}, and the
shape-specific columns: \code{a}, \code{b}, \code{phi} for ellipses/circles; \code{width}
and \code{height} for rectangles; \code{side} (plus mirrored \code{width}/\code{height})
for squares. Columns that don't apply to the chosen shape are \code{NA}.}
\item{ellipses}{for \code{shape = "circle"} and \code{shape = "ellipse"} fits,
the legacy 5-column data frame of \code{h}, \code{k}, \code{a}, \code{b}, \code{phi}. This
slot is deprecated in favour of \code{shapes} and is not populated for
rectangle/square fits.}
\item{original.values}{set relationships in the input}
\item{fitted.values}{set relationships in the solution}
\item{residuals}{residuals}
\item{regionError}{the difference in percentage points between each
disjoint subset in the input and the respective area in the output}
\item{diagError}{the largest \code{regionError}}
\item{stress}{normalized residual sums of squares}
}
\description{
Fit Euler diagrams (a generalization of Venn diagrams) using numerical
optimization to find exact or approximate solutions to a specification of set
relationships. The shape of the diagram may be a circle, an ellipse, an
axis-aligned rectangle, or an axis-aligned square.
}
\details{
If the input is a matrix or data frame and argument \code{by} is specified,
the function returns a list of euler diagrams.

The function minimizes the residual sums of squares,
\deqn{
  \sum_{i=1}^n (A_i - \omega_i)^2,
}{
  \sum (A_i - \omega_i)^2,
}
by default, where \eqn{\omega_i} the size of the ith disjoint subset, and
\eqn{A_i} the corresponding area in the diagram, that is, the unique
contribution to the total area from this overlap. The loss function
can, however, be controlled via the \code{loss} argument.

\code{\link[=euler]{euler()}} also returns \code{stress} (from \pkg{venneuler}), as well as
\code{diagError}, and \code{regionError} from \pkg{eulerAPE}.

The \emph{stress} statistic is computed as

\deqn{
  \frac{\sum_{i=1}^n (A_i - \beta\omega_i)^2}{\sum_{i=1}^n A_i^2},
}{
  \sum (A_i - \beta\omega_i)^2 / \sum A_i^2,
}
where
\deqn{
  \beta = \sum_{i=1}^n A_i\omega_i / \sum_{i=1}^n \omega_i^2.
}{
  \beta = \sum A_i\omega_i / \sum \omega_i^2.
}

\code{regionError} is computed as

\deqn{
  \left| \frac{A_i}{\sum_{i=1}^n A_i} - \frac{\omega_i}{\sum_{i=1}^n \omega_i}\right|.
}{
  max|A_i / \sum A  - \omega_i / \sum \omega|.
}

\code{diagError} is simply the maximum of regionError.
}
\section{Methods (by class)}{
\itemize{
\item \code{euler(default)}: a named numeric vector, with
combinations separated by an ampersand, for instance \code{A&B = 10}.
Missing combinations are treated as being 0.

\item \code{euler(data.frame)}: a \code{data.frame} of logicals, binary integers, or
factors.

\item \code{euler(matrix)}: a matrix that can be converted to a data.frame of logicals
(as in the description above) via \code{\link[base:as.data.frame]{base::as.data.frame.matrix()}}.

\item \code{euler(table)}: A table with \code{max(dim(x)) < 3}.

\item \code{euler(list)}: a list of vectors, each vector giving the contents of
that set (with no duplicates). Vectors in the list must be named.

}}
\examples{
# Fit a diagram with circles
combo <- c(A = 2, B = 2, C = 2, "A&B" = 1, "A&C" = 1, "B&C" = 1)
fit1 <- euler(combo)

# Investigate the fit
fit1

# Refit using ellipses instead
fit2 <- euler(combo, shape = "ellipse")

# Investigate the fit again (which is now exact)
fit2

# Plot it
plot(fit2)

# A set with no perfect solution
euler(c(
  "a" = 3491, "b" = 3409, "c" = 3503,
  "a&b" = 120, "a&c" = 114, "b&c" = 132,
  "a&b&c" = 50
))


# Using grouping via the 'by' argument through the data.frame method
euler(fruits, by = list(sex, age))


# Using the matrix method
euler(organisms)

# Using weights
euler(organisms, weights = c(10, 20, 5, 4, 8, 9, 2))

# The table method
euler(pain, factor_names = FALSE)

# A euler diagram from a list of sample spaces (the list method)
euler(plants[c("erigenia", "solanum", "cynodon")])
}
\references{
Wilkinson L. Exact and Approximate Area-Proportional Circular
Venn and Euler Diagrams. IEEE Transactions on Visualization and Computer
Graphics (Internet). 2012 Feb (cited 2016 Apr 9);18(2):321-31. Available
from: \doi{10.1109/TVCG.2011.56}

Micallef L, Rodgers P. eulerAPE: Drawing Area-Proportional 3-Venn Diagrams
Using Ellipses. PLOS ONE (Internet). 2014 Jul (cited 2016 Dec
10);9(7):e101717. Available from:
\doi{10.1371/journal.pone.0101717}
}
\seealso{
\code{\link[=plot.euler]{plot.euler()}}, \code{\link[=print.euler]{print.euler()}}, \code{\link[=eulerr_options]{eulerr_options()}}, \code{\link[=venn]{venn()}}
}
