dstm_eof: Dynamic spatio-temporal model with EOFs

Description Usage Arguments Details References See Also Examples

View source: R/dstm.R

Description

Fits a dynamic spatio-temporal model using empirical orthogonal functions (EOFs). The model does not require the spatial locations because the process model is based on the principal components of the data matrix. Three broad model types are supported:

1. RW: A random walk model for which the process matrix is the identity.

2. AR: An auto-regressive model for which the process matrix is diagonal and its elements are estimated.

3. Dense: A model in which the process matrix is a dense, estimated matrix.

For each broad model type, users can specify a variety of options including the size of the state space, the form of the process error, and whether to sample the observation error. Users can specify prior distributions for all sampled quantities using the 'params' argument.

Each model type mentioned above is a dynamic linear model (DLM), and the state vectors can be estimated using the forward filtering backward sampling algorithm. The other parameters are estimated with conditionally conjugate updates.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
dstm_eof(
  Y,
  proc_model = "Dense",
  P = 4L,
  proc_error = "IW",
  n_samples = 1L,
  sample_sigma2 = TRUE,
  verbose = FALSE,
  params = NULL
)

Arguments

Y

(numeric matrix) S by T data matrix containing the response variable at S spatial locations and T time points. The t-th column (NOT row) corresponds to the t-th observation vector.

proc_model

(character string) Process model: one of "RW" (identity process matrix), "AR" (diagonal process matrix), or "Dense" (dense process matrix).

P

(integer) Number of EOFs or, in other words, the state space size.

proc_error

(character string) Process error: "IW" (inverse-Wishart) or "Discount" (discount factor).

n_samples

(numeric scalar) Number of samples to draw

sample_sigma2

(logical) Whether to sample the variance of the iid observation error.

verbose

(logical) Whether to print additional information; e.g., iteration in sampling algorithm.

params

(list) List of hyperparameter values; see details.

Details

This section explains how to specify custom hyperparameters using the 'params' argument. For each distribution referenced below, we use the scale parameterization found on the distribution's Wikipedia page. You may specify the following as named elements of the 'params' list:

m_0: (numeric vector) The prior mean of the state vector at time zero (θ_0).

C_0: (numeric matrix) The prior variance-covariance matrix of the state vector at time zero (θ_0).

alpha_sigma2, beta_sigma2: (numeric scalars) The inverse-Gamma parameters (scale parameterization) of the prior distribution on the observation error (σ^2).

sigma2: (numeric scalar) The value to use for the observation error (σ^2) if 'sample_sigma2' = FALSE.

mu_G: (numeric matrix) The prior mean for the process matrix G. If 'proc_model' = "AR", then 'mu_G' must be a diagonal matrix. If 'proc_model' = "Dense", then 'mu_G' has no constraints.

Sigma_G: (numeric matrix) The prior variance-covariance matrix for the process matrix. If proc_model = "AR", then Sigma_G should be P by P and is the variance-covariance matrix for diag(G). If proc_model = "Dense", then Sigma_G should be P^2 by P^2 and is the variance-covariance matrix for vec(G).

alpha_lambda, beta_lambda: (numeric scalars) The inverse-Gamma parameters (scale parameterization) of the prior distribution on λ = (1 - δ) / δ, where δ is the discount factor.

scale_W: (numeric matrix) The scale matrix for the inverse-Wishart prior distribution on the variance-covariance matrix of the process error ('W').

df_W: (numeric scalar) The degees of freedom for the inverse-Wishart prior distribution on the variance-covariance matrix of the process error ('W').

References

Cressie, N., and Wikle, C. K. (2011), Statistics for spatio-temporal data, John Wiley and Sons, New York, ISBN:978-0471692744.

Fruhwirth-Schnatter, S. (1994), “Data Augmentation and Dynamic Linear Models,” Journal of Time Series Analysis, 15, 183–202, <doi:10.1111/j.1467-9892.1994.tb00184.x>.

Petris, G., Petrone, S., and Campagnoli, P. (2009), Dynamic Linear Models with R, useR!, Springer-Verlag, New York, ISBN:978-0387772370, <doi:10.1007/b135794>.

See Also

[dstm_ide]

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Load example data
data("ide_standard")

# Illustrate methods
rw_model <- dstm_eof(ide_standard, proc_model="RW", verbose=TRUE)
summary(rw_model)
predict(rw_model) 

# Other model types
dstm_eof(ide_standard, proc_model="AR") # Diagonal process matrix
dstm_eof(ide_standard, proc_model="Dense") # Dense process matrix

