procast {topmodels}R Documentation

Procast: Probabilistic Forecasting

Description

Generic function and methods for computing various kinds of forecasts from probabilistic (regression) models (probabilistic 4-casting).

Usage

procast(object, newdata = NULL, na.action = na.pass, type = "quantile", at = 0.5, ...)

## S3 method for class 'lm'
procast(object, newdata = NULL, na.action = na.pass,
  type = c("quantile", "mean", "variance", "parameter", "density", "probability", "score"),
  at = 0.5, drop = FALSE, ...)

procast_setup(pars, FUN, at = NULL, drop = FALSE, type = "procast", ...)

Arguments

object

a fitted model object. For the default method this needs to needs to be formula-based so that model.frame can be used to extract the response from the original data the model was fitted to or terms can be used to set up the response on newdata.

newdata

optionally, a data frame in which to look for variables with which to predict. If omitted, the original observations are used.

na.action

function determining what should be done with missing values in newdata. The default is to employ NA.

type

character specifying the type of probabilistic forecast to compute. In procast_setup the type is only used for nice labels of the returned data frame.

at

specification of values at which the forecasts should be evaluated, typically a numeric vector but possibly also a matrix or data frame. Additionally, at can be the character string "function" or "list", see details below.

drop

logical. Should forecasts be returned in a data frame (default) or (if possible) dropped to a vector, see details below.

FUN

function to be used for forecasts. Either of type FUN(pars, ...) or FUN(at, pars, ...), see details below.

pars

a data frame of predicted distribution parameters.

...

further parameters passed to methods.

Details

The function procast provides a unified framework for probabilistic 4-casting based on probabilistic (regression) models, also known as distributional regression approaches. Typical types of predictions include quanitles, probabilities, (conditional) expectations, variances, (log-)densities, or scores. Internally, procast methods typically compute the predicted parameters for each observation and then transform these to the desired outcome. Some quantities (e.g., expectations or variances) can be computed directly from the predicted parameters of the distribution while others require an additional argument at which the distribution is evaluated (e.g., the probability of a quantile or an observation of the response. The argument at can also be the character "function" or "list" so that a single function or list of functions is set up that can be evaluated at different values later on.

The function procast_setup is a convenience wrapper that make setting up procast methods easier for package developers. It takes a data frame of predicted parameters pars and a function FUN which is to be evaluated at the parameters. This can either have the interface FUN(pars, ...) when the desired quantity can be predicted directly from the predicted parameters – or the interface FUN(at, pars, ...) if an additional argument at is needed. procast_setup takes care of suitable expanding at to the dimensions of pars and optionally setting up a (list of) function(s) to be returned.

Value

Either a data.frame of predictions (in case of multivariate forecasts, or if drop = FALSE, default) or a vector (in case of a univariate forecast and additionally drop = TRUE). Unless at is the character string "function" or "list" in which case a (list of) function(s) is returned.

Examples

## linear regression models (homoscedastic Gaussian response)
m <- lm(dist ~ speed, data = cars)

## medians on observed data
procast(m)
procast(m, drop = TRUE)

## probability integral transform (PIT) on observed data
procast(m, type = "probability", at = cars$dist)

## log-likelihood contributions
procast(m, type = "density", at = cars$dist, log = TRUE)

## log-likelihood sum
sum(procast(m, type = "density", at = cars$dist, log = TRUE))
logLik(m)


## medians on new data
nd <- data.frame(speed = c(10, 15, 20))
procast(m, newdata = nd)

## different quantile for each observation
procast(m, newdata = nd, at = c(0.25, 0.5, 0.75))

## all combinations of quantiles and observations
procast(m, newdata = nd, at = rbind(c(0.25, 0.5, 0.75)))

## function for computing quantiles (vectorized)
qnt1 <- procast(m, newdata = nd, at = "function")
## as before
qnt1(0.5)
qnt1(c(0.25, 0.5, 0.75))
qnt1(rbind(c(0.25, 0.5, 0.75)))

## list of functions
qnt2 <- procast(m, newdata = nd, at = "list")
qnt2[[1]]
qnt2[[1]](0.5)
qnt2[[1]](c(0.25, 0.5, 0.75))


[Package topmodels version 0.0-1 Index]