Skip to contents
library(diseasy)
#> Loading required package: diseasystore
#> 
#> Attaching package: 'diseasy'
#> The following object is masked from 'package:diseasystore':
#> 
#>     diseasyoption

Overview

The DiseasyRegions module defines the regional scope for the models. In addition, it provides a common place to define the demography available for those areas, and the adjacency between regions within the areas.

Data structure

DiseasyRegions uses three inputs:

  • area: a character vector defining the selected regional scope.
  • demography: a data.frame with one “region” column, optional stratification columns, and one population column.
  • adjacency: a data.frame describing connectedness between pairs of regions (see the Regional adjacency section for further details).

The demography data must include the columns region and population. Any additional columns are treated as stratification variables.

demography_nordic
#>     region age population
#> 1       DK   0      60965
#> 2       DK   1      61357
#> 3       DK   2      61663
#> 4       DK   3      62128
#> 5       DK   4      61148
#> 6       DK   5      59481
#> 7       DK   6      58756
#> 8       DK   7      59589
#> 9       DK   8      61292
#> 10      DK   9      64165
#> 11      DK  10      66269
#> 12      DK  11      67372
#> 13      DK  12      68192
#> 14      DK  13      68277
#> 15      DK  14      68204
#> 16      DK  15      67902
#> 17      DK  16      68205
#> 18      DK  17      68237
#> 19      DK  18      69251
#> 20      DK  19      71412
#> 21      DK  20      72441
#> 22      DK  21      72552
#> 23      DK  22      74181
#> 24      DK  23      75906
#> 25      DK  24      78371
#> 26      DK  25      81048
#> 27      DK  26      80210
#> 28      DK  27      79829
#> 29      DK  28      78728
#> 30      DK  29      77063
#> 31      DK  30      75972
#> 32      DK  31      74085
#> 33      DK  32      72119
#> 34      DK  33      70817
#> 35      DK  34      69502
#> 36      DK  35      67719
#> 37      DK  36      66166
#> 38      DK  37      66057
#> 39      DK  38      66304
#> 40      DK  39      67696
#> 41      DK  40      69559
#> 42      DK  41      71136
#> 43      DK  42      71529
#> 44      DK  43      72436
#> 45      DK  44      76776
#> 46      DK  45      79152
#> 47      DK  46      78326
#> 48      DK  47      79877
#> 49      DK  48      80505
#> 50      DK  49      78296
#> 51      DK  50      76267
#> 52      DK  51      77447
#> 53      DK  52      81109
#> 54      DK  53      86471
#> 55      DK  54      87573
#> 56      DK  55      84710
#> 57      DK  56      82385
#> 58      DK  57      79126
#> 59      DK  58      75382
#> 60      DK  59      73669
#> 61      DK  60      71600
#> 62      DK  61      69838
#> 63      DK  62      69245
#> 64      DK  63      68759
#> 65      DK  64      67769
#> 66      DK  65      66030
#> 67      DK  66      65196
#> 68      DK  67      64169
#> 69      DK  68      62436
#> 70      DK  69      62102
#> 71      DK  70      61906
#> 72      DK  71      62662
#> 73      DK  72      65083
#> 74      DK  73      66916
#> 75      DK  74      64800
#> 76      DK  75      60558
#> 77      DK  76      55021
#> 78      DK  77      49722
#> 79      DK  78      44103
#> 80      DK  79      39325
#> 81      DK  80      36076
#> 82      DK  81      33233
#> 83      DK  82      30434
#> 84      DK  83      27360
#> 85      DK  84      24130
#> 86      DK  85      20954
#> 87      DK  86      18226
#> 88      DK  87      15919
#> 89      DK  88      13565
#> 90      DK  89      11548
#> 91      DK  90       9934
#> 92      DK  91       8122
#> 93      DK  92       6646
#> 94      DK  93       5307
#> 95      DK  94       4231
#> 96      DK  95       3331
#> 97      DK  96       2629
#> 98      DK  97       1911
#> 99      DK  98       1399
#> 100     DK  99       1036
#> 101     DK 100       1637
#> 102     FI   0      46122
#> 103     FI   1      46964
#> 104     FI   2      49539
#> 105     FI   3      52436
#> 106     FI   4      55324
#> 107     FI   5      57712
#> 108     FI   6      59248
#> 109     FI   7      60642
#> 110     FI   8      61805
#> 111     FI   9      62769
#> 112     FI  10      63146
#> 113     FI  11      62577
#> 114     FI  12      61846
#> 115     FI  13      61545
#> 116     FI  14      61084
#> 117     FI  15      60577
#> 118     FI  16      60052
#> 119     FI  17      58971
#> 120     FI  18      58747
#> 121     FI  19      59307
#> 122     FI  20      60085
#> 123     FI  21      60441
#> 124     FI  22      61454
#> 125     FI  23      63500
#> 126     FI  24      65727
#> 127     FI  25      68269
#> 128     FI  26      69596
#> 129     FI  27      70974
#> 130     FI  28      71845
#> 131     FI  29      71954
#> 132     FI  30      71423
#> 133     FI  31      70573
#> 134     FI  32      69267
#> 135     FI  33      68238
#> 136     FI  34      69659
#> 137     FI  35      71780
#> 138     FI  36      73627
#> 139     FI  37      73934
#> 140     FI  38      71997
#> 141     FI  39      70011
#> 142     FI  40      69540
#> 143     FI  41      69274
#> 144     FI  42      69620
#> 145     FI  43      70167
#> 146     FI  44      69529
#> 147     FI  45      67045
#> 148     FI  46      62525
#> 149     FI  47      60458
#> 150     FI  48      62345
#> 151     FI  49      64220
#> 152     FI  50      65583
#> 153     FI  51      68359
#> 154     FI  52      71724
#> 155     FI  53      72823
#> 156     FI  54      73028
#> 157     FI  55      73659
#> 158     FI  56      74613
#> 159     FI  57      74237
#> 160     FI  58      73261
#> 161     FI  59      72684
#> 162     FI  60      72191
#> 163     FI  61      70626
#> 164     FI  62      70675
#> 165     FI  63      72758
#> 166     FI  64      72854
#> 167     FI  65      72149
#> 168     FI  66      71330
#> 169     FI  67      71628
#> 170     FI  68      70964
#> 171     FI  69      70488
#> 172     FI  70      72002
#> 173     FI  71      72904
#> 174     FI  72      72405
#> 175     FI  73      70303
#> 176     FI  74      64332
#> 177     FI  75      54151
#> 178     FI  76      46033
#> 179     FI  77      39485
#> 180     FI  78      41891
#> 181     FI  79      41153
#> 182     FI  80      35597
#> 183     FI  81      36117
#> 184     FI  82      32580
#> 185     FI  83      29135
#> 186     FI  84      26604
#> 187     FI  85      24080
#> 188     FI  86      20853
#> 189     FI  87      18725
#> 190     FI  88      17164
#> 191     FI  89      15267
#> 192     FI  90      13126
#> 193     FI  91      10670
#> 194     FI  92       8284
#> 195     FI  93       6400
#> 196     FI  94       4954
#> 197     FI  95       3754
#> 198     FI  96       2872
#> 199     FI  97       2159
#> 200     FI  98       1593
#> 201     FI  99       1183
#> 202     FI 100       1987
#> 203     IS   0       4662
#> 204     IS   1       4692
#> 205     IS   2       4715
#> 206     IS   3       4736
#> 207     IS   4       4754
#> 208     IS   5       4760
#> 209     IS   6       4763
#> 210     IS   7       4760
#> 211     IS   8       4708
#> 212     IS   9       4844
#> 213     IS  10       5059
#> 214     IS  11       4953
#> 215     IS  12       4742
#> 216     IS  13       4577
#> 217     IS  14       4492
#> 218     IS  15       4436
#> 219     IS  16       4418
#> 220     IS  17       4331
#> 221     IS  18       4326
#> 222     IS  19       4474
#> 223     IS  20       4568
#> 224     IS  21       4523
#> 225     IS  22       4592
#> 226     IS  23       4654
#> 227     IS  24       4723
#> 228     IS  25       4747
#> 229     IS  26       4964
#> 230     IS  27       5064
#> 231     IS  28       4997
#> 232     IS  29       5093
#> 233     IS  30       5067
#> 234     IS  31       4887
#> 235     IS  32       4821
#> 236     IS  33       4698
#> 237     IS  34       4627
#> 238     IS  35       4707
#> 239     IS  36       4772
#> 240     IS  37       4768
#> 241     IS  38       4701
#> 242     IS  39       4870
#> 243     IS  40       4945
#> 244     IS  41       4745
#> 245     IS  42       4410
#> 246     IS  43       4324
#> 247     IS  44       4391
#> 248     IS  45       4348
#> 249     IS  46       4437
#> 250     IS  47       4600
#> 251     IS  48       4435
#> 252     IS  49       4060
#> 253     IS  50       4027
#> 254     IS  51       4080
#> 255     IS  52       4109
#> 256     IS  53       4265
#> 257     IS  54       4365
#> 258     IS  55       4362
#> 259     IS  56       4416
#> 260     IS  57       4348
#> 261     IS  58       4213
#> 262     IS  59       4214
#> 263     IS  60       4312
#> 264     IS  61       4196
#> 265     IS  62       4095
#> 266     IS  63       4046
#> 267     IS  64       3849
#> 268     IS  65       3666
#> 269     IS  66       3627
#> 270     IS  67       3489
#> 271     IS  68       3320
#> 272     IS  69       3237
#> 273     IS  70       3084
#> 274     IS  71       2941
#> 275     IS  72       2820
#> 276     IS  73       2617
#> 277     IS  74       2456
#> 278     IS  75       2294
#> 279     IS  76       2121
#> 280     IS  77       1967
#> 281     IS  78       1739
#> 282     IS  79       1516
#> 283     IS  80       1383
#> 284     IS  81       1282
#> 285     IS  82       1206
#> 286     IS  83       1151
#> 287     IS  84       1077
#> 288     IS  85        990
#> 289     IS  86        897
#> 290     IS  87        826
#> 291     IS  88        769
#> 292     IS  89        713
#> 293     IS  90        617
#> 294     IS  91        497
#> 295     IS  92        415
#> 296     IS  93        349
#> 297     IS  94        274
#> 298     IS  95        208
#> 299     IS  96        167
#> 300     IS  97        128
#> 301     IS  98         95
#> 302     IS  99         71
#> 303     IS 100        127
#> 304     NO   0      53709
#> 305     NO   1      55114
#> 306     NO   2      56457
#> 307     NO   3      58826
#> 308     NO   4      60525
#> 309     NO   5      61060
#> 310     NO   6      61477
#> 311     NO   7      62610
#> 312     NO   8      63862
#> 313     NO   9      65059
#> 314     NO  10      66435
#> 315     NO  11      66415
#> 316     NO  12      65351
#> 317     NO  13      64731
#> 318     NO  14      64116
#> 319     NO  15      63488
#> 320     NO  16      63377
#> 321     NO  17      62592
#> 322     NO  18      62893
#> 323     NO  19      65005
#> 324     NO  20      66617
#> 325     NO  21      67067
#> 326     NO  22      68012
#> 327     NO  23      69868
#> 328     NO  24      70600
#> 329     NO  25      71122
#> 330     NO  26      72394
#> 331     NO  27      73947
#> 332     NO  28      76001
#> 333     NO  29      77777
#> 334     NO  30      78327
#> 335     NO  31      77535
#> 336     NO  32      75831
#> 337     NO  33      74280
#> 338     NO  34      73149
#> 339     NO  35      71917
#> 340     NO  36      70827
#> 341     NO  37      70886
#> 342     NO  38      70821
#> 343     NO  39      70089
#> 344     NO  40      69576
#> 345     NO  41      68800
#> 346     NO  42      67505
#> 347     NO  43      67393
#> 348     NO  44      69167
#> 349     NO  45      71378
#> 350     NO  46      73081
#> 351     NO  47      74454
#> 352     NO  48      75406
#> 353     NO  49      74983
#> 354     NO  50      75445
#> 355     NO  51      76001
#> 356     NO  52      74420
#> 357     NO  53      73154
#> 358     NO  54      72382
#> 359     NO  55      71061
#> 360     NO  56      68973
#> 361     NO  57      66485
#> 362     NO  58      65027
#> 363     NO  59      63885
#> 364     NO  60      63402
#> 365     NO  61      62845
#> 366     NO  62      61706
#> 367     NO  63      60989
#> 368     NO  64      60307
#> 369     NO  65      58584
#> 370     NO  66      57323
#> 371     NO  67      56258
#> 372     NO  68      54036
#> 373     NO  69      52763
#> 374     NO  70      52761
#> 375     NO  71      52603
#> 376     NO  72      52817
#> 377     NO  73      53529
#> 378     NO  74      50722
#> 379     NO  75      46022
#> 380     NO  76      41573
#> 381     NO  77      36530
#> 382     NO  78      31841
#> 383     NO  79      29159
#> 384     NO  80      28078
#> 385     NO  81      25833
#> 386     NO  82      23446
#> 387     NO  83      21163
#> 388     NO  84      19094
#> 389     NO  85      17180
#> 390     NO  86      15519
#> 391     NO  87      14391
#> 392     NO  88      13178
#> 393     NO  89      11619
#> 394     NO  90       9966
#> 395     NO  91       8219
#> 396     NO  92       6764
#> 397     NO  93       5573
#> 398     NO  94       4520
#> 399     NO  95       3540
#> 400     NO  96       2748
#> 401     NO  97       2041
#> 402     NO  98       1448
#> 403     NO  99       1056
#> 404     NO 100       1636
#> 405     SE   0     113869
#> 406     SE   1     116485
#> 407     SE   2     118659
#> 408     SE   3     121036
#> 409     SE   4     123261
#> 410     SE   5     122760
#> 411     SE   6     123680
#> 412     SE   7     122923
#> 413     SE   8     123133
#> 414     SE   9     124651
#> 415     SE  10     125659
#> 416     SE  11     123050
#> 417     SE  12     121911
#> 418     SE  13     120422
#> 419     SE  14     118183
#> 420     SE  15     116234
#> 421     SE  16     115242
#> 422     SE  17     113199
#> 423     SE  18     110334
#> 424     SE  19     109308
#> 425     SE  20     110961
#> 426     SE  21     116441
#> 427     SE  22     113318
#> 428     SE  23     114372
#> 429     SE  24     121807
#> 430     SE  25     131933
#> 431     SE  26     140893
#> 432     SE  27     147596
#> 433     SE  28     151093
#> 434     SE  29     152385
#> 435     SE  30     155312
#> 436     SE  31     153085
#> 437     SE  32     149559
#> 438     SE  33     145003
#> 439     SE  34     141255
#> 440     SE  35     139527
#> 441     SE  36     135091
#> 442     SE  37     130698
#> 443     SE  38     129552
#> 444     SE  39     127802
#> 445     SE  40     130820
#> 446     SE  41     129104
#> 447     SE  42     125486
#> 448     SE  43     123838
#> 449     SE  44     124574
#> 450     SE  45     127240
#> 451     SE  46     132127
#> 452     SE  47     133231
#> 453     SE  48     133420
#> 454     SE  49     133427
#> 455     SE  50     132296
#> 456     SE  51     128322
#> 457     SE  52     129398
#> 458     SE  53     135051
#> 459     SE  54     138797
#> 460     SE  55     139144
#> 461     SE  56     137937
#> 462     SE  57     132713
#> 463     SE  58     124375
#> 464     SE  59     118885
#> 465     SE  60     116182
#> 466     SE  61     114095
#> 467     SE  62     113560
#> 468     SE  63     112960
#> 469     SE  64     112810
#> 470     SE  65     111575
#> 471     SE  66     108285
#> 472     SE  67     106802
#> 473     SE  68     106831
#> 474     SE  69     104659
#> 475     SE  70     105343
#> 476     SE  71     107658
#> 477     SE  72     109994
#> 478     SE  73     110520
#> 479     SE  74     109272
#> 480     SE  75     107975
#> 481     SE  76     104517
#> 482     SE  77      98368
#> 483     SE  78      88987
#> 484     SE  79      77567
#> 485     SE  80      67542
#> 486     SE  81      62834
#> 487     SE  82      59309
#> 488     SE  83      53289
#> 489     SE  84      47640
#> 490     SE  85      42346
#> 491     SE  86      37078
#> 492     SE  87      32211
#> 493     SE  88      28220
#> 494     SE  89      25291
#> 495     SE  90      21953
#> 496     SE  91      17878
#> 497     SE  92      14436
#> 498     SE  93      11494
#> 499     SE  94       8783
#> 500     SE  95       6447
#> 501     SE  96       4788
#> 502     SE  97       3535
#> 503     SE  98       2318
#> 504     SE  99       1795
#> 505     SE 100       3664

