Damp: Specify the amount of damping in a DLM prior.

View source: R/SpecPrior-generators.R

DampR Documentation

Specify the amount of damping in a DLM prior.

Description

By default, the level term in a local level model and the trend term in a linear trend model are 'damped'. The level term or trend term are pulled towards 0. The amount of damping can be specified by the user, or can be estimated from the data.

Usage

Damp(coef = NULL, shape1 = 2, shape2 = 2, min = 0.8, max = 1)

Arguments

coef

A number between 0 and 1.

shape1

A positive number. Defaults to 2.

shape2

A positive number. Defaults to 2.

min

A number between 0 and 1.

max

A number between min and 1.

Details

With a prior for a main effect, in a local level model, the level term has the form

level[j] ~ damp * level[j-1] + errorLevel[j],

and in a linear trend model, the trend term has the form

trend[j] ~ damp * trend[j-1] + errorTrend[j].

With a prior for an interaction, in a local level model, the level term has the form

level[k,l] ~ damp * level[k-1,l] + errorLevel[k,l].

and in linear trend model, the trend term has the form

trend[k,l] ~ damp * trend[k-1,l] + errorTrend[k,l]

(See the documentation for function DLM for an explanation of the k,l subscripts.)

Values of for damp are restricted to the range 0 <= damp <= 1. In linear trend models, including a damping term with a value near 1 typically results in more accurate forecasts (Hyndman et al 2008). There are exceptions, however: for instance, damping of the trend for the time effect is probably not appropriate in mortality forecasts for developed countries (Oeppen and Vaupel 2002). Damping is also not necessary appropriate in local level models.

The user can set the level of damping by providing a value for the coef argument. Alternatively, an appropriate value can be inferred from the data, using a beta prior on the transformed parameter (damp - min)/(max - min). The beta prior is specified using parameters shape1 and shape1. The default values give a boundary-avoiding prior, confined to the range (min, max), with min defaulting to 0.8 and max defaulting to 1. (See Gelman et al 2014, pp313-318, for a definition of boundary-avoiding priors.) Setting shape1 = 1 and shape2 = 1 gives a uniform prior on the range (min, max).

Setting the damp argument to NULL in function DLM turns off damping.

Value

An object of class Damp.

References

Hyndman, R., Koehler, A. B., Ord, J. K., & Snyder, R. D. (2008). Forecasting with' exponential smoothing: the state space approach. Springer.

Oeppen, J., & Vaupel, J. W. (2002). Broken limits to life expectancy. Science, 296(5570), 1029-1031.

See Also

Damp is used in calls to function DLM

Examples

## default
Damp()

## known value
Damp(coef = 0.95)

## estimate, but restrict to values between 0.85 and 0.95
Damp(min = 0.85, max = 0.95)

## uniform prior on the range (0, 1)
Damp(min = 0, max = 1, shape1 = 1, shape2 = 1)

## informative prior favouring high values, but
## not ruling out any value between 0 and 1
Damp(min = 0, max = 1, shape1 = 9, shape2 = 1)

StatisticsNZ/demest documentation built on Nov. 2, 2023, 7:56 p.m.