Diseasy's region (spatial) handler

The DiseasyRegions module is responsible for handling geographic regions included in the model.

The base class treats regions as generic identifiers. Use DiseasyRegionsNuts for NUTS-specific validation and hierarchical region matching.

See the vignette("diseasy-regions") for examples of use.

Value

A new instance of the DiseasyRegions R6 class.

See also

• rnaturalearth::ne_countries() for country-level shape files.

• giscoR::gisco_get_nuts() for NUTS-level shape files in Europe.

Super class

DiseasyBaseModule -> DiseasyRegions

Active bindings

regions

(character())
The geographic regions of interest. Read only.

available_stratifications

(character())
The available levels of stratification supported. Read only.

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
Read only.

infection_flow_matrix

(matrix)
The "Theta" matrix (see vignette("diseasy-regions")) that describes flow of infections between regions.

demography

(data.frame(1))
The demography of the population per region.
The data.frame must include the following columns:
* region (character) Region identifier.
* ... Optional additional stratification columns (e.g. sex, ethnicity).
* population (numeric) Number of individuals in the group. Read only.

Methods

Public methods

• DiseasyRegions$new()

• DiseasyRegions$set_regions()

• DiseasyRegions$set_adjacency()

• DiseasyRegions$set_demography()

• DiseasyRegions$validate_configuration()

• DiseasyRegions$region_filter()

• DiseasyRegions$regions_at_stratification()

• DiseasyRegions$adjacency_to_theta()

• DiseasyRegions$plot()

• DiseasyRegions$describe()

• DiseasyRegions$clone()

Inherited methods

• DiseasyBaseModule$load_module()
• DiseasyBaseModule$set_moduleowner()

---

DiseasyRegions$new()

Creates a new instance of the DiseasyRegions R6 class.

Usage

DiseasyRegions$new(regions = NULL, adjacency = NULL, demography = NULL, ...)

Arguments

regions

(character())
The geographic regions of interest. The specified regions must be available in the demography and adjacency data.

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
The from and to columns must contain the same set of regions. For "movement" inputs, rows are normalised before deriving the Theta matrix. For "infection-flow" inputs, values are interpreted directly as the Theta matrix.

demography

(data.frame(1))
The demography of the population per region.
The data.frame must include the following columns:
* region (character) Region identifier.
* ... Optional additional stratification columns (e.g. sex, ethnicity).
* population (numeric) Number of individuals in the group.

...

Parameters sent to DiseasyBaseModule R6 constructor.

---

DiseasyRegions$set_regions()

Sets the geographic regions of interest.

Usage

DiseasyRegions$set_regions(regions)

Arguments

regions

(character())
The geographic regions of interest. The specified regions must be available in the demography and adjacency data.

Returns

NULL (called for side effects)

---

DiseasyRegions$set_adjacency()

Sets the region adjacency data.

Usage

DiseasyRegions$set_adjacency(adjacency, type = c("movement", "infection-flow"))

Arguments

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
The from and to columns must contain the same set of regions. For "movement" inputs, rows are normalised before deriving the Theta matrix. For "infection-flow" inputs, values are interpreted directly as the Theta matrix.

type

(character)
The type of adjacency provided ("movement" versus "infection-flow"). See vignette("diseasy-regions") for details.

Returns

NULL (called for side effects)

---

DiseasyRegions$set_demography()

Sets the demography data for all regions.

Usage

DiseasyRegions$set_demography(demography)

Arguments

demography

(data.frame(1))
The demography of the population per region.
The data.frame must include the following columns:
* region (character) Region identifier.
* ... Optional additional stratification columns (e.g. sex, ethnicity).
* population (numeric) Number of individuals in the group.

Returns

NULL (called for side effects)

---

DiseasyRegions$validate_configuration()

Check whether regions, adjacency, and demography are mutually consistent.

Usage

DiseasyRegions$validate_configuration(regions, adjacency, demography)

Arguments

regions

(character())
The geographic regions of interest. The specified regions must be available in the demography and adjacency data.

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
The from and to columns must contain the same set of regions. For "movement" inputs, rows are normalised before deriving the Theta matrix. For "infection-flow" inputs, values are interpreted directly as the Theta matrix.

demography

(data.frame(1))
The demography of the population per region.
The data.frame must include the following columns:
* region (character) Region identifier.
* ... Optional additional stratification columns (e.g. sex, ethnicity).
* population (numeric) Number of individuals in the group.

Returns

NULL (called for side effects)

---

DiseasyRegions$region_filter()

Create a logical filter for values matching one or more regions.

Usage

DiseasyRegions$region_filter(values, regions = self %.% regions)

Arguments

values

(character())
Values to filter, typically region identifiers.

regions

(character() or NULL)
Region identifiers to match against. Defaults to the currently selected regions. If NULL, all values are matched.

Returns

A logical() vector with the same length as values.

---

DiseasyRegions$regions_at_stratification()

Get the regions available at the given stratification level

Usage

DiseasyRegions$regions_at_stratification(regional_stratification)

Arguments

regional_stratification

(character())
The level of spatial stratification of the population.

Returns

The (sorted) list of available regions within the defined scope at the given stratification level.

---

DiseasyRegions$adjacency_to_theta()

Converts long form adjacency to the "Theta" infection matrix.

Usage

DiseasyRegions$adjacency_to_theta(
  adjacency,
  type = c("movement", "infection-flow")
)

Arguments

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
The from and to columns must contain the same set of regions. For "movement" inputs, rows are normalised before deriving the Theta matrix. For "infection-flow" inputs, values are interpreted directly as the Theta matrix.

type

(character)
The type of adjacency provided ("movement" versus "infection-flow"). See vignette("diseasy-regions") for details.

