Trace ingoing and outgoing contact chains and visualise data on a Leaflet map

trace_contact_chains() determines ingoing and outgoing contact chains for one or more root holdings over a specified time period, and then plots these on an interactive Leaflet map. If a map with administrative areas is provided, contact chain data are aggregated geographically, and the resulting map can be coloured by the total weight or number of ingoing movements from or outgoing movements to each area.

Usage

trace_contact_chains(
  movement_data,
  holding_data,
  root,
  tEnd = NULL,
  days = NULL,
  inBegin = NULL,
  inEnd = NULL,
  outBegin = NULL,
  outEnd = NULL,
  maxDistance = NULL,
  admin_areas_map = NULL,
  colour_domain_weight_in = NULL,
  colour_domain_weight_out = NULL,
  colour_domain_moves_in = NULL,
  colour_domain_moves_out = NULL
)

Arguments

movement_data

A movenet-format movement tibble.

holding_data

A movenet-format holding tibble that includes a "coordinates" column. Holding identifiers must be unique.

root

A vector with one or more root holdings to perform contact tracing for.

tEnd

A single date, or character or factor that can be converted to a date, representing the last date to include both ingoing and outgoing movements. Defaults to NULL.

days

A single numeric representing the number of days prior to tEnd to include ingoing and outgoing movements for. Defaults to NULL.

inBegin

A single date, or character or factor that can be converted to a date, representing the first date to include ingoing movements for. Defaults to NULL.

inEnd

A single date, or character or factor that can be converted to a date, representing the last date to include ingoing movements for. Defaults to NULL.

outBegin

A single date, or character or factor that can be converted to a date, representing the first date to include outgoing movements for. Defaults to NULL.

outEnd

A single date, or character or factor that can be converted to a date, representing the last date to include outgoing movements for. Defaults to NULL.

maxDistance

A single numeric representing the maximum 'distance' (in number of movements) away from the root node, at which to stop contact tracing. Defaults to NULL, i.e. don't use the maxDistance stop criterion.

admin_areas_map

An sf dataframe with administrative area boundaries.

colour_domain_weight_in

A numeric vector representing the range (i.e. c(min, max)) of possible aggregate ingoing weight values to colour administrative areas by. If NULL (default), the range will be determined from the data.

colour_domain_weight_out

A numeric vector representing the range (i.e. c(min, max)) of possible aggregate outgoing weight values to colour administrative areas by. If NULL (default), the range will be determined from the data.

colour_domain_moves_in

A numeric vector representing the range (i.e. c(min, max)) of possible aggregate numbers of ingoing moves to colour administrative areas by. If NULL (default), the range will be determined from the data.

colour_domain_moves_out

A numeric vector representing the range (i.e. c(min, max)) of possible aggregate numbers of outgoing moves to colour administrative areas by. If NULL (default), the range will be determined from the data.

Value

A Leaflet map (HTML widget object) with graphics layers for holdings and movements that are part of ingoing and outgoing contact chains, and for administrative area data if admin_areas_map is provided. Further layers can be added using %>%.

Details

The time period can either be specified using tEnd and days, or using inBegin, inEnd, outBegin and outEnd. If using tEnd and days, the time period for ingoing and outgoing contacts ends at tEnd and starts at days prior to tEnd. An alternative way is to use inBegin, inEnd, outBegin and outEnd. The time period for ingoing contacts starts at inBegin and ends at inEnd. For outgoing contacts the time period starts at outBegin and ends at outEnd.

If admin_areas_map is provided, administrative area boundaries are added to the Leaflet map. Additionally, contact chain data are summarised geographically and the user can choose to colour the map by the total weight or number of ingoing movements from or outgoing movements to each administrative area. By default, the colour scales for these geographical layers are determined by the ranges of the respective values in the data, however they can be set via the colour_domain_weight_in, colour_domain_weight_out, colour_domain_moves_in, and/or colour_domain_moves_out arguments in order to make colours comparable across maps.

See also

• EpiContactTrace::Trace() for the underlying contact chain tracing functionality.

• leaflet::leaflet() for the underlying mapping functionality.

Other network-related functions: create_temporal_network_analysis_report(), movedata2igraph(), movedata2networkDynamic(), parallel_summarise_temporal_node_properties()

Examples

# Trace contact chains for a single root holding, over 90 days to 2019-07-01.
trace_contact_chains(example_movement_data, example_holding_data,
root = "95/216/1100", tEnd = "2019-07-01", days = 90)
#> Creating map with contact chains for root(s) 95/216/1100.


# Trace contact chains for a single root holding, with a maximum distance of
# 2 movements from root
trace_contact_chains(example_movement_data, example_holding_data,
root = "95/216/1100", tEnd = "2019-07-01", days = 90, maxDistance = 2)
#> Creating map with contact chains for root(s) 95/216/1100.


# Trace contact chains for a single root holding, using different periods for
# ingoing and outgoing contact chains.
trace_contact_chains(example_movement_data, example_holding_data,
root = "95/216/1100", inBegin = "2019-01-01", inEnd = "2019-04-01",
outBegin = "2019-04-01", outEnd = "2019-07-01")
#> Creating map with contact chains for root(s) 95/216/1100.


# Trace contact chains and summarise data by administrative area.
trace_contact_chains(example_movement_data, example_holding_data,
root = "95/216/1100", tEnd = "2019-07-01", days = 90,
admin_areas_map = example_admin_areas)
#> Creating map with contact chains for root(s) 95/216/1100.