The adjacency data must include exactly the columns from, to, and adjacency. The from and to columns should contain the same set of region identifiers.

adjacency_meta_nordic
#>    from to    adjacency
#> 1    NO NO 6.413468e+03
#> 2    NO FI 1.373980e+01
#> 3    FI NO 1.373980e+01
#> 4    SE NO 5.211436e+01
#> 5    NO SE 5.211436e+01
#> 6    NO DK 7.593018e+01
#> 7    DK NO 7.593018e+01
#> 8    FI DK 1.148846e+01
#> 9    DK FI 1.148846e+01
#> 10   SE FI 2.417292e+01
#> 11   FI SE 2.417292e+01
#> 12   SE SE 1.360304e+03
#> 13   SE DK 3.914193e+01
#> 14   DK SE 3.914193e+01
#> 15   DK DK 9.752552e+03
#> 16   SE IS 4.198384e+02
#> 17   IS SE 4.198384e+02
#> 18   FI FI 3.511907e+03
#> 19   NO IS 1.048687e+03
#> 20   IS NO 1.048687e+03
#> 21   IS FI 1.359369e+02
#> 22   FI IS 1.359369e+02
#> 23   IS DK 2.020525e+03
#> 24   DK IS 2.020525e+03
#> 25   IS IS 5.562547e+06

