% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rbind.R, R/emm-list.R, R/nested.R
\name{rbind.emmGrid}
\alias{rbind.emmGrid}
\alias{+.emmGrid}
\alias{[.emmGrid}
\alias{head.emmGrid}
\alias{tail.emmGrid}
\alias{subset.emmGrid}
\alias{rbind.emm_list}
\alias{rbind.summary_emm}
\alias{force_regular}
\title{Combine or subset \code{emmGrid} objects}
\usage{
\method{rbind}{emmGrid}(..., deparse.level = 1, adjust = "bonferroni")

\method{+}{emmGrid}(e1, e2)

\method{[}{emmGrid}(x, i, adjust, drop.levels = TRUE, ...)

\method{head}{emmGrid}(x, n = 6, ...)

\method{tail}{emmGrid}(x, n = 6, ...)

\method{subset}{emmGrid}(x, subset, ...)

\method{rbind}{emm_list}(..., which, adjust = "bonferroni")

\method{rbind}{summary_emm}(..., which)

force_regular(object)
}
\arguments{
\item{...}{In \code{rbind}, object(s) of class \code{emmGrid} or \code{summary_emm}.
In others, additional arguments passed to other methods}

\item{deparse.level}{(required but not used)}

\item{adjust}{Character value passed to \code{\link{update.emmGrid}}}

\item{e1, e2, x, object}{Objects of class \code{emmGrid}}

\item{i}{Integer vector of indexes}

\item{drop.levels}{Logical value. If \code{TRUE}, the \code{"levels"} slot in
the returned object is updated to hold only the predictor levels that actually occur}

\item{n}{integer number of entries to include (or exclude if negative)}

\item{subset}{logical expression indicating which rows of the grid to keep}

\item{which}{Integer vector of subset of elements to use;
if missing, we use all elements.}
}
\value{
A revised object of class \code{emmGrid}

The result of \code{e1 + e2} is the same as \code{rbind(e1, e2)}

The \code{rbind} method for \code{emm_list} objects simply combines 
the \code{emmGrid} objects comprising the first element of \code{...}.
Note that the returned object is not yet summarized, so any \code{adjust}
parameters apply to the combined \code{emmGrid}.

The \code{rbind} method for \code{summary_emm} objects (or a list thereof)
returns a single \code{summary_emm} object. This combined object
\emph{preserves} any adjusted P values or confidence limits in the
original summaries, since those quantities have already been computed.

\code{force_regular} adds extra (invisible) rows to an \code{emmGrid} object
  to make it a regular grid (all combinations of factors). This regular structure is 
  needed by \code{emmeans}. An object can become irregular by, for example,
  subsetting rows, or by obtaining contrasts of a nested structure.
}
\description{
These functions provide methods for \code{\link[base:cbind]{rbind}} and
\code{\link[base:Extract]{[}} that may be used to combine \code{emmGrid} objects
together, or to extract a subset of cases. The primary reason for 
doing this would be to obtain multiplicity-adjusted results for smaller
or larger families of tests or confidence intervals.
}
\note{
\code{rbind} throws an error if there are incompatibilities in
  the objects' coefficients, covariance structures, etc. But they 
  are allowed to have different factors; a missing level \code{'.'}
  is added to factors as needed.

These functions generally reset \code{by.vars} to \code{NULL};
so if you want to keep any \dQuote{by} variables, you should follow-up
with \code{\link{update.emmGrid}}.
}
\examples{
warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
warp.rg <- ref_grid(warp.lm)

# Do all pairwise comparisons within rows or within columns, 
# all considered as one faily of tests:
w.t <- pairs(emmeans(warp.rg, ~ wool | tension))
t.w <- pairs(emmeans(warp.rg, ~ tension | wool))
rbind(w.t, t.w, adjust = "mvt")
update(w.t + t.w, adjust = "fdr")  ## same as above except for adjustment

# Show only 3 of the 6 cases
summary(warp.rg[c(2, 4, 5)])

# After-the-fact 'at' specification
subset(warp.rg, wool == "A")  ## or warp.rg |> subset(wool == "A")


### Working with 'emm_list' objects
mod <- lm(conc ~ source + factor(percent), data = pigs)
all <- emmeans(mod, list(src = pairwise ~ source, pct = consec ~ percent))
rbind(all, which = c(2, 4), adjust = "mvt")

### Irregular object
tmp <- warp.rg[-1]
## emmeans(tmp, "tension")   # will fail because tmp is irregular
emmeans(force_regular(tmp), "tension")   # will show some results
}
