Standard S3 generics for deli estimators

Methods for base R generics stats::coef(), stats::vcov(), stats::confint(), stats::nobs(), stats::df.residual(), stats::fitted(), stats::residuals(), stats::weights(), stats::model.frame(), stats::model.matrix(), stats::formula(), stats::terms(), stats::sigma(), stats::logLik(), and stats::deviance() so that deli estimator objects interoperate with the broader R modeling ecosystem.

Usage

# S3 method for class '`deli::deli_estimator`'
coef(object, ...)

# S3 method for class '`deli::deli_estimator`'
vcov(object, ...)

# S3 method for class '`deli::deli_estimator`'
confint(object, parm, level = 0.95, ...)

# S3 method for class '`deli::deli_estimator`'
nobs(object, ...)

# S3 method for class '`deli::deli_estimator`'
df.residual(object, ...)

# S3 method for class '`deli::deli_estimator`'
fitted(object, ...)

# S3 method for class '`deli::deli_estimator`'
residuals(object, type = "response", ...)

# S3 method for class '`deli::deli_estimator`'
weights(object, ...)

# S3 method for class '`deli::deli_estimator`'
model.frame(
  formula,
  data = NULL,
  subset = NULL,
  na.action,
  drop.unused.levels = FALSE,
  xlev = NULL,
  ...
)

# S3 method for class '`deli::deli_estimator`'
model.matrix(object, data = NULL, ...)

# S3 method for class '`deli::deli_estimator`'
formula(x, ...)

# S3 method for class '`deli::deli_estimator`'
terms(x, ...)

# S3 method for class '`deli::deli_estimator`'
sigma(object, ...)

# S3 method for class '`deli::deli_estimator`'
logLik(object, ...)

# S3 method for class '`deli::deli_estimator`'
deviance(object, ...)

Arguments

object: A fitted MEstimator or GMMEstimator object (after calling estimate()).
...: Not used. confint(), residuals(), model.frame(), and model.matrix() require them to be empty, so that a name none of them recognizes is an error rather than silently ignored: a misspelled level would report the default limits, a misspelled type would report response residuals as though they had been asked for, and a misspelled data would report on the fitted rows while the caller believed they had asked for rows of their own. The rest ignore them, which is the convention for a base generic with no optional argument for a wrong name to displace.
parm: A specification of which parameters are to be given confidence intervals, either a vector of numbers or a vector of names. If missing, all parameters are considered.
level: The confidence level required. Default 0.95.
type: Character string naming the residual residuals() returns. Only "response" is available, since it is the one residual defined for every estimating equation predict() supports. Any other value is an error rather than a response residual under another name.
formula: A fitted MEstimator or GMMEstimator object. Named formula because stats::model.frame() names its first argument that; the method takes a fit, not a formula.
data: A data frame to build the model frame or the design matrix of, or NULL (default) to report the one the fit was solved on. model.frame() needs it to carry the response as well as the predictors; model.matrix() names no response, so the predictors alone are enough there.
subset, na.action, drop.unused.levels, xlev: Passed to stats::model.frame(), and meaning there what they mean for any other model frame. xlev defaults to the factor levels the fit recorded. All four describe how to build a frame from data, so supplying one without data is an error rather than a silent no-op.
x: A fitted MEstimator or GMMEstimator object. Named x because stats::formula() and stats::terms() name their first argument that.

Value

coef(): Named numeric vector of parameter estimates.
vcov(): Named variance-covariance matrix.
confint(): Matrix with columns "lower" and "upper".
nobs(): Integer number of observations.
df.residual(): Integer residual degrees of freedom, the number of observations less the number of parameters.
fitted(): Named numeric vector of fitted values on the response scale, one per observation the fit was solved on.
residuals(): Named numeric vector of response residuals.
weights(): The observation weights the fit was solved with, as they were recorded, or NULL for a formula fit specified without any. Weights that vary over time are reported as the matrix they were supplied as rather than as a vector: ee_plogit() takes an n-by-K matrix carrying one column per time interval, and an observation weighted differently in each interval has no one weight for a vector to hold.
model.frame(): The model frame the fit was built from, with the rows dropped for missing data already removed, or the model frame of data when one is supplied.
model.matrix(): The design matrix the fit was solved on, or the design matrix of data when one is supplied, coded with the contrasts and factor levels the fit recorded.
formula(): The model formula.
terms(): The terms object of the model frame, carrying the response index, any offset, and the predvars of a data-dependent term.
sigma(), logLik(), deviance(): Nothing. Each raises an error saying that an M-estimator states no likelihood and records no residual scale.