Regional adjacency

DiseasyRegions builds on the concept of a degree of “connectedness” between the different regions. Here, this “connectedness” is referred to as “adjacency” in alignment with other models.

Different measures for adjacency can be extracted from real-world data which have very different interpretations. Adjacency is often described from information about “movement” such as mobility data or surveys on how people move between regions. Alternatively adjacency can be derived from “infection” data such as genetic phylogeny.

While these seem very similar, there are substantial differences in how these adjacencies are expressed numerically, and how they should be implemented in disease spread models. Our framework assumes a reality where disease is transported between regions by people returning to their own region (travel or commuting), that is: there is no immigration or emigration. If the supplied adjacency describes a movement matrix it is furthermore assumed that people travelling to a place transmits disease equally with people travelling from a place. Which in turns means that the resulting infection matrix used in the models will be symmetric.

In diseasy, the adjacency of DiseasyRegions are implemented in SEIR-like models and it helps to be clear on how this adjacency is used to illustrate these differences.

To begin, let’s define the “movement matrix” Φ\Phi between RR connected regions:

Φ¯¯=[ϕ1,1⋯ϕ1,R⋮⋱⋮ϕR,1⋯ϕR,R] \overline{\overline{\Phi}} = \begin{bmatrix} \phi_{1,1} & \cdots & \phi_{1,R} \\ \vdots & \ddots & \vdots \\ \phi_{R,1} & \cdots & \phi_{R,R} \end{bmatrix}

