Package 'DIFM'

Title: Dynamic ICAR Spatiotemporal Factor Models
Description: Bayesian factor models are effective tools for dimension reduction. This is especially applicable to multivariate large-scale datasets. It allows researchers to understand the latent factors of the data which are the linear or non-linear combination of the variables. Dynamic Intrinsic Conditional Autocorrelative Priors (ICAR) Spatiotemporal Factor Models 'DIFM' package provides function to run Markov Chain Monte Carlo (MCMC), evaluation methods and visual plots from Shin and Ferreira (2023)<doi:10.1016/j.spasta.2023.100763>. Our method is a class of Bayesian factor model which can account for spatial and temporal correlations. By incorporating these correlations, the model can capture specific behaviors and provide predictions.
Authors: Hwasoo Shin [aut, cre], Marco Ferreira [aut]
Maintainer: Hwasoo Shin <[email protected]>
License: GPL (>= 2)
Version: 1.0
Built: 2024-11-09 06:39:44 UTC
Source: CRAN

Help Index

Dynamic ICAR Spatiotemporal Factor Models

Description

Bayesian factor models are effective tools for dimension reduction. This is especially applicable to multivariate large-scale datasets. It allows researchers to understand the latent factors of the data which are the linear or non-linear combination of the variables. Dynamic Intrinsic Conditional Autocorrelative Priors (ICAR) Spatiotemporal Factor Models 'DIFM' package provides function to run Markov Chain Monte Carlo (MCMC), evaluation methods and visual plots from Shin and Ferreira (2023)<doi:10.1016/j.spasta.2023.100763>. Our method is a class of Bayesian factor model which can account for spatial and temporal correlations. By incorporating these correlations, the model can capture specific behaviors and provide predictions.

Details

Package: BCFM2

Type: Package

Version: 1.0

Date: 2023-02-20

License: GPL(>=2)

Author(s)

Hwasoo Shin [aut, cre], Marco Ferreira [aut]

Maintainer: Hwasoo Shin <[email protected]>

References

Shin, H. and Ferreira, M. (2023). "Dynamic ICAR Spatiotemporal Factor Models." Spatial Statistics, 56, 100763

Lopes, H. and West, M. (2004). “Bayesian Model Assessment in Factor Analysis.” Statistica Sinica, 14, 41–67.

Prado, R., Ferreira, M. A. R., and West, M. (2021). Time Series: Modeling, Computation, and Inference. 2nd ed. Boca Raton: CRC Press.

Spatial dependence matrix of the factor loadings

Description

It computes the spatial covariance and precision matrix of the neighboring subregions using Intrinsice Autoregressive Conditional (ICAR) process.

Usage

buildH(areapoly, permutation = NA)

Arguments

areapoly

The polygon of the areas. We can obtain this through readOGR function from sp matrix.
permutation

Permutation order of the subregions

Details

The off-digonal values are -1 when two subregions are neighbors. Otherwise, we assign 0. The diagonal values are the sum of the values of its own row.

Value

A list of two matrices: Precision matrix H and the covariance matrix obtained through Moore-Penrose inverse of H.

Hyperparameters for DIFM

Description

Sets the hyperparameters to generate Gibbs sampler of DIFM

Usage

difm.hyp.parm(
  model.attributes,
  n.tau = 2.2,
  n.s2.tau = 0.1,
  n.sigma = 2.2,
  n.s2.sigma = 0.1,
  Hlist,
  Psi.size = 0.01
)

Arguments

model.attributes

Model attributes from difm.model.attributes
n.tau

Shape parameter for tau
n.s2.tau

Rate parameter for tau
n.sigma

Shape parameter for sigma squared
n.s2.sigma

Rate parameter for sigma squared
Hlist

Neighborhood matrix
Psi.size

The magnitude of covariance for the evolution matrix

Value

A list of hyperparameters of tau, W, sigma, and theta.

Initialize model attributes for DIFM

Description

It initialize the basic parameters and model attributes for DIFM

Usage

difm.model.attributes(data, n.iter, n.factors, G0)

