1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/plm-tidiers.R
3\name{augment.plm}
4\alias{augment.plm}
5\title{Augment data with information from a(n) plm object}
6\usage{
7\method{augment}{plm}(x, data = model.frame(x), ...)
8}
9\arguments{
10\item{x}{A \code{plm} objected returned by \code{\link[plm:plm]{plm::plm()}}.}
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("plm", quietly = TRUE)) {
74
75library(plm)
76
77data("Produc", package = "plm")
78zz <- plm(log(gsp) ~ log(pcap) + log(pc) + log(emp) + unemp,
79  data = Produc, index = c("state", "year")
80)
81
82summary(zz)
83
84tidy(zz)
85tidy(zz, conf.int = TRUE)
86tidy(zz, conf.int = TRUE, conf.level = 0.9)
87
88augment(zz)
89glance(zz)
90
91}
92
93}
94\seealso{
95\code{\link[=augment]{augment()}}, \code{\link[plm:plm]{plm::plm()}}
96
97Other plm tidiers:
98\code{\link{glance.plm}()},
99\code{\link{tidy.plm}()}
100}
101\concept{plm tidiers}
102\value{
103A \code{\link[tibble:tibble]{tibble::tibble()}} with columns:
104  \item{.fitted}{Fitted or predicted value.}
105  \item{.resid}{The difference between observed and fitted values.}
106
107}
108