# Specify hyperparameters
P <- 4
dstm_eof(ide_standard, P=P,
         params=list(m_0=rep(1, P), C_0=diag(0.01, P),
                     scale_W=diag(P), df_W=100))

Example output

Filtering sample number 1
Drawing sample number 1
Summary for dstm object `rw_model`
Process model: `RW`
Process error: `IW`
sigma2 was sampled

List elements (in order) are as follows:
F theta sigma2 W scalar_params other_params 

Scalar Objects:
  sigma2 
1.619865 


Matrices/Arrays:
       class dim 1 dim 2 dim 3
F     matrix   400     4  <NA>
theta  array     4    21     1
W      array     4     4     1


Lists:
              length
scalar_params      8
other_params       3
               [,1]
  [1,]  3.284962030
  [2,]  3.307853157
  [3,]  1.482641284
  [4,]  0.054946663
  [5,]  0.669898889
  [6,] -2.193939320
  [7,] -0.176620316
  [8,] -0.827541332
  [9,]  0.112101241
 [10,] -2.848499045
 [11,] -1.349714481
 [12,] -0.054910956
 [13,]  0.337912450
 [14,] -0.234563372
 [15,] -0.104940009
 [16,] -1.517713252
 [17,] -2.834050804
 [18,]  1.270074454
 [19,]  0.013484303
 [20,] -3.014239627
 [21,] -1.439947608
 [22,] -2.684747662
 [23,]  0.434022791
 [24,]  1.256956773
 [25,]  0.200717522
 [26,]  0.531194513
 [27,] -2.225444934
 [28,] -1.668305134
 [29,]  0.409953490
 [30,]  0.176036688
 [31,] -1.268107021
 [32,]  0.529993753
 [33,] -0.229861243
 [34,]  3.057387895
 [35,]  0.228581368
 [36,] -1.601772093
 [37,] -3.058080005
 [38,] -3.144300479
 [39,] -1.146278757
 [40,] -0.980604559
 [41,]  2.103787424
 [42,] -0.602829448
 [43,]  2.106574811
 [44,] -1.290764028
 [45,]  3.178041244
 [46,]  1.523313469
 [47,]  0.967862944
 [48,] -1.761596902
 [49,]  0.741407156
 [50,] -1.635739458
 [51,]  0.811493184
 [52,]  2.158060209
 [53,]  1.551575261
 [54,] -1.380810949
 [55,] -0.758755533
 [56,] -2.138136817
 [57,] -2.802102601
 [58,] -0.445022952
 [59,] -3.458409045
 [60,] -1.913258217
 [61,] -1.144900661
 [62,] -1.245914486
 [63,] -1.478814398
 [64,]  1.247783180
 [65,] -1.721106621
 [66,] -1.151701671
 [67,] -0.321615673
 [68,] -0.750090936
 [69,] -0.704207313
 [70,]  2.302439396
 [71,]  1.139631344
 [72,]  0.580318338
 [73,]  2.553063656
 [74,] -2.253461810
 [75,] -3.182276114
 [76,] -2.915379992
 [77,] -1.863181066
 [78,] -2.421532614
 [79,] -2.669815700
 [80,] -2.420047896
 [81,] -0.408862735
 [82,] -2.379370060
 [83,] -0.060068364
 [84,] -2.250674832
 [85,] -1.374255064
 [86,] -0.468903803
 [87,] -2.769497334
 [88,]  0.863035625
 [89,] -4.576183605
 [90,] -2.226621281
 [91,] -0.152690350
 [92,] -0.547465863
 [93,]  0.164510139
 [94,] -1.216241372
 [95,] -1.770598836
 [96,] -3.309338529
 [97,] -0.944715215
 [98,] -1.647317741
 [99,] -1.859170979
