% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/emmip.R
\name{emmip}
\alias{emmip}
\alias{emmip.default}
\alias{emmip_ggplot}
\alias{emmip_lattice}
\title{Interaction-style plots for estimated marginal means}
\usage{
emmip(object, formula, ...)

\method{emmip}{default}(object, formula, type, CIs = FALSE, PIs = FALSE,
  style, engine = get_emm_option("graphics.engine"), plotit = TRUE,
  nesting.order = FALSE, ...)

emmip_ggplot(emms, style = "factor", dodge = 0.2, xlab = labs$xlab,
  ylab = labs$ylab, tlab = labs$tlab, facetlab = "label_both", scale,
  dotarg = list(shape = "circle"), linearg = list(linetype = "solid"),
  CIarg = list(alpha = 0.4), PIarg = list(alpha = 0.25), col = NULL, ...)

emmip_lattice(emms, style = "factor", xlab = labs$xlab, ylab = labs$ylab,
  tlab = labs$tlab, pch = c(1, 2, 6, 7, 9, 10, 15:20), lty = 1,
  col = NULL, ...)
}
\arguments{
\item{object}{An object of class \code{emmGrid}, or a fitted model of a class
supported by the \pkg{emmeans} package}

\item{formula}{Formula of the form 
\code{trace.factors ~ x.factors | by.factors}. The EMMs are
plotted against \code{x.factor} for each level of \code{trace.factors}.
\code{by.factors} is optional, but if present, it determines separate
panels. Each element of this formula may be a single factor in the model,
or a combination of factors using the \code{*} operator.}

\item{...}{Additional arguments passed to \code{\link{emmeans}} (when
\code{object} is not already an \code{emmGrid} object),
\code{predict.emmGrid}, 
\code{emmip_ggplot}, or \code{emmip_lattice}.}

\item{type}{As in \code{\link{predict.emmGrid}}, this determines
whether we want to inverse-transform the predictions
(\code{type = "response"}) or not (any other choice). The default is
\code{"link"}, unless the \code{"predict.type"} option is in force; see
\code{\link{emm_options}}.
In addition, the user may specify \code{type = "scale"} to create a
transformed scale for the vertical axis based on \code{object}'s response 
transformation or link function.}

\item{CIs}{Logical value. If \code{TRUE}, confidence intervals (or HPD intervals
for Bayesian models) are added to the plot 
(works only with \code{engine = "ggplot"}).}

\item{PIs}{Logical value. If \code{TRUE}, prediction intervals are added to the plot 
(works only with \code{engine = "ggplot"}). This is allowed only if the
underlying model family is \code{"gaussian"}.
If both \code{CIs} and
\code{PIs} are \code{TRUE}, the prediction intervals will be somewhat
longer, lighter, and thinner than the confidence intervals. Additional
parameters to \code{\link{predict.emmGrid}} (e.g., \code{sigma}) may be passed via
\code{...}. For Bayesian models, PIs require \code{frequentist = TRUE} and 
a value for \code{sigma}.}

\item{style}{Optional character value. This has an effect only when the
horizontal variable is a single numeric variable. If \code{style} is
unspecified or \code{"numeric"}, the horizontal scale will be numeric and
curves are plotted using lines (and no symbols). With \code{style =
"factor"}, the horizontal variable is treated as the levels of a factor
(equally spaced along the horizontal scale), and curves are plotted using
lines and symbols. When the horizontal variable is character or factor, or
a combination of more than one predictor, \code{"factor"} style is always used.}

\item{engine}{Character value matching \code{"ggplot"} (default), 
\code{"lattice"}, or \code{"none"}. The graphics engine to be used to produce the plot.
These require, respectively, the \pkg{ggplot2} or \pkg{lattice} package to
be installed. Specifying \code{"none"} is equivalent to setting \code{plotit = FALSE}.}

\item{plotit}{Logical value. If \code{TRUE}, a graphical object is returned;
if \code{FALSE}, a data.frame is returned containing all the values
used to construct the plot.}

\item{nesting.order}{Logical value. If \code{TRUE}, factors that are nested
are presented in order according to their nesting factors, even if those nesting
factors are not present in \code{formula}. If \code{FALSE}, only the
variables in \code{formula} are used to order the variables.}

\item{emms}{A \code{data.frame} created by calling \code{emmip} with
\code{plotit = FALSE}. Certain variables and attributes are expected
to exist in this data frame; see the section detailing the rendering functions.}

\item{dodge}{Numerical amount passed to \code{ggplot2::position_dodge} 
by which points and intervals are offset so they do not collide.}

\item{xlab, ylab, tlab}{Character labels for the horizontal axis, vertical
axis, and traces (the different curves), respectively. The \code{emmip}
function generates these automatically and provides therm via the \code{labs} 
attribute, but the user may override these if desired.}

\item{facetlab}{Labeller for facets (when by variables are in play). Use
\code{"label_value"} to show just the factor levels, or \code{"label_both"}
to show both the factor names and factor levels; \code{"label_context"}
decides which based on how many \code{by} factors there are. See the
documentation for \code{ggplot2::labellers}.}

\item{scale}{If not missing, an object of class \code{scales::trans} specifying
a (usually) nonlinear scaling for the vertical axis. For example, 
\code{scales = scales::log_trans()} specifies a logarithmic scale. For
fine-tuning purposes, additional
arguments to \code{ggplot2::scale_y_continuous} may be included in \code{...} .}

\item{dotarg}{\code{list}
of arguments passed to \code{geom_point} to customize appearance of points.
If this includes \code{shape} and it is of length greater than 1, it is interpreted
as a shape palette instead.}

\item{linearg}{\code{list}
of arguments passed to \code{geom_line} to customize appearance of lines.
If this includes \code{linetype} and it is of length greater than 1,
it is interpreted as a linetype.}

\item{CIarg, PIarg}{\code{list}s
of arguments passed to \code{geom_linerange} to customize appearance of intervals.
(Note: the \code{linetype} aesthetic defaults to \code{"solid"} under the hood)}

\item{col}{With \code{emmip_ggplot}, this adds \code{color = col} (not
\code{colour}) to all of the \code{*arg} lists. This is intended for setting a
common color for everything, such as a black-and-white plot. 
With \code{emmip_lattice}, \code{col} specifies the colors to use
for each group, recycled as needed. If not specified, the default trellis
colors are used.}

\item{pch}{(Lattice only) The plotting characters to use for each group (i.e., levels of
\code{trace.factors}). They are recycled as needed.}

\item{lty}{(Lattice only) The line types to use for each group. Recycled as needed.}
}
\value{
If \code{plotit = FALSE}, a \code{data.frame} (actually, a
  \code{summary_emm} object) with the table of EMMs that would be plotted.
  The variables plotted are named \code{xvar} and \code{yvar}, and the trace
  factor is named \code{tvar}. This data frame has an added \code{"labs"}
  attribute containing the labels \code{xlab}, \code{ylab}, and \code{tlab}
  for these respective variables. The confidence limits are also
  included, renamed \code{LCL} and \code{UCL}.

If \code{plotit = TRUE}, the function
  returns an object of class \code{"ggplot"} or a \code{"trellis"}, depending
  on \code{engine}.
}
\description{
Creates an interaction plot of EMMs based on a fitted model and a simple
formula specification.
}
\note{
Conceptually, this function is equivalent to 
  \code{\link{interaction.plot}} where the summarization function is thought 
  to return the EMMs.
}
\section{Details}{

If \code{object} is a fitted model, \code{\link{emmeans}} is called with an
appropriate specification to obtain estimated marginal means for each
combination of the factors present in \code{formula} (in addition, any 
arguments in \code{\dots} that match \code{at}, \code{trend}, 
\code{cov.reduce}, or \code{fac.reduce} are passed to \code{emmeans}). 
Otherwise, if \code{object} is an \code{emmGrid} object, its first element is 
used, and it must contain one estimate for each combination of the factors
present in \code{formula}.
}