If we interpret these adjacencies as “the average fraction of contacts between regions”, we can diagram the SEIR compartments of a two-region model as:

SEIR model overview for a two region model

SEIR model overview for a two region model

With the following equations for the infectious compartments in region 11İ1=β(S1ϕ1,1⏟stayϕ1,1I1⏟stay+S1ϕ1,1⏟stayϕ1,2I2⏟travel+S1ϕ2,1⏟travelϕ2,2I2⏟stay+S1ϕ2,1⏟travelϕ2,1I1⏟travel)−rII1 \dot{I}_1 = \beta\left( \underbrace{S_1 \phi_{1,1}}_\textrm{stay} \underbrace{\phi_{1,1} I_1}_\textrm{stay} + \underbrace{S_1 \phi_{1,1}}_\textrm{stay} \underbrace{\phi_{1,2} I_2}_\textrm{travel} + \underbrace{S_1 \phi_{2,1}}_\textrm{travel}\underbrace{\phi_{2,2} I_2}_\textrm{stay} + \underbrace{S_1 \phi_{2,1}}_\textrm{travel}\underbrace{\phi_{2,1} I_1}_\textrm{travel}\right) - r_I I_1 where we divide the types of contacts into whether individuals stay in their own region or travel1 to other regions.

In general, we can express the dynamics in matrix form assuming RR different regions I¯̇=βS¯∘Θ¯¯⋅I¯−rII¯ \dot{\overline{I}} = \beta\overline{S}\circ\overline{\overline{\Theta}}\cdot\overline{I} - r_I \overline{I}

