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

In StatisticsNZ/demest: Bayesian Demographic Estimation and Forecasting

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))

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