[100,] -3.570809556
[101,]  0.254281108
[102,] -2.503893567
[103,] -2.237021669
[104,] -0.382431217
[105,] -0.416896095
[106,] -1.979857893
[107,] -0.036145656
[108,] -1.822196669
[109,] -0.646490230
[110,] -2.689350682
[111,]  0.395642124
[112,]  0.406872007
[113,] -1.705475987
[114,] -0.735759164
[115,] -2.155785672
[116,] -3.148595838
[117,] -3.683365802
[118,] -7.053681572
[119,] -2.476835099
[120,] -2.905906258
[121,] -0.987452742
[122,]  0.405497887
[123,] -5.127466349
[124,] -2.866526278
[125,] -0.856426489
[126,] -2.608739876
[127,] -1.982451606
[128,] -1.806588092
[129,] -3.162274423
[130,] -3.272993535
[131,] -1.053514719
[132,] -1.494115110
[133,] -1.396926962
[134,] -2.573200770
[135,] -1.506224006
[136,] -3.318308348
[137,] -1.863121860
[138,]  0.953326052
[139,] -0.286101870
[140,] -0.995581126
[141,] -1.388102740
[142,] -3.257509930
[143,] -3.954715168
[144,] -1.264446054
[145,] -3.225291758
[146,] -1.605699106
[147,] -4.237842399
[148,] -0.599195213
[149,] -1.865230480
[150,] -3.819075892
[151,] -0.990173692
[152,] -0.606697581
[153,]  0.761851372
[154,] -1.142932298
[155,] -1.938053293
[156,] -1.973112914
[157,] -1.389763702
[158,] -4.052721738
[159,] -1.077721805
[160,] -3.590596037
[161,] -1.935993605
[162,] -2.305747810
[163,] -1.917162493
[164,] -2.684496509
[165,] -2.286804811
[166,]  1.456838996
[167,] -0.267634059
[168,] -1.117095144
[169,] -0.190320409
[170,] -3.668677809
[171,] -2.137377736
[172,] -0.007572449
[173,] -0.545373539
[174,] -2.002888618
[175,] -0.736700775
[176,] -1.265387181
[177,]  0.418615394
[178,] -1.837461853
[179,]  0.477502863
[180,]  0.529502780
[181,] -3.107095308
[182,] -2.094852972
[183,] -4.006200387
[184,] -1.006892293
[185,] -3.140007501
[186,] -3.617804239
[187,] -0.567196039
[188,] -3.268438773
[189,] -3.086287853
[190,] -5.571271697
[191,] -2.318226424
[192,] -3.468484742
[193,] -0.293138755
[194,]  0.861143180
[195,] -3.097198959
[196,] -2.519046059
[197,] -1.779349620
[198,] -0.812769965
[199,] -0.775158574
[200,]  0.797683708
[201,] -2.791708067
[202,] -4.114104731
[203,] -3.219031399
[204,] -4.217679089
[205,] -0.507622944
[206,]  0.063469217
[207,] -0.105791899
[208,] -2.958457037
[209,] -4.757157147
[210,] -3.672867070
[211,] -5.284593966
[212,] -2.878194835
[213,] -1.624409445
[214,]  0.485944514
[215,] -2.834541494
[216,]  0.302233316
[217,] -3.102499028
[218,] -1.869682265
[219,] -0.826814106
[220,] -2.399192435
[221,] -5.024386929
[222,] -4.700268428
[223,] -3.781733472
[224,] -3.022986721
[225,] -3.032688443
[226,] -1.665045106
[227,] -3.124585856
[228,] -1.569786544
[229,] -5.397335106
[230,] -5.939813237
[231,] -6.775466132
[232,] -4.163096526
[233,] -2.644823661
[234,] -3.806804150
[235,]  0.502994456
[236,] -2.513734679
[237,] -2.695850505
[238,] -1.749353167
[239,] -1.446767857
[240,]  0.132476876
[241,] -4.681230243
[242,] -5.499345241
[243,] -6.253685390
[244,] -6.402793542
[245,] -4.971456196
[246,] -4.546044429
[247,] -1.878202159
[248,] -0.074282488
[249,] -5.771818929
[250,] -5.456141353
[251,] -7.308710994
[252,] -6.795527493
[253,] -7.947857940
[254,] -3.088434411
[255,] -3.550761064
[256,] -2.876073617
[257,] -3.061259829
[258,] -0.914076450
[259,] -1.498932289
[260,] -0.445003921
[261,] -3.806286191
[262,] -6.192849870
[263,] -5.392784622
[264,] -4.674336192
[265,] -6.219449471
[266,] -3.099657879
[267,] -3.079123515
[268,] -2.880730339
[269,] -4.066125896
[270,] -5.310884335
[271,] -6.974579982
[272,] -4.950882372
[273,] -5.895720090
[274,] -1.970299511
[275,] -1.371501281
[276,] -1.980940288
[277,] -2.750841252
[278,] -2.913027643
[279,] -0.273060487
[280,] -2.725546415
[281,] -4.455682392
[282,] -3.401106289
[283,] -5.936949916
[284,] -4.155314025
[285,] -5.935803923
[286,] -3.829298011
[287,]  0.199601951
[288,] -4.801914679
[289,] -2.229797531
[290,] -2.726223806
[291,] -5.866195360
[292,] -5.726444573
[293,] -5.426537383
[294,] -5.278844453
[295,] -2.333067401
[296,] -1.772633087
[297,] -1.592605267
[298,] -2.178488122
[299,]  0.447832280
[300,] -0.483104611
[301,] -4.178398376
[302,] -3.083884154
[303,] -5.098021553
[304,] -3.781725347
[305,] -3.816014099
[306,] -1.392753759
[307,] -0.890064071
[308,] -1.445376227
[309,] -0.301124676
[310,] -3.631482286
[311,] -2.366351417
[312,] -6.918445215
[313,] -5.258912082
[314,] -1.528291456
[315,] -3.943159401
[316,] -2.531973408
[317,] -2.008854542
[318,] -3.292577927
[319,] -1.780391176
[320,] -1.196615578
[321,] -3.289464733
[322,] -1.892197694
[323,] -3.284330375
[324,] -0.651047287
[325,] -3.101769107
[326,] -1.468500874
[327,] -2.332699965
[328,] -1.997166819
[329,] -0.606159681
[330,] -2.536114401
[331,] -1.151453858
[332,] -2.842960439
[333,] -3.735279204
[334,] -4.233795742
[335,] -3.760382372
[336,] -0.732737397
[337,] -0.823455035
[338,] -0.823901276
[339,] -2.822161979
[340,] -1.328807032
[341,] -1.906989252
[342,]  0.230669542
[343,] -1.704397237
[344,] -3.043059677
[345,] -0.652691007
[346,] -4.093069288
[347,] -2.723330909
[348,] -1.743464507
[349,] -0.216440257
[350,]  0.766168562
[351,] -0.698250550
[352,] -1.112868111
[353,] -2.842437319
[354,] -1.861778339
[355,] -0.010365232
[356,]  0.300582179
[357,] -1.696389589
[358,] -1.931239056
[359,] -1.947450984
[360,] -2.618810417
[361,] -0.827885439
[362,] -0.431840056
[363,]  0.630697714
[364,] -2.485658927
[365,] -3.136034772
[366,]  0.332571160
[367,] -0.269129070
[368,] -2.287241767
[369,] -3.335577605
[370,] -0.105817855
[371,] -1.775992191
[372,]  0.137526722
[373,]  0.586077207
[374,] -1.195028863
[375,] -1.216693307
[376,] -2.722734905
[377,] -0.680799818
[378,] -0.498028792
[379,] -2.157960424
[380,]  0.794121580
[381,] -2.237152836
[382,] -2.697171482
[383,] -1.272088765
[384,]  0.610730086
[385,]  0.674064910
[386,] -0.486259535
[387,] -2.737482733
[388,]  0.434062315
[389,] -2.251885750
[390,] -2.099372636
[391,] -1.503690547
[392,] -0.739714358
[393,] -1.636649308
[394,] -1.728176153
[395,] -1.096797277
[396,]  0.815293621
[397,]  0.917871200
[398,] -0.071789774
[399,]  0.772188797
[400,]  1.430139187
Summary for dstm object `x`
Process model: `AR`
Process error: `IW`
sigma2 was sampled