Where ∘\circ is the Hadamard product (element-wise multiplication).

The matrix elements of Θ¯¯\overline{\overline{\Theta}} contains the probability that individual interact across regions, with elements Θx,y=∑zϕz,xϕz,y\Theta_{x,y} = \sum_z \phi_{z,x} \phi_{z,y}.

These elements compute the probability that individuals in region xx travel to region zz AND individuals in region yy travel to region zz.

For the 2-region system, the mixing can be expressed in matrix form as: Θ¯¯=[ϕ1,12+ϕ2,12ϕ1,1ϕ1,2+ϕ2,1ϕ2,2ϕ2,2ϕ2,1+ϕ1,2ϕ1,1ϕ2,22+ϕ1,22] \overline{\overline{\Theta}} = \begin{bmatrix} \phi_{1,1}^2 + \phi_{2,1}^2 & \phi_{1,1}\phi_{1,2} + \phi_{2,1}\phi_{2,2} \\ \phi_{2,2}\phi_{2,1} + \phi_{1,2}\phi_{1,1} & \phi_{2,2}^2 + \phi_{1,2}^2 \end{bmatrix}

In this formalism, the Θ\Theta which satisfies: İ=İ1+İ2=βSI−rII \dot{I} = \dot{I}_1 + \dot{I}_2 = \beta S I - r_I I