\section{Rendering functions}{

The functions \code{emmip_ggplot} and \code{emmip_lattice}
are called when \code{plotit == TRUE} to render the plots; 
but they may also be called later on an object saved via \code{plotit = FALSE}
(or \code{engine = "none"}). The functions require that \code{emms} contains variables
\code{xvar}, \code{yvar}, and \code{tvar}, and attributes \code{"labs"} and \code{"vars"}.
Confidence intervals are plotted if variables \code{LCL} and \code{UCL} exist;
and prediction intervals are plotted if \code{LPL} and \code{UPL} exist.
Finally, it must contain the variables named in \code{attr(emms, "vars")}.

In \code{emmip_ggplot}, colors, linetypes, and shapes are all assigned to
groups (according to \code{tvar}) unless overridden. So, for example, one may 
have different symbols for each group by simply specifying \code{dotarg = list()}.
}

\examples{
#--- Three-factor example
noise.lm = lm(noise ~ size * type * side, data = auto.noise)

# Separate interaction plots of size by type, for each side
emmip(noise.lm, type ~ size | side)

# One interaction plot, using combinations of size and side as the x factor
# ... with added confidence intervals and some formatting changes
emmip(noise.lm, type ~ side * size, CIs = TRUE,
    CIarg = list(linewidth = 1.5, alpha = 1, color = "orange"),
    dotarg = list(size = 2, shape = "square", color = "black"))
    
# Same using legacy theme
with_emm_options(gg.theme = 1,
    emmip(noise.lm, type ~ side * size, CIs = TRUE,
        CIarg = list(linewidth = 1.5, alpha = 1, color = "orange"),
        dotarg = list(size = 2, shape = "square", color = "black")))

# Create a black-and-white version of above with different linetypes
# (Let the linetypes and symbols default to the palette)
emmip(noise.lm, type ~ side * size, CIs = TRUE, col = "black",
      linearg = list(), dotarg = list(size = 4), CIarg = list(alpha = 1)) +
    ggplot2::theme_bw()

# One interaction plot using combinations of type and side as the trace factor
emmip(noise.lm, type * side ~ size)

# Individual traces in panels
emmip(noise.lm, ~ size | type * side)

# Example for the 'style' argument
fib.lm = lm(strength ~ machine * sqrt(diameter), data = fiber)
fib.rg = ref_grid(fib.lm, at = list(diameter = c(12, 14, 15, 25, 36)))
emmip(fib.rg, machine ~ diameter)   # curves (because diameter is numeric)
emmip(fib.rg, machine ~ diameter, style = "factor")  # points and lines

# For an example using extra ggplot2 code, see 'vignette("messy-data")',
# in the section on nested models.

### Options with transformations or link functions
neuralgia.glm <- glm(Pain ~ Treatment * Sex + Age, family = binomial(), 
                     data = neuralgia) 

# On link scale:
emmip(neuralgia.glm, Treatment ~ Sex)

# On response scale:
emmip(neuralgia.glm, Treatment ~ Sex, type = "response")

# With transformed axis scale and custom scale divisions
emmip(neuralgia.glm, Treatment ~ Sex, type = "scale",
    breaks = seq(0.10, 0.90, by = 0.10))
}
\seealso{
\code{\link{emmeans}}, \code{\link{interaction.plot}}.
}