Details

fitted(), residuals(), weights(), model.frame(), model.matrix(), formula(), and terms() report on the model a fit was specified as, which only the formula interface records, so each of them is an error for a fit built from a stacked_equations function. fitted() and residuals() are also an error for a formula fit of an estimating equation predict() does not support, since a fitted value is a prediction; see deli-predict for the equations it covers.

fitted() is the conditional mean of the response, so it is on the response scale rather than the link scale, matching stats::fitted() on a glm object. residuals() is the response minus that mean, the residual a GLM calls a response residual, and the only type it takes. Deviance and Pearson residuals are not offered: the first needs a likelihood and the second a variance function, and an M-estimator need not state either, while the response residual is defined the same way for every equation predict() supports. Under a non-identity link it is heteroscedastic by construction.

model.frame() returns the frame the fit was solved on, or builds the frame of data when one is supplied, through the terms and factor levels the fit recorded. A data-dependent term such as poly(x, 2) is therefore evaluated at its fitted basis and a factor gets its fitted levels, as they are under predict(). data has to carry the response, since a model frame holds every variable the formula names; covariate values that carry no response are what predict() and deli-augment take a newdata for.

model.matrix() returns the design the fit was solved on, or the design of data when one is supplied, coded with the contrasts and factor levels the fit recorded rather than with whatever getOption("contrasts") says when the call is made. A design matrix is a property of the fit, so a fit made under one setting of that option answers with the coding it was solved on under any other, which is what predict() does as well. A design names no response, so data needs only the predictors.

df.residual() is the number of observations less the number of parameters. Both counts belong to the fit rather than to a specification, so it answers for a fit built from a stacked_equations function as readily as for a formula one. weights() returns the observation weights the fit was solved with, which reach a fit only through the formula interface. A formula fit specified without weights returns NULL, as stats::weights() does for an unweighted stats::lm() fit: a vector of ones would be indistinguishable from a fit weighted by ones.

sigma(), logLik(), and deviance() are errors for every fit, and say why. An M-estimator is defined by its estimating equations, which need come from no likelihood at all, so there is no log-likelihood to return and no deviance to take from one; stats::AIC() and stats::BIC() reach a fit through logLik() and are refused with it. A residual standard deviation belongs to the model an equation states rather than to the solve: a linear equation has one, a logistic equation has none, and nothing in the estimates says which was solved. Reporting an error is the only answer that does not invent a quantity the fit never had.

Examples

fit <- m_estimate(mpg ~ wt + hp, data = mtcars, .ee = ee_regression,
                  model = "linear")

coef(fit)
#> (Intercept)          wt          hp 
#> 37.22727012 -3.87783074 -0.03177295 

vcov(fit)
#>              (Intercept)           wt            hp
#> (Intercept)  3.759412749 -0.991167246 -1.918909e-03
#> wt          -0.991167246  0.384309827 -1.649185e-03
#> hp          -0.001918909 -0.001649185  4.417008e-05

confint(fit)
#>                   lower       upper
#> (Intercept) 33.42705575 41.02748449
#> wt          -5.09286587 -2.66279561
#> hp          -0.04479898 -0.01874691

nobs(fit)
#> [1] 32

df.residual(fit)
#> [1] 29

head(fitted(fit))
#>         Mazda RX4     Mazda RX4 Wag        Datsun 710    Hornet 4 Drive 
#>          23.57233          22.58348          25.27582          21.26502 
#> Hornet Sportabout           Valiant 
#>          18.32727          20.47382 

head(residuals(fit))
#>         Mazda RX4     Mazda RX4 Wag        Datsun 710    Hornet 4 Drive 
#>        -2.5723294        -1.5834826        -2.4758187         0.1349799 
#> Hornet Sportabout           Valiant 
#>         0.3727334        -2.3738163 

formula(fit)
#> mpg ~ wt + hp
#> <environment: 0x563b97831a18>

# Weights reach a fit through the formula interface, and `weights()` reports
# the vector the fit was solved with.
weighted <- m_estimate(mpg ~ wt + hp, data = mtcars, .ee = ee_regression,
                       model = "linear", weights = 1 / hp)

head(weights(weighted))
#> [1] 0.009090909 0.009090909 0.010752688 0.009090909 0.005714286 0.009523810