requires S¯⋅Θ¯¯⋅I¯=SI \overline{S}\cdot\overline{\overline{\Theta}}\cdot\overline{I} = S I

That leads to the following expression: S1(ϕ1,12+ϕ2,12)I1+S1(ϕ1,1ϕ1,2+ϕ2,1ϕ2,2)I2+S2(ϕ2,22+ϕ1,22)I2+S2(ϕ2,2ϕ2,1+ϕ1,2ϕ1,1)I1 S_1 (\phi_{1,1}^2 + \phi_{2,1}^2) I_1 + S_1 (\phi_{1,1}\phi_{1,2} + \phi_{2,1}\phi_{2,2}) I_2 + S_2 (\phi_{2,2}^2 + \phi_{1,2}^2) I_2 + S_2 (\phi_{2,2}\phi_{2,1} + \phi_{1,2}\phi_{1,1}) I_1

If we assume there is no spatial structure and therefore all matrix elements are identical: ϕx,y=ϕ\phi_{x,y} = \phi

Then we can reduce the expression ⇒S1(2ϕ2)I1+S1(2ϕ2)I2+S2(2ϕ2)I2+S2(2ϕ2)I1 \Rightarrow S_1 (2\phi^2) I_1 + S_1 (2\phi^2) I_2 + S_2 (2\phi^2) I_2 + S_2 (2\phi^2) I_1

⇒S1(2ϕ2)(I1+I2)+S2(2ϕ2)(I1+I2) \Rightarrow S_1 (2\phi^2) (I_1 + I_2) + S_2 (2\phi^2) (I_1 + I_2)

⇒(2ϕ2)(S1+S2)(I1+I2) \Rightarrow (2\phi^2) (S_1 + S_2) (I_1 + I_2)

⇒(2ϕ2)SI \Rightarrow (2\phi^2) S I

Which means that the neutral matrix elements for the 2-region system are: ϕ=12 \phi = \frac{1}{\sqrt{2}}

and in general for the n-region system2: ϕ=1n \phi = \frac{1}{\sqrt{n}}

