1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/lfe-tidiers.R
3\name{augment.felm}
4\alias{augment.felm}
5\title{Augment data with information from a(n) felm object}
6\usage{
7\method{augment}{felm}(x, data = model.frame(x), ...)
8}
9\arguments{
10\item{x}{A \code{felm} object returned from \code{\link[lfe:felm]{lfe::felm()}}.}
11
12\item{data}{A \link[base:data.frame]{base::data.frame} or \code{\link[tibble:tibble]{tibble::tibble()}} containing the original
13data that was used to produce the object \code{x}. Defaults to
14\code{stats::model.frame(x)} so that \code{augment(my_fit)} returns the augmented
15original data. \strong{Do not} pass new data to the \code{data} argument.
16Augment will report information such as influence and cooks distance for
17data passed to the \code{data} argument. These measures are only defined for
18the original training data.}
19
20\item{...}{Additional arguments. Not used. Needed to match generic
21signature only. \strong{Cautionary note:} Misspelled arguments will be
22absorbed in \code{...}, where they will be ignored. If the misspelled
23argument has a default value, the default value will be used.
24For example, if you pass \code{conf.lvel = 0.9}, all computation will
25proceed using \code{conf.level = 0.95}. Additionally, if you pass
26\code{newdata = my_tibble} to an \code{\link[=augment]{augment()}} method that does not
27accept a \code{newdata} argument, it will use the default value for
28the \code{data} argument.}
29}
30\description{
31Augment accepts a model object and a dataset and adds
32information about each observation in the dataset. Most commonly, this
33includes predicted values in the \code{.fitted} column, residuals in the
34\code{.resid} column, and standard errors for the fitted values in a \code{.se.fit}
35column. New columns always begin with a \code{.} prefix to avoid overwriting
36columns in the original dataset.
37
38Users may pass data to augment via either the \code{data} argument or the
39\code{newdata} argument. If the user passes data to the \code{data} argument,
40it \strong{must} be exactly the data that was used to fit the model
41object. Pass datasets to \code{newdata} to augment data that was not used
42during model fitting. This still requires that at least all predictor
43variable columns used to fit the model are present. If the original outcome
44variable used to fit the model is not included in \code{newdata}, then no
45\code{.resid} column will be included in the output.
46
47Augment will often behave differently depending on whether \code{data} or
48\code{newdata} is given. This is because there is often information
49associated with training observations (such as influences or related)
50measures that is not meaningfully defined for new observations.
51
52For convenience, many augment methods provide default \code{data} arguments,
53so that \code{augment(fit)} will return the augmented training data. In these
54cases, augment tries to reconstruct the original data based on the model
55object with varying degrees of success.
56
57The augmented dataset is always returned as a \link[tibble:tibble]{tibble::tibble} with the
58\strong{same number of rows} as the passed dataset. This means that the
59passed data must be coercible to a tibble. At this time, tibbles do not
60support matrix-columns. This means you should not specify a matrix
61of covariates in a model formula during the original model fitting
62process, and that \code{\link[splines:ns]{splines::ns()}}, \code{\link[stats:poly]{stats::poly()}} and
63\code{\link[survival:Surv]{survival::Surv()}} objects are not supported in input data. If you
64encounter errors, try explicitly passing a tibble, or fitting the original
65model on data in a tibble.
66
67We are in the process of defining behaviors for models fit with various
68\code{na.action} arguments, but make no guarantees about behavior when data is
69missing at this time.
70}
71\examples{
72
73if (requireNamespace("lfe", quietly = TRUE)) {
74
75library(lfe)
76
77# Use built-in "airquality" dataset
78head(airquality)
79
80# No FEs; same as lm()
81est0 <- felm(Ozone ~ Temp + Wind + Solar.R, airquality)
82tidy(est0)
83augment(est0)
84
85# Add month fixed effects
86est1 <- felm(Ozone ~ Temp + Wind + Solar.R  | Month, airquality)
87tidy(est1)
88tidy(est1, fe = TRUE)
89augment(est1)
90glance(est1)
91
92# The "se.type" argument can be used to switch out different standard errors
93# types on the fly. In turn, this can be useful exploring the effect of
94# different error structures on model inference.
95tidy(est1, se.type = "iid")
96tidy(est1, se.type = "robust")
97
98# Add clustered SEs (also by month)
99est2 <- felm(Ozone ~ Temp + Wind + Solar.R  | Month | 0 | Month, airquality)
100tidy(est2, conf.int = TRUE)
101tidy(est2, conf.int = TRUE, se.type = "cluster")
102tidy(est2, conf.int = TRUE, se.type = "robust")
103tidy(est2, conf.int = TRUE, se.type = "iid")
104
105}
106
107}
108\seealso{
109\code{\link[=augment]{augment()}}, \code{\link[lfe:felm]{lfe::felm()}}
110
111Other felm tidiers:
112\code{\link{tidy.felm}()}
113}
114\concept{felm tidiers}
115\value{
116A \code{\link[tibble:tibble]{tibble::tibble()}} with columns:
117  \item{.fitted}{Fitted or predicted value.}
118  \item{.resid}{The difference between observed and fitted values.}
119
120}
121