margins (version 0.3.23)

dydx: Marginal Effect of a Given Variable

Description

Differentiate an Estimated Model Function with Respect to One Variable, or calculate a discrete difference (“first difference”) as appropriate.

Usage

dydx(data, model, variable, ...)
# S3 method for default
dydx(data, model, variable, type = c("response", "link"),
  change = c("dydx", "minmax", "iqr", "sd"), eps = 1e-07,
  as.data.frame = TRUE, ...)
# S3 method for factor
dydx(data, model, variable, type = c("response", "link"),
  fwrap = FALSE, as.data.frame = TRUE, ...)
# S3 method for ordered
dydx(data, model, variable, type = c("response", "link"),
  fwrap = FALSE, as.data.frame = TRUE, ...)
# S3 method for logical
dydx(data, model, variable, type = c("response", "link"),
  as.data.frame = TRUE, ...)

Arguments

data

The dataset on which to to calculate \(\hat{y}\).

model

The model object to pass to prediction.

variable

A character string specifying the variable to calculate the derivative or discrete change for.

…

Ignored.

type

The type of prediction. Default is “response”.

change

For numeric variables, a character string specifying the type of change to express. The default is the numerical approximation of the derivative. Alternative values are occasionally desired quantities: “minmax” (the discrete change moving from min(x) to max(x)), “iqr” (the move from the 1st quartile to 3rd quartile of x), or “sd” (the change from mean(x) - sd(x) to mean(x) + sd(x)), or a two-element numeric vector expressing values of the variable to calculate the prediction for (and difference the associated predictions).

eps

If change == "dydx" (the default), the value of the step \(\epsilon\) to use in calculation of the numerical derivative for numeric variables.

as.data.frame

A logical indicating whether to return a data frame (the default) or a matrix.

fwrap

A logical specifying how to name factor columns in the response.

Value

A data frame, typically with one column unless the variable is a factor with more than two levels. The names of the marginal effect columns begin with “dydx_” to distinguish them from the substantive variables of the same names.

Details

These functions provide a simple interface to the calculation of marginal effects for specific variables used in a model, and are the workhorse functions called internally by marginal_effects.

dydx is an S3 generic with classes implemented for specific variable types. S3 method dispatch, somewhat atypically, is based upon the class of data[[variable]].

For numeric (and integer) variables, the method calculates an instantaneous marginal effect using a simple “central difference” numerical differentiation: $$\frac{f(x + \frac{1}{2}h) - f(x - \frac{1}{2}h)}{dh}$$, where (\(h = \max(|x|, 1) \sqrt{\epsilon}\) and the value of \(\epsilon\) is given by argument eps. This procedure is subject to change in the future.

For factor variables (or character variables, which are implicitly coerced to factors by modelling functions), discrete first-differences in predicted outcomes are reported instead (i.e., change in predicted outcome when factor is set to a given level minus the predicted outcome when the factor is set to its baseline level). These are sometimes called “partial effects”. If you want to use numerical differentiation for factor variables (which you probably do not want to do), enter them into the original modelling function as numeric values rather than factors.

For ordered factor variables, the same approach as factors is used. This may contradict the output of modelling function summaries, which rely on options("contrasts") to determine the contrasts to use (the default being contr.poly rather than contr.treatment, the latter being used normally for unordered factors).

For logical variables, the same approach as factors is used, but always moving from FALSE to TRUE.

References

Miranda, Mario J. and Paul L. Fackler. 2002. Applied Computational Economics and Finance. p. 103.

Greene, William H. 2012. Econometric Analysis. 7th edition. pp. 733--741.

Cameron, A. Colin and Pravin K. Trivedi. 2010. Microeconometric Using Stata. Revised edition. pp. 106--108, 343--356, 476--478.

See Also

marginal_effects, margins

Examples

# NOT RUN {
require("datasets")
x <- lm(mpg ~ cyl * hp + wt, data = head(mtcars))
# marginal effect (numerical derivative)
dydx(head(mtcars), x, "hp")

# other discrete differences
## change from min(mtcars$hp) to max(mtcars$hp)
dydx(head(mtcars), x, "hp", change = "minmax")
## change from 1st quartile to 3rd quartile
dydx(head(mtcars), x, "hp", change = "iqr")
## change from mean(mtcars$hp) +/- sd(mtcars$hp)
dydx(head(mtcars), x, "hp", change = "sd")
## change between arbitrary values of mtcars$hp
dydx(head(mtcars), x, "hp", change = c(75,150))

# factor variables
mtcars[["cyl"]] <- factor(mtcars$cyl)
x <- lm(mpg ~ cyl, data = head(mtcars))
dydx(head(mtcars), x, "cyl")

# }