# R/S4-classes.R In emmeans: Estimated Marginal Means, aka Least-Squares Means

##############################################################################
#    Copyright (c) 2012-2017 Russell V. Lenth                                #
#                                                                            #
#    This file is part of the emmeans package for R (*emmeans*)              #
#                                                                            #
#    *emmeans* is free software: you can redistribute it and/or modify       #
#    the Free Software Foundation, either version 2 of the License, or       #
#    (at your option) any later version.                                     #
#                                                                            #
#    *emmeans* is distributed in the hope that it will be useful,            #
#    but WITHOUT ANY WARRANTY; without even the implied warranty of          #
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           #
#    GNU General Public License for more details.                            #
#                                                                            #
#    You should have received a copy of the GNU General Public License       #
#    along with R and *emmeans*.  If not, see                                #
##############################################################################

### S4 class definitions for emmeans package

### emmGrid object - For reference grids, emmeans results, etc.

#' The \code{emmGrid} class
#'
#' The \code{emmGrid} class encapsulates linear functions of regression
#' parameters, defined over a grid of predictors. This includes reference
#' grids and grids of marginal means thereof (aka estimated marginal means).
#' Objects of class emmGrid may be used independently of the underlying model
#' object. Instances are created primarily by \code{\link{ref_grid}} and
#' \code{\link{emmeans}}, and several related functions.
#'
#' @rdname emmGrid-class
#' @slot model.info list. Contains the elements \code{call} (the call that
#'   produced the model), \code{terms} (its \code{terms} object), and
#'   \code{xlev} (factor-level information)
#' @slot roles list. Contains at least the elements \code{predictors},
#'   \code{responses}, and \code{multresp}. Each is a character vector of names
#'   of these variables.
#' @slot grid data.frame. Contains the combinations of the variables that define
#'   the reference grid. In addition, there is an auxiliary column named
#'   \code{".wgt."} holding the observed frequencies or weights for each factor
#'   combination (excluding covariates). If the model has one or more
#'   \code{\link{offset}()} calls, there is an another auxiliary column named
#'   \code{".offset."}. Auxiliary columns are not considered part of the
#'   reference grid. (However, any variables included in \code{offset} calls
#'   \emph{are} in the reference grid.)
#' @slot levels list. Each entry is a character vector with the distinct levels
#'   of each variable in the reference grid. Note that \code{grid} is obtained
#'   by applying the function \code{\link{expand.grid}} to this list
#' @slot matlevs list. Like \code{levels} but has the levels of any matrices in
#'   the original dataset. Matrix columns are always concatenated and treated as
#'   a single variable for purposes of the reference grid
#' @slot linfct matrix. Each row consists of the linear function of the
#'   regression coefficients for predicting its corresponding element of the
#'   reference grid. The rows of this matrix go in one-to-one correspondence
#'   with the rows of \code{grid}, and the columns with elements of \code{bhat}.
#' @slot bhat numeric. The regression coefficients. If there is a multivariate
#'   response, the matrix of coefficients is flattened to a single vector, and
#'   \code{linfct} and \code{V} redefined appropriately. Important: \code{bhat}
#'   must \emph{include} any \code{NA} values produced as a result of
#'   collinearity in the predictors. These are taken care of later in the
#'   estimability check.
#' @slot nbasis matrix. The basis for the non-estimable functions of the
#'   regression coefficients. Every EMM will correspond to a linear combination
#'   of rows of \code{linfct}, and that result must be orthogonal to all the
#'   columns of \code{nbasis} in order to be estimable. If everything is
#'   estimable, \code{nbasis} should be a 1 x 1 matrix of \code{NA}.
#' @slot V matrix. The symmetric variance-covariance matrix of \code{bhat}
#' @slot dffun function having two arguments. \code{dffun(k, dfargs)} should
#'   return the degrees of freedom for the linear function \code{sum(k*bhat)},
#'   or \code{NA} if unavailable
#' @slot dfargs list. Used to hold any additional information needed by
#'   \code{dffun}.
#' @slot misc list. Additional information used by methods. These include at
#'   least the following: \code{estName} (the label for the estimates of linear
#'   functions), and the default values of \code{infer}, \code{level}, and
#'   this slot may be modified if desired using the \code{\link{update.emmGrid}}
#'   method.
#' @slot post.beta matrix. A sample from the posterior distribution of the
#'   regression coefficients, if MCMC methods were used; or a 1 x 1 matrix of
#'   \code{NA} otherwise. When it is non-trivial, the \code{\link{as.mcmc.emmGrid}}
#'   method returns \code{post.beta \%*\% t(linfct)}, which is a sample from the
#'   posterior distribution of the EMMs.
#'
#' @section Methods:
#'   All methods for these objects are S3 methods except for \code{show}.
#'
#' @export
setClass("emmGrid", slots = c(
model.info = "list",
roles = "list",
grid = "data.frame",
levels = "list",
matlevs = "list",
linfct = "matrix",
bhat = "numeric",
nbasis = "matrix",
V = "matrix",
dffun = "function",
dfargs = "list",
misc = "list",
post.beta = "matrix"
))
# Note: misc will hold various extra params,
# including at least the following req'd by the summary method
#   estName: column name for the estimate in the summary ["prediction"]
#   infer: booleans (CIs?, tests?)  [(FALSE,FALSE)]
#   level: default conf level [.95]