Arguments

data

The dataset
n.iter

Number of iterations
n.factors

Number of factors to run DIFM
G0

The basic evolution matrix for one factor

Value

A list of number of timepoints, subregions, factors, matrix of evolution matrix, and matrix to extract common factors.

Run Dynamic ICAR Factors Model (DIFM), with C++ codes

Description

This function runs Dynamic ICAR factors Model (DIFM), simulated from C++ codes

Usage

DIFMcpp(model.attributes, hyp.parm, data, every = 1, verbose = TRUE)

Arguments

model.attributes

Model attributes from difm.model.attributes
hyp.parm

Hyperparameters from difm.hyp.parm
data

The dataset
every

Save every iterations to final result
verbose

Print out the iteration process

Value

The Gibbs sampler of DIFM

Run Dynamic ICAR Factors Model (DIFM)

Description

This function runs Dynamic ICAR factors Model (DIFM)

Usage

DIFMR(model.attributes, hyp.parm, data, every = 1, verbose = TRUE)

Arguments

model.attributes

Model attributes from difm.model.attributes
hyp.parm

Hyperparameters from difm.hyp.parm
data

The dataset
every

Save every iterations to final result
verbose

Print out the iteration process

Value

The Gibbs sampler of DIFM

Marginal predictive density

Description

It calculates the marginal density (Lewis and Raftery, 1997) from the DIFM sample using C++.

Usage

marginal_d_cpp(data, attributes, hyp_parm, Gibbs, burnin = -1L, verbose = TRUE)

Arguments

data

The dataset
attributes

Model attributes generated from difm.model.attributes.
hyp_parm

Hyperparameters generated from difm.hyp.parm.
Gibbs

Result of Gibbs sampler from DIFM function.
burnin

Burn-in period. If not specified, one tenths of the iterations will be the burn-in period.
verbose

Print out the process.

Value

A list of 4 items: Laplace-Metropolis predictive density of the given DIFM, integrated likelihood, the maximum of the predictive densities and determinant of the covariance matrix of the parameters.

Marginal predictive density

Description

It calculates the marginal density (Lewis and Raftery, 1997) from the DIFM sample using R.

Usage

marginal.d(
  data,
  model.attributes,
  hyp.parm,
  Gibbs,
  burnin = NA,
  verbose = TRUE
)

Arguments

data

The dataset
model.attributes

Model attributes generated from difm.model.attributes.
hyp.parm

Hyperparameters generated from difm.hyp.parm.
Gibbs

Result of Gibbs sampler from DIFM function.
burnin

Burn-in period. If not specified, one tenths of the iterations will be the burn-in period.
verbose

Print out the iteration process.

Value

Metropolis-Laplace estimator of the Marginal density

Order of permutation by the largest absolute value in each eigenvector

Description

It finds the vector of permutation to permute data by its largest absolute value in each eigenvector. It sets the order by specified number of factors, and the rest is ordered as they were.

Usage

permutation.order(data, n.factors)

Arguments

data

The dataset
n.factors

Number of factors

Value

The numeric vector of permutation

Permute the dataset by the largest absolute value in each eigenvector, and scale

Description

It finds the vector of permutation to permute data by its largest absolute value in each eigenvector. It sets the order by specified number of factors, and the rest is ordered as they were. The data is permuted, and if needed, scaled.

Usage

permutation.scale(data, n.factors, return.scale = FALSE)

Arguments

data

The dataset
n.factors

Number of factors
return.scale

Scale data after permutation

Value

The permuted and standardized dataset, either in matrix or array.

Credible interval plot of factor loadings

Description

The functions builds a column-wise plots of factor loadings. The parameters fixed at 1 are displayed with red dashed vertical lines.

Usage

plot_B.CI(
  Gibbs,
  true.val = NA,
  burnin = NA,
  permutation = NA,
  main.bool = TRUE,
  layout.dim = NA
)

Arguments

Gibbs

Result of Gibbs sampler from DIFM function
true.val

True values of factor loadings. If not available, NA.
burnin

