rstpm2 (version 1.5.1)

predictnl: Estimation of standard errors using the numerical delta method.

Description

A simple, yet exceedingly useful, approach to estimate the variance of a function using the numerical delta method. A number of packages provide functions that analytically calculate the gradients; we use numerical derivatives, which generalises to models that do not offer analytical derivatives (e.g. ordinary differential equations, integration), or to examples that are tedious or error-prone to calculate (e.g. sums of predictions from GLMs).

Usage

# S3 method for default
predictnl(object, fun, newdata=NULL, gd=NULL, ...)
# S3 method for lm
predictnl(object, fun, newdata=NULL, ...)
# S3 method for predictnl
print(x, ...)
# S3 method for formula
predict(object,data,newdata,na.action,type="model.matrix",...)
# S3 method for predictnl
confint(object, parm, level=0.95, ...)

Arguments

object

An object with coef, vcov and `coef<-` methods (required).

fun

A function that takes object as the first argument, possibly with newdata and other arguments (required). See notes for why it is often useful to include newdata as an argument to the function.

newdata

An optional argument that defines newdata to be passed to fun.

gd

An optional matrix of gradients. If this is not specified, then the gradients are calculated using finite differences.

parm

currently ignored

level

significance level for 2-sided confidence intervals

x

a predictnl object to be printed.

data

object used to define the model frame

na.action

passed to model.frame

type

currently restricted to "model.matrix"

Other arguments that are passed to fun.

Value

Returns an object of class an object with class c("predictnl","data.frame") elements c("fit","se.fit","Estimate","SE") and with methods print and confint. Note that the Estimate and SE fields are deprecated and their use is discouraged, as we would like to remove them from future releases.

Details

The signature for fun is either fun(object, ...) or fun(object, newdata=NULL, ...).

The different predictnl methods call the utility function numDeltaMethod, which in turn calls the grad function for numerical differentiation. The numDeltaMethod function calls the standard coef and vcov methods, and the non-standard `coef<-` method for changing the coefficients in a regression object. This non-standard method has been provided for several regression objects and essentially mirrors the coef method.

One potential issue is that some predict methods do not re-calculate their predictions for the fitted dataset (i.e. when newdata=NULL). As the predictnl function changes the fitted coefficients, it is required that the predictions are re-calculated. One solution is to pass newdata as an argument to both predictnl and fun; alternatively, newdata can be specified in fun. These approaches are described in the examples below. The numDeltaMethod method called by predictnl provides a warning when the variance estimates are zero, which may be due to this cause.

For completeness, it is worth discussing why the example predictnl(fit,predict) does not work for when fit is a glm object. First, predict.glm does not update the predictions for the fitted data. Second, the default predict method has a signature predict(object, ...), which does not include a newdata argument. We could then either (i) require that a newdata argument be passed to the fun function for all examples, which would make this corner case work, or (ii) only pass the newdata argument if it is non-null or in the formals for the fun function, which would fail for this corner case. The current API defaults to the latter case (ii). To support this approach, the predictnl.lm method replaces a null newdata with object$data. We also provide a revised numdelta:::predict.lm method that performs the same operation, although its use is not encouraged due to its clumsiness.

Examples

Run this code
# NOT RUN {
df <- data.frame(x=0:1, y=c(10, 20))
fit <- glm(y ~ x, df, family=poisson)

predictnl(fit,
          function(obj,newdata)
          diff(predict(obj,newdata,type="response")))

# }

Run the code above in your browser using DataCamp Workspace