---

DiseasyRegions$plot()

Plot model outputs or module configuration spatially.

Usage

DiseasyRegions$plot(data = NULL, shape_files = NULL)

Arguments

data

(data.frame(1))
The data to plot spatially on the configured regions. If NULL, the demography and adjacency of regions are plotted. If data.frame, the first non-structural column is plotted. Structural columns are region, date, realisation_id, and weight.

shape_files

(sf or NULL)
Shape files used to draw the configured regions. If NULL, rnaturalearth::ne_countries() is used.

If an sf object is supplied, region identifiers are guessed from:

• region for user-provided shape files

• adm0_iso (as in rnaturalearth::ne_countries - also requires iso_a2 column)

• geo (as in giscoR::gisco_get_nuts())

If several candidate columns exist, the first candidate with any match to the configured regions is used.

Returns

NULL (called for side effects)

---

DiseasyRegions$describe()

Prints a human readable report of the internal state of the module.

Usage

DiseasyRegions$describe()

---

DiseasyRegions$clone()

The objects of this class are cloneable with this method.

Usage

DiseasyRegions$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Super classes

DiseasyBaseModule -> DiseasyRegions -> DiseasyRegionsNuts

Active bindings

available_stratifications

(character())
The available levels of stratification supported. Read only.

Methods

Public methods

• DiseasyRegionsNuts$validate_configuration()

• DiseasyRegionsNuts$region_filter()

• DiseasyRegionsNuts$regions_at_stratification()

• DiseasyRegionsNuts$plot()

• DiseasyRegionsNuts$clone()

Inherited methods

• DiseasyBaseModule$load_module()
• DiseasyBaseModule$set_moduleowner()
• DiseasyRegions$adjacency_to_theta()
• DiseasyRegions$describe()
• DiseasyRegions$initialize()
• DiseasyRegions$set_adjacency()
• DiseasyRegions$set_demography()
• DiseasyRegions$set_regions()

---

DiseasyRegionsNuts$validate_configuration()

Check whether regions, adjacency, and demography are mutually consistent and complete under NUTS hierarchy semantics.

Usage

DiseasyRegionsNuts$validate_configuration(regions, adjacency, demography)

Arguments

regions

(character())
The geographic regions of interest. The specified regions must be available in the demography and adjacency data.

adjacency

(data.frame(1))
The adjacency (connectedness) of the regions. Effectively, the adjacency is a long-form of the adjacency-matrix
The data.frame must include the following columns:
- from (character): Region identifier.
- to (character): Region identifier.
- adjacency (numeric): Strength of the connectedness.
The from and to columns must contain the same set of regions. For "movement" inputs, rows are normalised before deriving the Theta matrix. For "infection-flow" inputs, values are interpreted directly as the Theta matrix.

demography

(data.frame(1))
The demography of the population per region.
The data.frame must include the following columns:
* region (character) Region identifier.
* ... Optional additional stratification columns (e.g. sex, ethnicity).
* population (numeric) Number of individuals in the group.

Returns

NULL (called for side effects)

---

DiseasyRegionsNuts$region_filter()

Create a logical filter using NUTS hierarchy prefix matching.

Usage

DiseasyRegionsNuts$region_filter(values, regions = self %.% regions)

Arguments

values

(character())
Values to filter, typically NUTS codes.

regions

(character() or NULL)
Region identifiers to match against. Defaults to the currently selected regions. If NULL, all values are matched.

Returns

A logical() vector with the same length as values.

---

DiseasyRegionsNuts$regions_at_stratification()

Get the regions available at the given stratification level

Usage

DiseasyRegionsNuts$regions_at_stratification(regional_stratification)

Arguments

regional_stratification

(character())
The level of spatial stratification of the population.

Returns

The (sorted) list of available regions within the defined scope at the given stratification level.

---

DiseasyRegionsNuts$plot()

Usage

DiseasyRegionsNuts$plot(...)

Arguments

...

Parameters sent to $plot().

---

DiseasyRegionsNuts$clone()

The objects of this class are cloneable with this method.

Usage

DiseasyRegionsNuts$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

  # Create simple demography for three generic regions.
  demography <- data.frame(
    region = c("north", "north", "south", "south", "east", "east"),
    age_group = rep(c("0-17", "18+"), times = 3),
    population = c(100, 300, 80, 220, 60, 140)
  )

  # Adjacency is a long-form representation of connectedness.
  adjacency <- data.frame(
    from = c("north", "north", "north", "south", "south", "south", "east", "east", "east"),
    to   = c("north", "south", "east", "north", "south", "east", "north", "south", "east"),
    adjacency = c(0.7, 0.2, 0.1, 0.1, 0.8, 0.1, 0.1, 0.3, 0.6)
  )

  # Restrict the model scope to two regions.
  region <- DiseasyRegions$new(
    regions = c("north", "south"),
    adjacency = adjacency,
    demography = demography
  )

  # Active bindings return data for configured regions.
  region %.% regions
#> [1] "north" "south"
  region %.% demography
#>   region age_group population
#> 1  north      0-17        100
#> 2  north       18+        300
#> 3  south      0-17         80
#> 4  south       18+        220
  region %.% adjacency
#>    from    to adjacency
#> 1 north north       0.7
#> 2 north south       0.2
#> 3 south north       0.1
#> 4 south south       0.8

  # Update the configured regional scope.
  region$set_regions(regions = c("north", "south", "east"))
  region$describe()
#> # DiseasyRegions #############################################
#> Regions: east, north, south
#> Total population: 900
#> Theta matrix: Max eigenvalue 1.06

  rm(region, demography, adjacency)