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