%\VignetteIndexEntry{Introducing eulerr}
%\VignetteEngine{knitr::knitr}

\PassOptionsToPackage{usenames,fixpdftex,dvipsnames,svgnames,x11names}{xcolor}
\PassOptionsToPackage{hyphens}{url}
\PassOptionsToPackage{font=small,labelfont=bf,labelsep=period}{caption}

\documentclass[
  numbers=noendperiod,
  bibliography=totoc
]{scrartcl}

% Page layout
\usepackage[
  a4paper,
  left=23mm,
  top=27.4mm,
  bottom=27.4mm,
  textwidth=107mm,
  marginparsep=8mm,
  marginparwidth=49mm,
]{geometry}
\usepackage{multicol}

% Margin paragraph
\usepackage{sidenotes}
\usepackage{marginfix}

% Headers and footers
\usepackage[
  automark,
  headsepline=false,
  headwidth=textwithmarginpar,
  footwidth=head
]{scrlayer-scrpage}

\clearpairofpagestyles
\rofoot[\pagemark]{\pagemark}
\lohead{\headmark}

% Title page
\title{Introducing eulerr}
\author{Johan larsson}
\date{\today}

\usepackage{titling}
\setlength{\droptitle}{-5em}
\pretitle{\begin{flushleft}\LARGE\bfseries}
\posttitle{\end{flushleft}}
\preauthor{\begin{flushleft}\Large}
\postauthor{\end{flushleft}}
\predate{\begin{flushleft}\large\itshape}
\postdate{\end{flushleft}}

% Graphics
\usepackage[font=footnotesize]{subcaption}
\usepackage{graphicx}
\setkeys{Gin}{width=\linewidth,totalheight=\textheight,keepaspectratio}
\graphicspath{{graphics/}}

\usepackage{booktabs}

% Text justification and parskip
%\usepackage[document]{ragged2e}

% Lists
\usepackage[shortlabels]{enumitem}

% Algorithms
\usepackage[vlined]{algorithm2e}

% Bibliography
\usepackage[square,numbers,sort&compress]{natbib}

% Floats
\DeclareCaptionType[fileext=alg,name=Algorithm]{alg}

% Extended verbatim environments
\usepackage{fancyvrb}
\fvset{fontsize=\small}% default font size for fancy-verbatim environments

% Provide fullwidth environment
\newlength{\overhang}
\setlength{\overhang}{\marginparwidth}
\addtolength{\overhang}{\marginparsep}
\makeatother

\newenvironment{fullwidth}{
  \begin{addmargin*}[0em]{-\overhang}
  }{
  \end{addmargin*}
}

% Fonts
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[lining]{libertine}
\usepackage{textcomp}
\usepackage[varqu,varl,scaled=0.93]{inconsolata}
\usepackage{mathtools}
\usepackage{amsthm}
\usepackage[libertine,vvarbb,libaltvw,liby]{newtxmath}
\usepackage[scr=rsfso]{mathalfa}
\usepackage{bm}
\useosf
\usepackage{microtype}

