VGAM (version 1.1-6)

# margeff: Marginal Effects for Several Categorical Response Models

## Description

Marginal effects for the multinomial logit model and cumulative logit/probit/... models and continuation ratio models and stopping ratio models and adjacent categories models: the derivative of the fitted probabilities with respect to each explanatory variable.

## Usage

`margeff(object, subset = NULL, ...)`

## Arguments

object

A `vglm` object, with one of the following family functions: `multinomial`, `cumulative`, `cratio`, `sratio` or `acat`.

subset

Numerical or logical vector, denoting the required observation(s). Recycling is used if possible. The default means all observations.

further arguments passed into the other methods functions.

## Value

A \(p\) by \(M+1\) by \(n\) array, where \(p\) is the number of explanatory variables and the (hopefully) nominal response has \(M+1\) levels, and there are \(n\) observations.

In general, if `is.numeric(subset)` and `length(subset) == 1` then a \(p\) by \(M+1\) matrix is returned.

## Warning

Care is needed in interpretation, e.g., the change is not universally accurate for a unit change in each explanatory variable because eventually the `new' probabilities may become negative or greater than unity. Also, the `new' probabilities will not sum to one.

This function is not applicable for models with data-dependent terms such as `bs` and `poly`. Also the function should not be applied to models with any terms that have generated more than one column of the LM model matrix, such as `bs` and `poly`. For such try using numerical methods such as finite-differences. The `formula` in `object` should comprise of simple terms of the form ` ~ x2 + x3 + x4`, etc.

Some numerical problems may occur if the fitted values are close to 0 or 1 for the `cratio` and `sratio` models. Models with offsets may result in an incorrect answer.

## Details

Computes the derivative of the fitted probabilities of the categorical response model with respect to each explanatory variable. Formerly one big function, this function now uses S4 dispatch to break up the computations.

The function `margeff()` is not generic. However, it calls the function `margeffS4VGAM()` which is. This is based on the class of the `VGAMff` argument, and it uses the S4 function `setMethod` to correctly dispatch to the required methods function. The inheritance is given by the `vfamily` slot of the VGAM family function.

`multinomial`, `cumulative`, `propodds`, `acat`, `cratio`, `sratio`, `vglm`.

## Examples

Run this code
``````# NOT RUN {
# Not a good example for multinomial() since the response is ordinal!!
ii <- 3; hh <- 1/100
pneumo <- transform(pneumo, let = log(exposure.time))
fit <- vglm(cbind(normal, mild, severe) ~ let, multinomial, pneumo)
fit <- vglm(cbind(normal, mild, severe) ~ let,
cumulative(reverse = TRUE,  parallel = TRUE),
data = pneumo)
fitted(fit)[ii, ]

mynewdata <- with(pneumo, data.frame(let = let[ii] + hh))
(newp <- predict(fit, newdata = mynewdata, type = "response"))

# Compare the difference. Should be the same as hh --> 0.
round((newp-fitted(fit)[ii, ]) / hh, 3)  # Finite-diff approxn
round(margeff(fit, subset = ii)["let",], 3)

# Other examples
round(margeff(fit), 3)
round(margeff(fit, subset = 2)["let",], 3)
round(margeff(fit, subset = c(FALSE, TRUE))["let",,], 3)  # Recycling
round(margeff(fit, subset = c(2, 4, 6, 8))["let",,], 3)

# Example 3; margeffs at a new value
mynewdata2a <- data.frame(let = 2)  # New value
mynewdata2b <- data.frame(let = 2 + hh)  # For finite-diff approxn
(neweta2 <- predict(fit, newdata = mynewdata2a))
fit@x[1, ] <- c(1, unlist(mynewdata2a))
fit@predictors[1, ] <- neweta2  # Needed
max(abs(margeff(fit, subset = 1)["let", ] - (
predict(fit, newdata = mynewdata2b, type = "response") -
predict(fit, newdata = mynewdata2a, type = "response")) / hh
))  # Should be 0
# }
``````

Run the code above in your browser using DataCamp Workspace