This “movement matrix” Φ¯¯\overline{\overline{\Phi}} can be estimated from information on how individuals travel, such as from survey or mobility data.

Alternatively, we can consider the Θ¯¯\overline{\overline{\Theta}} matrix which we can think of as a “infection-flow” matrix. This matrix identifies the flow of infections from individuals residing in regions xx to individuals residing in regions yy. Such matrix may be estimated from more direct measurements of disease flow such as from genetic data or contact tracing.

The Φ\Phi matrix will be normalised such that its row sums are 1.

DiseasyRegions can take either type of adjacency matrix.

The stored adjacency input is long form, but the module also exposes an $infection_flow_matrix field. This field returns a matrix representation of adjacency for the currently selected regions.

Regional differences in infection risk

In DiseasyRegions we implement a regional modifier for the infection risk as a named vector of relative risks for each region in the model.

This modifier can conceptually be thought of as either a modifier on the human behaviour of individual residing in the region (e.g. socio-economic differences in behaviour) or a modifier relating to the physical location itself (e.g. related to infrastructure of the region).

If the modifier Γx\Gamma_x is related to the location, the elements of the infection-flow matrix is modified to Θx,y=∑zΓzϕz,xϕz,y \Theta_{x,y} = \sum_z \Gamma_z \phi_{z,x} \phi_{z,y}

Whereas if the modifier is related to behavioural differences, the elements are modified to: Θx,y=ΓxΓy∑zϕz,xϕz,y \Theta_{x,y} = \sqrt{\Gamma_x\Gamma_y} \sum_z \phi_{z,x} \phi_{z,y}

Notice that if the infection-matrix is directly specified, these modifies may already (implicitly) included.

The region-specific modifiers can be set via the set_regional_risks() method, and the interpretation of the modifier can be toggled via the risk_type argument.

Creating a regional module

A DiseasyRegions object can be created and then configured with the selected area, demography, and adjacency data. Each setter validates the candidate input before storing it.

regions <- DiseasyRegions$new()

regions
#> # DiseasyRegions #############################################
#> Area: No area has been specified
#> Total population: No population data loaded
#> Theta matrix: No adjacency data loaded
regions$set_area(area = c("DK", "SE", "NO", "FI"))
regions$set_demography(demography = demography_nordic)
regions$set_adjacency(adjacency = adjacency_meta_nordic)

regions
#> # DiseasyRegions #############################################
#> Area: DK, FI, NO, SE
#> Total population: 27,124,322
#> Theta matrix: Max eigenvalue 9754.49

The $demography field returns demography filtered to the currently selected regions.

regions %.% demography
#> # A tibble: 404 × 3
#>   region   age population
#>   <chr>  <dbl>      <dbl>
#> 1 DK         0      60965
#> 2 DK         1      61357
#> 3 DK         2      61663
#> 4 DK         3      62128
#> 5 DK         4      61148
#> # ℹ 399 more rows

Population totals can be computed directly from the filtered demography.

aggregate(
  population ~ region,
  data = regions %.% demography,
  FUN = sum
)
#>   region population
#> 1     DK    5837230
#> 2     FI    5522887
#> 3     NO    5381527
#> 4     SE   10382678

The active bindings $adjacency and $infection_flow_matrix expose derived views of adjacency input after filtering to the selected regions.

regions %.% adjacency
#> # A tibble: 16 × 3
#>    from  to    adjacency
#>    <chr> <chr>     <dbl>
#>  1 DK    DK       9753. 
#>  2 DK    FI         11.5
#>  3 DK    NO         75.9
#>  4 DK    SE         39.1
#>  5 FI    DK         11.5
#>  6 FI    FI       3512. 
#>  7 FI    NO         13.7
#>  8 FI    SE         24.2
#>  9 NO    DK         75.9
#> 10 NO    FI         13.7
#> 11 NO    NO       6413. 
#> 12 NO    SE         52.1
#> 13 SE    DK         39.1
#> 14 SE    FI         24.2
#> 15 SE    NO         52.1
#> 16 SE    SE       1360.
regions %.% infection_flow_matrix
#>            DK         FI         NO         SE
#> DK 9752.55170   11.48846   75.93018   39.14193
#> FI   11.48846 3511.90746   13.73980   24.17292
#> NO   75.93018   13.73980 6413.46763   52.11436
#> SE   39.14193   24.17292   52.11436 1360.30436

