polywog (version 0.4-1)

predVals: Easy computation of fitted values

Description

User-friendly generation of fitted values and their confidence intervals from models of class "polywog", using the "observed-value approach" advocated by Hanmer and Kalkan (2013).

Usage

predVals(model, xvars, data = model$model, xlims = list(), n = 100,
  interval = TRUE, level = 0.95, maxrows = 10000, report = FALSE,
  .parallel = FALSE, ...)

Arguments

model

a fitted model of class "polywog", typically the output of polywog.

xvars

a character vector containing names of raw input variables (from model$varNames). Partial matches are allowed.

data

data frame to treat as the observed sample (defaults to the data used to fit the supplied model)

xlims

named list of limits for the evaluation grid for each continuous variable in xvars. If not given, the variable's observed range is used.

n

number of grid points at which to evaluate each continuous variable in xvars.

interval

logical: whether to compute bootstrap confidence intervals for each fitted value.

level

confidence level for the intervals.

maxrows

maximum number of rows of output. Used to prevent accidental memory overruns when xvars contains more than two continuous variables.

report

logical: whether to print a status bar. Not available if .parallel = TRUE.

.parallel

logical: whether to perform bootstrap iterations in parallel using foreach. See the "Details" section of the bootPolywog documentation page for more on parallel computation.

...

other arguments, currently ignored

Value

A data frame containing the fitted values and confidence intervals (if requested) for each combination of covariate values.

The returned data frame also inherits from class "preplot.polywog". This is used by plot.polywog, which calls predVals to compute the values to plot.

Details

predVals allows users to examine the estimated effects of input variables on the expected outcome using the coefficients returned by polywog. The procedure is designed so that, for a preliminary analysis, the user can simply specify the fitted model and the independent variable of interest, and quickly obtain predicted values.

The predicted values are generated according to Hanmer and Kalkan's (2013) observed-value approach, which takes the form of a nested loop. When xvars contains a single variable \(X_m\), the procedure is as follows:

1. For each level \(x\) of \(X_m\) in data (if \(X_m\) is discrete) or each element \(x\) of a grid over the range of \(X_m\) in data (if \(X_m\) is continuous):

   1. For each observation \(i\) of data:

      1. Set \(X_{mi} = x\), while holding all other variables \(X_{-mi}\) at their observed levels

      2. Compute the predicted value of \(Y_i\) for the modified observation \(i\), using the estimated model coefficients (as in predict.polywog)

   2. The predicted value of \(Y\) given \(X_m = x\) is the average of the predictions computed in the previous step

This observed-value approach provides a better estimate of population average effects for nonlinear models than does the traditional approach, which is to vary \(X_m\) across its levels/range while holding each other covariate to its mean or median in data (Hanmer and Kalkan 2013).

When xvars consists of multiple variables \(X_1, \ldots, X_M\), the predVals procedure is the same, except the outer loop is over every combination of their levels in data.

All confidence intervals are generated via the bootstrap. Specifically, predVals repeats the above procedure for each set of bootstrap coefficients and computes order statistics of the resulting set of averages (for each combination of levels of xvars). If model does not have a boot.matrix element (see bootPolywog), confidence intervals will not be computed.

References

Michael J. Hanmer and Kerem Ozan Kalkan. 2013. "Behind the Curve: Clarifying the Best Approach to Calculating Predicted Probabilities and Marginal Effects from Limited Dependent Variable Models." American Journal of Political Science 57(1):263--277.

See Also

predict.polywog for more flexible (but less user-friendly) computation of fitted values. plot.polywog for plotting fitted values and their confidence intervals.

Examples

# NOT RUN {
## Using occupational prestige data
data(Prestige, package = "carData")
Prestige <- transform(Prestige, income = income / 1000)

## Fit a polywog model with bootstrap iterations
## (note: using low convergence threshold to shorten computation time of the
## example, *not* recommended in practice!)
set.seed(22)
fit1 <- polywog(prestige ~ education + income + type,
                data = Prestige,
                degree = 2,
                boot = 5,
                thresh = 1e-4)

## Predicted prestige across occupational categories
predVals(fit1, "type")

## Predicted prestige by education
predVals(fit1, "education", n = 10)

## Plotting
pred_income <- predVals(fit1, "income", n = 10)
plot(pred_income)
# }