\newcommand{\proglang}[1]{\textsf{#1}}
\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
\newcommand{\code}[1]{\texttt{#1}}

% Custom operators
\DeclareMathOperator{\E}{E}
\DeclareMathOperator{\Pois}{Pois}
\DeclareMathOperator{\B}{Bin}
\DeclareMathOperator{\V}{Var}
\DeclareMathOperator{\Exp}{Exp}

% Caption styles (caption package is loaded with sidenotes)
\DeclareCaptionStyle{sidecaption}{labelfont=bf,labelsep=period,font=small}
\DeclareCaptionStyle{marginfigure}{labelfont=bf,labelsep=period,font=small}
\DeclareCaptionStyle{margintable}{labelfont=bf,labelsep=period,font=small}
\DeclareCaptionStyle{widefigure}{labelfont=bf,labelsep=period,font=small}
\DeclareCaptionStyle{widetable}{labelfont=bf,labelsep=period,font=small}

% Cross-referencing and colors
\usepackage{hyperref}
\usepackage[noabbrev,capitalize,nameinlink]{cleveref}
\usepackage{xcolor}
\hypersetup{linkcolor=SteelBlue4,
            citecolor=SteelBlue4,
            urlcolor=SteelBlue4,
            colorlinks=true}

% Change fontsize in sidenotes
\makeatletter
\ExplSyntaxOn
\RenewDocumentCommand \sidenotetext { o o +m }
{
  \IfNoValueOrEmptyTF{#1}
    {
      \@sidenotes@placemarginal{#2}{\textsuperscript{\thesidenote}{}\small~#3}
  \refstepcounter{sidenote}
}
    {\@sidenotes@placemarginal{#2}{\textsuperscript{#1}\small~#3}}
}
\ExplSyntaxOff
\makeatother

\begin{document}

<<setup, include = FALSE>>=
knitr::knit_hooks$set(crop = knitr::hook_pdfcrop)
knitr::knit_hooks$set(document = function(x) {
  sub('\\usepackage[]{color}', '\\usepackage{xcolor}', x, fixed = TRUE)
})

knitr::opts_chunk$set(
  echo = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.width = 2.3,
  fig.height = 2.3,
  crop = TRUE,
  size = "small",
  fig.align = "center",
  dev = "pdf",
  dev.args = list(family = "sans", pointsize = 8)
)
library(lattice)
lattice.options(default.theme = list(fontsize = list(text = 8, points = 4)))

@

\maketitle

\section{Motivation}

\pkg{eulerr} generates area-proportional euler diagrams that display set
relationships (intersections, unions, and disjoints) with circles or ellipses.
\href{https://en.wikipedia.org/wiki/Euler_diagram}{Euler diagrams} are Venn
diagrams without the requirement that all set interactions be present (whether
they are empty or not). That is, depending on input, eulerr will sometimes
produce Venn diagrams but sometimes not.

R features several packages that produce Euler diagrams;
some of the more prominent ones (on CRAN) are
\begin{itemize}
\item \href{https://cran.r-project.org/package=eVenn}{eVenn},
\item \href{https://cran.r-project.org/package=VennDiagram}{VennDiagram},
\item \href{https://cran.r-project.org/package=venn}{venn},
\item \href{https://cran.r-project.org/package=colorfulVennPlot}{colorfulVennPlot}, and
\item \href{https://cran.r-project.org/package=venneuler}{venneuler}.
\end{itemize}
The last of these (\pkg{venneuler}) was the primary inspiration for this
package, along with the refinements that Fredrickson has presented on his
\href{http://www.benfrederickson.com/}{blog} and made available in his
javascript \href{https://github.com/benfred/venn.js}{venn.js}.
\href{http://www.eulerdiagrams.org/eulerAPE/}{eulerAPE}, which was the first
program to uses ellipses instead of circles, has also been instrumental in the
design of \pkg{eulerr}. The downside to \pkg{eulerAPE} is that it only handles
three sets that all need to intersect.

\emph{enneuler}, on the other hand, will take any number of sets (in theory),
yet has been known to produce
\href{http://benfred.github.io/venn.js/tests/venneuler_comparison/}{imperfect solutions}
for set configurations that have perfect such. And unlike \pkg{eulerAPE}, it is
restricted to circles (as is \pkg{venn.js}).

\section{Enter eulerr}
\pkg{eulerr} is based on the improvements to venneuler that Ben Fredrickson
introduced with \pkg{venn.js} but has been programmed from scratch, uses different
optimizers, and returns statistics featured in \pkg{venneuler} and
\pkg{eulerAPE} as well as allows a range of different inputs and conditioning on
additional variables. Moreover, it can model set relationships with ellipses for
any number of sets involed.

\subsection{Input}
At the time of writing, it is possible to provide input to \pkg{eulerr} as
either
\begin{itemize}
\item a named numeric vector with set combinations as disjoint set combinations
or unions (depending on how the argument \code{type} is set),
\item a matrix or data frame of logicals with columns representing sets and rows
the set relationships for each observation, or
\item a list of sample spaces.
\end{itemize}

<<input>>=
library(eulerr)
options(digits = 4)

# Input in the form of a named numeric vector
fit1 <- euler(c("A" = 25, "B" = 5, "C" = 5,
                "A&B" = 5, "A&C" = 5, "B&C" = 3,
                "A&B&C" = 3))

# Input as a matrix of logicals
set.seed(1)
mat <- cbind(
  A = sample(c(TRUE, TRUE, FALSE), 50, TRUE),
  B = sample(c(TRUE, FALSE), 50, TRUE),
  C = sample(c(TRUE, FALSE, FALSE, FALSE), 50, TRUE)
)
fit2 <- euler(mat)
@

\subsection{Fit}
We inspect our results by printing the eulerr object

<<>>=
fit2
@

or directly access and plot the residuals.

<<residual-plot, eval = FALSE>>=
# Cleveland dot plot of the residuals
lattice::dotplot(resid(fit2), xlab = "",
                 panel = function(...) {
                   panel.abline(v = 0, lty = 2)
                   panel.dotplot(...)
                 })
@

\begin{figure}[hbtp]
\sidecaption{Residuals for the fit diagram.\label{fig:residual-plot}}
<<residual-dev, ref.label='residual-plot', echo = FALSE, fig.width = 3.5>>=
@
\end{figure}

This shows us that the \code{A\&C} intersection is somewhat overrepresented in
\code{fit2}. Given that these residuals are on the scale of the original
values, however, the residuals are arguably of little concern.

As an alternative, we could plot the circles in another program by retrieving
their coordinates and radii.

<<coefs>>=
coef(fit2)
@

\subsection{Goodness-of-fit}
To tell if we can trust our solution, we use two goodness-of-fit measures: the
stress statistic from venneuler \cite{wilkinson_2012},
$$\frac{\sum_{i=1}^{n} (y_i - \hat{y}_i)^2}{\sum_{i=1}^{n} y_i ^ 2}$$
where $\hat{y}_i$ is an ordinary least squares estimate from the regression of
the fitted areas on the original areas that is being explored during
optimization,

and the \emph{diagError} statistic from \pkg{eulerAPE} \cite{micallef2014}:

$$\max_{i = 1, 2, \dots, n} \left| \frac{y_i}{\sum y_i} -
\frac{\hat{y}_i}{\sum \hat{y}_i} \right|$$
In our example, the diagError is \Sexpr{fit2$diag_error} and our
stress is \Sexpr{fit2$stress}, suggesting that the fit is accurate.

We can now be confident that eulerr provides a reasonable representation of
our input using circles. Were it otherwise, we might try to use ellipses
instead. \citet{wilkinson_2012} features a difficult combination that it manages
to fit with a reasonably small error; with \pkg{eulerr}, however, we can get
rid of that error entirely~(\cref{fig:wilkinson2012}).

<<>>=
wilkinson2012 <-  c(A = 4, B = 6, C = 3, D = 2, E = 7, F = 3,
                    "A&B" = 2, "A&F" = 2, "B&C" = 2, "B&D" = 1,
                    "B&F" = 2, "C&D" = 1, "D&E" = 1, "E&F" = 1,
                    "A&B&F" = 1, "B&C&D" = 1)
fit3 <- euler(wilkinson2012, shape = "ellipse")
@

\begin{figure}
\sidecaption{A difficult combination modelled with ellipses.\label{fig:wilkinson2012}}
<<wilkinson2012, echo = FALSE, fig.width = 3.4, fig.height = 2.5>>=
plot(fit3)
@
\end{figure}

If we still lack a good fit after having tried ellipses, we would do best to
stop here and look for another way to visualize our data. (I suggest the
excellent \href{https://cran.r-project.org/package=UpSetR}{UpSetR} package.)

\subsection{Visualization}
No we get to the fun part: plotting our diagram. This is easy, as well as
highly customizable, with \pkg{eulerr}. The default
parameters~(\cref{fig:eulerr-plot}) can easily be adjusted to suit anyobody's
needs~(\cref{fig:custom-plot}).

<<eulerr-plot, eval = FALSE>>=
plot(fit2)
@

\begin{marginfigure}
<<eulerr-dev, ref.label = "eulerr-plot", echo = FALSE>>=
@
\caption{The default graphical parameters.}
\label{fig:eulerr-plot}
\end{marginfigure}

<<custom-plot, eval = FALSE>>=
# Remove fills, vary border type, and switch fontface.
plot(fit2, fill = "transparent", lty = 1:3, fontface = 4)
@

\begin{marginfigure}
<<custom-plot, ref.label = "custom-plot", echo = FALSE>>=
@
\caption{Adjusted graphical parameters.}
\label{fig:custom-plot}
\end{marginfigure}

Plotting is provided through the excellent
\href{https://CRAN.R-project.org/package=lattice}{lattice} and interfaces all of
its bells and whistles to allow for extensive customization of the resulting
plots.

\pkg{eulerr}'s default color palette is taken from
\href{https://cran.r-project.org/package=qualpalr}{qualpalr}---another package
that I have developed---which uses color difference algorithms to generate
distinct qualitative color palettes.

\section{Acknowledgements}

\pkg{eulerr} would not be possible without Ben Fredrickson's work on
\pkg{venn.js} or Leland Wilkinson's \pkg{venneuler}.

\bibliography{eulerr}
\bibliographystyle{unsrtnat}

\end{document}