Number of burn-in. If not specified, it uses the first tenths as burn-in period.
permutation

Permutation of variables. If not specified, no permutation.
main.bool

Add title of the plots.
layout.dim

Dimension of panel layout for multiple factor loadings. If not specificed, factor loadings plots are layout in one column.

Value

Factor loadings credible interval plots

Spatial plots of factor loadings

Description

The functions builds maps of factor loadings.

Usage

plot_B.spatial(
  Gibbs,
  areapoly,
  burnin = NA,
  permutation = NA,
  main.bool = TRUE,
  layout.dim = NA
)

Arguments

Gibbs

Result of Gibbs sampler from DIFM function.
areapoly

The polygon of the areas. We can obtain this through readOGR function from sp package.
burnin

Number of burn-in. If not specified, it uses the first tenths as burn-in period.
permutation

Permutation of variables. If not specified, no permutation.
main.bool

Add title of the plots.
layout.dim

Dimension of panel layout for multiple factor loadings. If not specificed, factor loadings plots are layout in one column.

Value

Factor loadings map plots

A credible interval plot of posterior of sigma squared

Description

It returns a credible interval plot of idiosyncratic variance, sigma squared. The lines are 95

Usage

plot_sigma2.CI(Gibbs, burnin = NA, permutation = NA, main.bool = TRUE)

Arguments

Gibbs

Result of Gibbs sampler from DIFM function.
burnin

Number of burn-in. If not specified, it uses the first tenths as burn-in period.
permutation

Permutation of variables. If not specified, no permutation.
main.bool

Add title of the plots.

Value

A credible interval plot of sigma squared

Credible interval plot of factor loadings variance

Description

It returns a credible interval plot of factor loadings covariance, tau. The lines are 95

Usage

plot_tau.CI(Gibbs, burnin = NA, true.val = NA, main.bool = TRUE)

Arguments

Gibbs

Result of Gibbs sampler from DIFM function.
burnin

Number of burn-in. If not specified, it uses the first tenths as burn-in period.
true.val

True values of tau. If not available, NA.
main.bool

Add title of the plots.

Value

Credible interval plot of tau

Credible interval plot of common factors

Description

The functions builds the plot of 95% confidence intervals of the common realizations, X. The black solid lines are the posterior mean and the dased lines are the 95% confidence intervals.

Usage

plot_X.CI(Gibbs, burnin = NA, main.bool = FALSE, layout.dim = NA)

Arguments

Gibbs

Result of Gibbs sampler from DIFM function.
burnin

Number of burn-in. If not specified, it uses the first tenths as burn-in period.
main.bool

Add title of the plots.
layout.dim

Dimension of panel layout for multiple common factors. If not specificed, common factor plots are layout in one column.

Value

Credible interval plots of common factors

Property crime in United States

Description

A subset of data of property crime per 100,000 people in western states from 1960 to 2019.

Usage

Property

Format

## 'Property' A data frame with 60 rows and 11 columns:

AZ

Arizona

CA

California

CO

Colorado

ID

Idaho

MT

Montana

NV

Nevada

NM

New Mexico

OR

Oregon

UT

Utah

WA

Washington

WY

Wyoming

...

Source

<https://www.disastercenter.com/crime/>

Violent crime data in United States

Description

A subset of data of violent crime per 100,000 people in western states from 1960 to 2019.

Usage

Violent

Format

## 'Violent' A data frame with 60 rows and 11 columns:

AZ

Arizona

CA

California

CO

Colorado

ID

Idaho

MT

Montana

NV

Nevada

NM

New Mexico

OR

Oregon

UT

Utah

WA

Washington

WY

Wyoming

...

Source

<https://www.disastercenter.com/crime/>

Westen states in United States

Description

A sp map data of the western states in United States

Usage

WestStates

Format

## 'WestStates' A SpatialPolygonsDataFrame data of the western states in United States

FID

The number ID of the western states

State_Code

Abbreviations of the state names

State_Name

Names of the states

A SpatialPolygonsDataFrame data of the western states in United States

Source

<https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html>