List elements (in order) are as follows:
F theta G sigma2 W scalar_params other_params 

Scalar Objects:
  sigma2 
1.604522 


Matrices/Arrays:
       class dim 1 dim 2 dim 3
F     matrix   400     4  <NA>
theta  array     4    21     1
G      array     4     4     1
W      array     4     4     1


Lists:
              length
scalar_params      8
other_params       3
Summary for dstm object `x`
Process model: `Dense`
Process error: `IW`
sigma2 was sampled

List elements (in order) are as follows:
F theta G sigma2 W scalar_params other_params 

Scalar Objects:
  sigma2 
1.623388 


Matrices/Arrays:
       class dim 1 dim 2 dim 3
F     matrix   400     4  <NA>
theta  array     4    21     1
G      array     4     4     1
W      array     4     4     1


Lists:
              length
scalar_params      8
other_params       3
Summary for dstm object `x`
Process model: `Dense`
Process error: `IW`
sigma2 was sampled

List elements (in order) are as follows:
F theta G sigma2 W scalar_params other_params 

Scalar Objects:
  sigma2 
1.594611 


Matrices/Arrays:
       class dim 1 dim 2 dim 3
F     matrix   400     4  <NA>
theta  array     4    21     1
G      array     4     4     1
W      array     4     4     1


Lists:
              length
scalar_params      8
other_params       3

ideq documentation built on Dec. 20, 2019, 1:07 a.m.