This is the low-level marginal effects calculator called by margins that assembles a “margins” object.
build_margins(model, data, type = c("response", "link", "terms"),
vce = c("delta", "simulation", "bootstrap"), iterations = 50L,
method = c("simple", "Richardson", "complex"), ...)A model object.
A data.frame over which to calculate marginal effects.
A character string indicating the type of marginal effects to estimate. Mostly relevant for non-linear models, where the reasonable options are “response” (the default) or “link” (i.e., on the scale of the linear predictor in a GLM).
A character string indicating the type of estimation procedure to use for estimating variances. The default (“delta”) uses the delta method. Alternatives are “bootstrap”, which uses bootstrap estimation, or “simulation”, which averages across simulations drawn from the joint sampling distribution of model coefficients. The latter two are extremely time intensive.
If vce = "bootstrap", the number of bootstrap iterations. If vce = "simulation", the number of simulated effects to draw. Ignored otherwise.
A character string indicating the numeric derivative method to use when estimating marginal effects. “simple” optimizes for speed; “Richardson” optimizes for accuracy. See grad for details.
Ignored.
A data.frame of class “margins” containing the contents of data, fitted values for model, the standard errors of the fitted values, and any estimated marginal effects. This data.frame may have repeated column names (for the original variables and the margginal effects thereof). Marginal effects columns are distinguished by their class (“marginaleffect”) and can be extracted using extract_marginal_effects. Attributes containing additional information, including the marginal effect variances and additional details.
Generally, it is not necessary to call this function directly because margins provides a simpler interface. To just get marginal effects without building a “margins” object, call marginal_effects instead, which handles the effect estimation of a model object without building a “margins” object.
This is the package's core function that assembles a “margins” object, through sequential calls to prediction, marginal_effects, and an internal function (get_effect_variances()) to calculate variances. See documentation pages for those functions for details on implementation and return values.
The choice of vce may be important. The default variance-covariance estimation procedure (vce = "delta") uses the delta method to estimate marginal effect variances. This is the fastest method. When vce = "simulation", coefficient estimates are repeatedly drawn from the asymptotic (multivariate normal) distribution of the model coefficients and each draw is used to estimate marginal effects, with the variance based upon the dispersion of those simulated effects. The number of interations used is given by iterations. For vce = "bootstrap", the bootstrap is used to repeatedly subsample data and the variance of marginal effects is estimated from the variance of the bootstrap distribution. This method is markedly slower than the other two procedures and, obviously, it will probably fail if atmeans = TRUE. Again, iterations regulates the number of boostrap subsamples to draw.