% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cov_adj.R
\name{cov_adj}
\alias{cov_adj}
\title{Prepare prognostic regression offset for \code{lmitt()} or \code{lm()}}
\usage{
cov_adj(
  model,
  newdata = NULL,
  specification = NULL,
  by = NULL,
  set_to_reference = NULL
)
}
\arguments{
\item{model}{any model that inherits from a \code{glm}, \code{lm}, or
\code{robustbase::lmrob} object.}

\item{newdata}{a dataframe; optional. See Details for how \code{newdata}
is found in the call stack if none is provided.}

\item{specification}{a \code{StudySpecification} object; optional. If not
provided, it can be retrieved from the call stack if passed to suitable
calls.}

\item{by}{named vector; optional.}

\item{set_to_reference}{named list; optional.}
}
\value{
A \code{SandwichLayer} if \code{specification} is not NULL or a
\code{StudySpecification} object is found in the call stack, otherwise a
\code{PreSandwichLayer} object
}
\description{
\code{cov_adj()} takes a fitted model object and predicts
outcomes under the counterfactual of being in the control condition.
Using these predictions as offsets in a linear model with just the
treatment variable as a regressor estimates the treatment effect with
covariance adjustments as provided by the previously fitted model.
In the special case that this covariance model was fit using only
(quasi-)experimental control group observations, the method is known
as Peters-Belson regression. \code{cov_adj()} assists the process by
reporting its predictions on the scale of the response (in contrast to
\code{predict.glm()}) and by retaining certain artifacts from
covariance model fitting.  These artifacts are used by \code{\link[=vcov_tee]{vcov_tee()}},
and by \code{\link[stats:vcov]{stats::vcov()}} as applied to a \code{teeMod} object, so
that the covariance model's contribution to sampling variability
is reflected in treatment coefficient standard errors.
\code{cov_adj()} can be used with \code{lm()}, but is better supported
in combination with propertee's \code{lm}-wrapper, \code{\link[=lmitt]{lmitt()}}.
}
\details{
If \code{specification} is provided or can be found in the call
stack, then prior to generating adjustments, \code{cov_adj()} will
identify the treatment variable and replace all values with a reference
level. If the treatment has logical type, this reference level is
\code{FALSE}, and if it has numeric type, this is the smallest
non-negative value (which means 0 for 0/1 binary). (Factor treatments are
not currently supported.)\cr\cr More
broadly, the \code{set_to_reference} argument can be used to set columns
to values specified by the user prior to generating predictions. The
argument takes a named list where the names specify the columns whose
values should be replaced, and the entries specify the replacement values.
If an entry is given as \code{default()}, internal routines will determine
the reference level (the first level of a factor/factorized character
variable or the minimum of a numeric/logical variable). \cr\cr If
\code{newdata} is provided, the values of the output vector represent
adjustments for the outcomes in \code{newdata}. If \code{cov_adj()} is
called in the \code{offset} argument of \code{lmitt()}, predictions will
correspond to rows in the \code{data} argument of \code{lmitt()}.
Otherwise, adjustments are made based on the data to which \code{model} is
fit. \cr\cr The \code{by} argument specifies columns for merging datasets.
The names of the argument specify columns in the dataframe for building
\code{specification}, while the entries specify columns in the dataframe
for fitting \code{model}.
}
\examples{
data("STARplus")

##' A prognostic model fitted to experimental + non-experimental controls
y0hat_read <- lm(read_yr1 ~ gender*dob +dobNA + race,
                 data = STARplus,
                 subset = cond_at_entry!="small")

STARspec <- rct_spec(cond_at_entry ~ unit_of_assignment(stdntid) +
                         block(grade_at_entry, school_at_entry),
                     subset=!is.na(grade_at_entry),# excludes non-experimentals
                     data = STARplus)
ett_wts    <- ett(STARspec, data = STARplus,
                  dichotomy= cond_at_entry =="small" ~.)

ett_read <- lm(read_yr1 ~ assigned(dichotomy= cond_at_entry =="small" ~.),
               offset = cov_adj(y0hat_read),
               data = STARplus,
               weights = ett_wts)
coef(ett_read)
ett_read |> as.lmitt() # brings in control-group means of outcome, predictions

ate_read <- lmitt(read_yr1 ~ 1, STARspec, STARplus,
                  dichotomy= cond_at_entry =="small" ~.,
                  offset = cov_adj(y0hat_read),
                  weights = "ate")
show(ate_read)
vcov(ate_read, type = "HC0", cov_adj_rcorrect = "HC0") |> unname()

ate_read_loc <-
    lmitt(read_yr1 ~ race, STARspec, STARplus,
          dichotomy= cond_at_entry =="small" ~.,
          offset = cov_adj(y0hat_read, newdata = STARplus),
          weights = "ate")
show(ate_read_loc)
}
