remef: Remove Partial Effects

Documented in keepef

#' Keep effects
#'
#' \code{keepef} is used to remove fixed and random effects from repsonse 
#'  variable based on a (linear) mixed-effects model object generated by the
#'  \pkg{lme4} package.
#' 
#' @param model a model object.
#' @param fix either a character vector of coefficient labels 
#'  (fixed effects) or a corresponding numeric index vector.
#' @param ran a named list of integer vectors representing
#'  random effects.
#' @param grouping logical. Should lower-order terms associated with the
#'  ones in \code{fix} also be kept? The details are given under 
#'  'Details'.
#' @param keep.intercept logical. Should the intercept be kept
#'  (default) or be removed?
#' @param inverse logical. If \code{TRUE}, the inverse of the link
#'  function is applied (after the effects are removed).
#' @return \code{keepef} returns a numeric vector. The length of the
#'  vector is equal to the number of observations of the model.   
#'                        
#' @details \code{model} is an object returned by a model fitting 
#'  function of the \pkg{lme4} package, i.e., \code{lmer} for
#'  linear mixed-effects models or \code{glmer} for generalised
#'  linear mixed-effects models.
#'  For more on details on mixed-effects models and partial effects, see
#'  the help page of \code{\link{partial}}.
#'  
#'  The response vector in a (generalised) linear mixed model
#'  can be represented as a sum of fixed effects,
#'  random effects, and residuals. \code{remef} "removes" a subset of these
#'  effects.
#'
#'  The valid \emph{character} strings for the parameter \code{fix} 
#'  correspond to the names of the coeffcients in the model summary output.
#'  Note that the name of a coefficient is not necessarily identical to the
#'  name of a predictor variable (e.g., factor variables). Furthermore,
#'  a single variable in a model formula can result in multiple 
#'  model coefficients (e.g., polynomial contrasts). The names of a model
#'  fit can be extracted with the function \code{effect_labels}.
#'  The character string passed to \code{fix} must not include the 
#'  intercept (\code{"(Intercept)"}). Use the parameter 
#'  \code{keep.intercept} instead.
#'   
#'  If \code{fix} is a \emph{numeric} index vector, the indices correspond
#'  to the order of coefficients in the model. For a fitted model object,
#'  the \code{effect_labels} returns the names of the coefficients in their
#'  order. Note that \code{fix} must not include the index of the
#'  intercept (usually \code{1}). Use the parameter \code{keep.intercept}
#'  instead.
#'   
#'  The parameter \code{ran} is used to specify random effects.
#'  The names of the list passed to \code{ran} correspond to the names
#'  of the random factors in the model summary.
#'  Alternatively, the string \code{"all"} can pe passed to \code{ran}
#'  which results in the selection of all random effects.
#'   
#'  If \code{grouping} is \code{FALSE}, only the specified fixed effects in
#'  \code{fix} are used. 
#'  If \code{grouping} is \code{TRUE}, associated effects of lower 
#'  order are kept too.
#'  For example,
#'  if a model fit has the terms \code{A}, \code{B}, \code{C},
#'  \code{A:B}, \code{A:C}, \code{B:C}, and \code{A:B:C},
#'  terms of lower order relative to \code{A:B} are
#'  \code{A} and \code{B}. Terms of lower order relative to \code{A:B:C}
#'  are \code{A}, \code{B}, \code{C}, \code{A:B}, \code{A:C},
#'  and \code{B:C}.
#'   
#'  The parameter \code{inverse} is only important for \emph{generalised}
#'  linear mixed-effects models (in contrast to linear mixed-effects 
#'  models). In the former type of statistical models, a link function
#'  is specified to transform the response variable.
#'  If \code{partial} is used with such a type of model, the resulting
#'  values will be in the metric of the variable \emph{after} after the
#'  transformation. For example, if the response is binary and a model with
#'  the binomial distribution using the logit link funtion is fit,
#'  the function \code{partial} will return
#'  logits unless \code{inverse = TRUE} in which case logits will be 
#'  transformed to proportions after the removal of effects. 
#'   
#' @seealso \code{\link{remef}} for a wrapper of \code{\link{partial}} with 
#'  \code{keep = FALSE}.
#' @export
#' @examples
#' library(lme4)
#' 
#' fm1 <- lmer(Reaction ~ 1 + Days + (1 + Days | Subject), sleepstudy)
#' summary(fm1)
#' 
#' # keep fixed effect of 'Days' (and the intercept), remove all other effects
#' k1_1 <- keepef(fm1, fix = "Days")
#' 
#' # keep fixed effect of 'Days' but not the intercept
#' k1_2 <- partial(fm1, fix = "Days", keep.intercept = FALSE)
#' 
#' # remove random slope of 'Days' (random factor: 'Subject')
#' k1_3 <- keepef(fm1, ran = list(Subject = "Days"))
#' 
#' # keep fixed effect of 'Days' and both random effects
#' k1_4 <- keepef(fm1, fix = "Days", ran = list(Subject = c("(Intercept)", "Days")))
#' # equivalent command with numeric indices
#' k1_5 <- keepef(fm1, fix = 2, ran = list(Subject = c(1, 2)))
#' 
#' # remove all effects (and the intercept)
#' k1_6 <- keepef(fm1, keep.intercept = FALSE)
#' all.equal(unname(residuals(fm1)), k1_6)
#' 
#' 
#' fm2 <- glmer(r2 ~ 1 + btype + Anger + (1 + Anger || item) + (1 | id), VerbAgg, family = binomial)
#' summary(fm2)
#' 
#' # keep fixed effects of 'btype'
#' # (since 'btype' is a three-level factor, two coefficients are estimated, 'btypescold' and 'btypeshout')
#' k2_1 <- keepef(fm2, fix = c("btypescold", "btypeshout"))
#' # extract coefficient names related to 'btype'
#' term2coef(fm2, "btype")
#' 
#' #' # since `fm2` is a binomial GLMM, the partial effects are logits,
#' # the parameter `inverse` can be used to return probablities instead
#' k2_1_prob <- keepef(fm2, fix = c("btypescold", "btypeshout"), inverse = TRUE)
#' 
#' # keep all random effects
#' # (Note that the order of random effects for the random factor 'item' is:
#' # 'Anger', '(Intercept)'; see `summary(fm2)`)
#' k2_2 <- keepef(fm2, ran = list(item = c(1, 2), id = 1))
#' k2_3 <- keepef(fm2, ran = "all")  # equivalent command
#' 
#' 
#' fm3 <- lmer(angle ~ 1 + recipe * temperature + (1 | recipe:replicate), cake)
#' summary(fm3)
#' 
#' # keep the random intercept
#' k3_1 <- partial(fm3, ran = list("recipe:replicate" = 1))
#' 
#' # keep fixed effect 'recipeB:temperature^4' and the lower-order ones (and the intercept)
#' k3_2 <- keepef(fm3, fix = "recipeB:temperature^4", grouping = TRUE)
#' # these are the lower-order terms of 'recipeB:temperature^4'
#' asef(fm3, "recipeB:temperature^4", order = "lower")
#' 
#' # keep all polynomials of 'temperature'
#' k3_3 <- keepef(fm3, fix = term2coef(fm3, "temperature"))

keepef <-
function(model, fix = NULL, ran = NULL, grouping = FALSE,
         keep.intercept = TRUE, inverse = FALSE)
{
  partial(model, fix = fix, ran = ran, grouping = grouping,
          keep.intercept = keep.intercept, inverse = inverse, keep = TRUE)
}