Damp {demest} | R 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)

[Package demest version 0.0.0.3.1 Index]