gmrfdpgrow: Bayesian instrinsic Gaussian Markov Random Field model for dependent time-indexed functions

Description

Estimates a collection of time-indexed functions under intrinsic Gaussian Markov random field prior formulations where a Dirichlet process mixture allows sub-groupings of the functions to share the same iGMRF precision parameter. The iGMRF formulation supports any number of additive precision terms, expressing either or both of multiple trend and seasonality.

Usage

gmrfdpgrow(y, ipr, q_order, q_type, q_shape, q_rate, tau_shape, tau_rate,
  dp_shape, dp_rate, M_init, n.iter, n.burn, n.thin, progress, jitter,
  kappa_fast)

Arguments

A multivariate continuous response, specified as an N x T matrix, where N denotes the number of functions and T, the number of time points per function. Intermittent missing-at-random values are allowed and will be est

ipr

An optional input vector of inclusion probabilities for each observation unit in the case the observed data were acquired through an informative sampling design, so that unbiased inference about the population requires adjustments to the observed sample

q_order

An integer vector of length K to select the order for each iGMRF precision term. e.g. If the first term is a RW2 and there is a second is a 3-month seasonality term, where the time points are indexed by month, then q_order = c(2,3)

q_type

A vector of length K, the number of iGMRF precision terms, with each entry indicating whether the associated term is a trend ("tr") or seasonality ("sn") term. So all entries must be one of c("tr","sn")

q_shape

The value (in (0,infty)) for the shape hyperparameter for the Gamma base distribution for the iGMRF scale parameters, kappa_star(k,m), where k denotes the term and m, the cluster. Defaults to q_shape = 0.3

q_rate

The rate parameter of the Gamma base distribution on kappa_star.
Defaults to q_rate = 0.0005.

tau_shape

The value (in (0,infty)) for the shape hyperparameter for the Gamma prior on the error
precision parameter. Defaults to tau_shape = 1.0.

tau_rate

The rate parameter of the Gamma prior distribution on tau_e.
Defaults to tau_rate = 1.

dp_shape

The shape parameter for the Gamma prior on the DP concentration parameter,
conc. Defaults to dp_shape = 1.

dp_rate

The rate parameter for the Gamma prior on the DP concentration parameter,
conc. Defaults to dp_rate = 1.

M_init

Starting number of clusters of nrow(y) units to initialize sampler.
Defaults to M_init = nrow(y).

n.iter

Total number of MCMC iterations.

n.burn

Number of MCMC iterations to discard.
gmrfdpgrow will return (n.iter - n.burn) posterior samples.

n.thin

Gap between successive sampling iterations to save.

progress

A boolean value denoting whether to display a progress bar during model execution.
Defaults to progress = true.

jitter

A scalar double indicating amount of jitter to subract from the posterior
rate and shape hyperparameters of tau_e to stabilize computation.
Defaults to jitter = 0.0.

kappa_fast

Boolean for whether to generate rate hyperparameter from full conditionals
versus joint Gaussian (on random effects, bb, given kappa.  The
former is faster, but numerically less stable.
Defaults to kappa_fast = FALSE

`Value`

S3 gmrfdpgrow object, for which many methods are available to return and view results.
       Generic functions applied to an object, res of class gmrfdpgrow, includes:
plot(res)returns results plots, including fit functions versus data and allocation
                 of fitted functions into clusters
samples(res)contains (n.iter - n.burn) posterior sampling iterations
            for every model parameter
resid(res)contains the model residuals.

`References`

T. D. Savitsky and D. Toth (2014) Bayesian Non-parametric Models for Collections of Time-
    indexed Functions. submitted to: JRSS Series A (Statistics in Society).

T. D. Savitsky (2014) Bayesian Non-parametric Functional Mixture
    Estimation for Time-indexed data. submitted to: Annals of Applied Statistics.

T. D. Savitsky (2014) Bayesian Non-Parametric Mixture Estimation for Time-Indexed Functional
    Data for R. Submitted to: Journal of Statistical Software.

`See Also`

gmrfdpgrow

`Examples`

Run this code{
library(growfunctions)

## load the monthly employment count data for a collection of
## U.S. states from the Current
## Population Survey (cps)
data(cps)
## subselect the columns of N x T, y, associated
## with the years 2008 - 2013
## to examine the state level employment levels
## during the "great recession"
y_short   <- cps$y[,(cps$yr_label %in% c(2008:2013))]

## Run the DP mixture of iGMRF's to estimate posterior
## distributions for model parameters
## Under default RW2(kappa) = order 2 trend
## precision term
## Run for 1500 iterations, with half as burn-in for a
## more useful (converged) result.
res_gmrf            <- gmrfdpgrow(y = y_short,
                                     n.iter = 40,
                                     n.burn = 20,
                                     n.thin = 1)

## 2 plots of estimated functions: 1. faceted by cluster and fit;
## 2.  data for experimental units.
## for a group of randomly-selected functions
fit_plots_gmrf      <- cluster_plot( object = res_gmrf,
                                     units_name = "state",
                                     units_label = cps$st,
                                     single_unit = FALSE,
                                     credible = TRUE )
}
Run the code above in your browser using DataLab