DLM {demest} | R Documentation

## Specify a Dynamic Linear Model (DLM) prior.

### Description

Specify a prior for main effects or interactions in which units that are neighbours are more strongly correlated than units that are distant from each other. Dynamic linear models were developed for time series, but are often appropriate for non-time dimensions, such as age.

### Usage

    DLM(
      along = NULL,
      level = Level(),
      trend = Trend(),
      damp = Damp(),
      season = NULL,
      covariates = NULL,
      error = Error()
    )

### Arguments

`along` | Name of a dimension.
`level` | An object of class `Level` specifying the prior for `errorLevel` or `NULL`. `level` can be `NULL` only when `trend` is non-`NULL`.
`trend` | An object of class `Trend` (the default) or `NULL`. If `trend` is `NULL`, then `DLM` produces local level model; otherwise `DLM` produces a linear trend model.
`damp` | An object of class `Damp` (the default) or `NULL`. If `damp` is `NULL` the level or trend terms are not damped.
`season` | An object of class `Season` or `NULL` (the default). If `season` is `NULL`, the prior does not include a seasonal effect.
`covariates` | An object of class `Covariates` or `NULL` (the default). If `covariates` is `NULL`, the prior does not include covariates.
`error` | An object of class `Error`.

### Details

When applied to a main effect, the prior specified by `DLM` has the form

`parameter[j] = level[j] + season[j] + covariates[j] + error[j].`

When applied to an interaction, a DLM prior contains a separate series along one dimension (typically a time dimension) for each combination of values for the remaining series. Using `k` to index location on the "along" dimension, and `l` to index location on the remaining dimensions, the prior has the form

`parameter[k,l] = level[k,l] + season[k,l] + covariates[k,l] + error[k,l].`

For instance, if `parameter` is a region:time interaction involving 10 regions and 30 periods, and the "along" dimension is time, then `k=1,...,30` and `l=1,...,10`. If `parameters` is an age:sex:region interaction involving 101 age groups, 2 sexes, and 10 regions, and the "along" dimension is age, then `k=1,...,101` and `l = 1,...,20`.

Season and covariate terms are specified using functions `Season` and `Covariates`. Both are optional. Error terms are specified using function `Error`.

### Value

An object of class `SpecDLM`.

### The "along" dimension

If the "along" dimension is not specified, then `DLM` looks for a dimension with `dimtype` `"time"`. If it does not find one, it looks for a dimension with dimtype `"age"`.

A dimension with dimtype `"state"` can be used as an `"along"` dimension. Doing so probably make senses if the dimension measures a qualitative variable such as income or years of schooling. It probably does not makes sense if the dimension measures a qualitative variable such as region or occupation.

### The local level model

In a local level model, the level term follows a random walk. With a main effect,

`level[j] = damp * level[j-1] + errorLevel[j],`

and with an interaction,

`level[k,l] = damp * level[k-1,l] + errorLevel[k,l],`

where `0 < damp <= 1`. The documentaion for function `Damp` describes the role played by the `damp` term.

### The linear trend model

In a linear level model, the level term follows a random walk but with an underlying trend. The trend term itself follows a random walk, implying that it can change magnitude or direction. With a main effect,

`level[j] = level[j-1] + trend[j-1] + errorLevel[j]` `trend[j] = trend[j-1] + errorTrend[j],`

and with an interaction,

`level[k,l] = level[k-1,l] + trend[k-1,l] + errorLevel[k,l]` `trend[k,l] = damp * trend[k-1,l] + errorTrend[k,l].`

where `0 < damp <= 1`. The documentaion for function `Damp` describe the role played by the `damp` term.

If `level` is `NULL`, then the model does not include `errorLevel`. This can be a useful simplification in situations where there is a trend in the data, but the full linear trend model is not converging properly.

### Error terms

The error term for the level, `errorLevel`, has the form

`errorLevel[j] ~ N(0, scaleLevel^2)`

or

`errorLevel[k,l] ~ N(0, scaleLevel^2)`.

Similarly, the error term for the trend, `errorTrend`, has the form

`errorLevel[j] ~ N(0, scaleLevel^2)`

or

`errorLevel[k,l] ~ N(0, scaleLevel^2)`.

`scaleLevel` and `scaleTrend` both have half-t priors. Non-default versions of these can be specified using function `HalfT`.

### References

Petris, G., Petrone, S., & Campagnoli, P. (2009). Dynamic Linear Models with R. Springer.

Prado, R., & West, M. (2010). Time Series: Modeling, Computation, and Inference. CRC Press.

### See Also

`ExchFixed` and `Exch` specify exchangeable in which the order of the units conveys no information about the correlations between them. `DLM`, `ExchFixed`, and `Exch` are usually called as part of a call to function `Model`.

### Examples

    ## damped linear trend model with no seasonal effect
    ## and no covariates
    DLM()

    ## damped local level model with no seasonal effect
    ## and no covariates
    DLM(trend = NULL)

    ## local level model with no damping, no seasonal effect,
    ## and no covariates
    DLM(trend = NULL, damp = NULL)

    ## damped linear trend model with seasonal effect
    ## and no covariates
    DLM(season = Season(n = 4))

    ## linear trend model with covariates, but no damping
    ## and no seasonal effects
    gdp.data <- data.frame(year = 2000:2016,
                           gdp = rnorm(17))
    gdp.covariates <- Covariates(mean ~ gdp, data = gdp.data)
    DLM(damp = NULL, covariates = gdp.covariates)

    ## robustified damped linear trend model
    DLM(error = Error(robust = TRUE))

[Package demest version 0.0.0.3.1 Index]