Diseasy's region (spatial) handler — DiseasyRegions • diseasy

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

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

Value

A new instance of the DiseasyRegions R6 class.

Super class

DiseasyBaseModule -> DiseasyRegions

Active bindings

regions: (character())
The geographic regions of interest. 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$adjacency_to_theta()
DiseasyRegions$describe()
DiseasyRegions$clone()

Inherited methods

`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.

The generic implementation uses exact matching. DiseasyRegionsNuts overrides this method with hierarchical NUTS prefix matching.

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$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$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.

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)