Regional modifiers of infection risk can be set via the $set_regional_risks() method

… tied to location:

regions$set_regional_risks(
  regional_risks = c("DK" = 1.1, "SE" = 0.9, "NO" = 0.8, "FI" = 0.5),
  regional_risks_type = "location"
)

# Our example produces an error since the provided `adjacency` is not movement data
try(regions %.% infection_flow_matrix)
#> Error in base::tryCatch(base::withCallingHandlers({ : 
#>   `regional_risks_type` can only be "location" if `adjacency_type = "movement"`

… or tied to population:

regions$set_regional_risks(
  regional_risks = c("DK" = 1.1, "SE" = 0.9, "NO" = 0.8, "FI" = 0.5),
  regional_risks_type = "behaviour"
)

regions %.% infection_flow_matrix
#>              DK          FI          NO         SE
#> DK 10727.806867    8.520073   71.228818   38.94573
#> FI     8.520073 1755.953729    8.689812   16.21569
#> NO    71.228818    8.689812 5130.774105   44.22050
#> SE    38.945732   16.215690   44.220503 1224.27392

The module configuration can also be visualised via the $plot() method with or plot().

plot(regions)
#> Linking to GEOS 3.14.1, GDAL 3.12.2, PROJ 9.7.1; sf_use_s2() is TRUE

Regional module with hierarchical structure (NUTS)

If you have demography and adjacency data for structured regions (such as NUTS), then DiseasyRegionsNuts can handle the nested data.

regions_nuts <- DiseasyRegionsNuts$new()

regions_nuts
#> # DiseasyRegions #############################################
#> Area: No area has been specified
#> Total population: No population data loaded
#> Theta matrix: No adjacency data loaded
regions_nuts$set_area(area = "DK")
regions_nuts$set_demography(demography = demography_nordic_nuts3)
regions_nuts$set_adjacency(adjacency = adjacency_meta_nordic_nuts3)

regions_nuts
#> # DiseasyRegions #############################################
#> Area: DK
#> Total population: 5,992,734
#> Theta matrix: Max eigenvalue 90130217

And again the module configuration can also be visualised with plot().

plot(regions_nuts)

Changing the selected regions

The selected regional scope can be changed with $set_area(). The new regions must be available in the stored adjacency and demography data.

regions$set_area(area = c("DK", "SE"))

regions %.% area
#> [1] "DK" "SE"

The active fields now reflect the updated scope.

regions %.% demography
#> # A tibble: 202 × 3
#>   region   age population
#>   <chr>  <dbl>      <dbl>
#> 1 DK         0      60965
#> 2 DK         1      61357
#> 3 DK         2      61663
#> 4 DK         3      62128
#> 5 DK         4      61148
#> # ℹ 197 more rows
regions %.% adjacency
#> # A tibble: 4 × 3
#>   from  to    adjacency
#>   <chr> <chr>     <dbl>
#> 1 DK    DK       9753. 
#> 2 DK    SE         39.1
#> 3 SE    DK         39.1
#> 4 SE    SE       1360.
regions %.% infection_flow_matrix
#>             DK         SE
#> DK 10727.80687   38.94573
#> SE    38.94573 1224.27392

Validation

The module checks that selected regions are available in the stored demography and adjacency. For example, trying to select a region that is not present in the data will fail.

try(DiseasyRegionsNuts$set_area(regions = "DE"))
#> Error in try(DiseasyRegionsNuts$set_area(regions = "DE")) : 
#>   attempt to apply non-function

The adjacency data must also contain the same region identifiers in the from and to columns.

bad_adjacency <- data.frame(
  from = c("DE", "BE"),
  to = c("DE", "BE"),
  adjacency = c(1, 1)
)

try(regions$set_adjacency(adjacency = bad_adjacency))
#> Error in base::tryCatch(base::withCallingHandlers({ : 
#>   `area` and `adjacency` must contain at least one common region.