make_epiflows {epiflows}

Create an epiflows object

Description

An epiflows object contains a pair of data frames that provide information about locations and flows between locations.

Usage

make_epiflows(...)

## S3 method for class 'data.frame'
make_epiflows(
  flows,
  locations = NULL,
  from = 1L,
  to = 2L,
  n = 3L,
  id = 1L,
  ...
)

## S3 method for class 'integer'
make_epiflows(inflow, outflow, focus, locations, id = 1L, ...)

## S3 method for class 'numeric'
make_epiflows(inflow, outflow, focus, locations, id = 1L, ...)

Arguments

...

Any number of varaibles that can be used for mapping or modelling. See global_vars() and get_vars() for details.

flows

a data frame where each row represents a flow from one location to the next. This must have at least three columns:

• Where the flow started (as specified in from, below)

• Where the flow ended (as specified in to, below)

• How many cases were involved (as specified in n, below)

locations

a data frame where each row represents a location. This can have any number of columns specifying useful metadata about the location, but it must contain at least one column specifying the location ID used in the flows data frame (as specified by the id argument, below).

from

the column in the flows data frame indicating where the flow started. This can be an integer or character. Default is the first column.

to

the column in the flows data frame indicating where the flow terminated. This can be an integer or character. Default is the second column.

n

the column in the flows data frame indicating how many cases were contained in the flow. This can be an integer or character. Default is the third column.

id

The column to use for the identifier in the locations data frame. This defaults to the first column.

inflow

a named integer or numeric vector specifying the number of cases flowing into a location specified by focus.

outflow

a named integer or numeric vector specifying the number of cases flowing from a location specified by focus.

focus

a character vector specifying the focal location for integer input. This is necessary for integer input to make clear what "outflow" and "inflow" are relative to.

Details

The epiflows object can be constructed using simply a list of locations with optional metadata (similar to a linelist) and a list of flows that describes the number of cases flowing from one location to another. Optional metadata such as coordinates and duration of stay can be included in the linelist for use in estimate_risk_spread() or map_epiflows().

Developer note: object structure

Because a flow of cases from one location to another can be thought of as a contact with a wider scope, the epiflows object inherits from the epicontacts object, constructed via epicontacts::make_epicontacts(). This means that all the methods for subsetting an object of class epicontacts also applies to epiflows, including the use of the function epicontacts::thin(). One caveat is that, internally, the names of the elements within the object do not match the terminology used in epiflows.

Value

An epiflows object in list format with four elements:

• locations (accessible via get_locations()): a data frame of locations with first column 'id' containing character vector of unique identifiers.

• flows (accessible via get_flows()): data.frame of flows with first two columns named 'from' and 'to' indicating directed flows between two locations, and a third column named 'n', specifying the number of cases in each

• vars (accessible via get_vars()). This contains a named list of available variables that can be used in further plotting and/or modelling. Default variables are found in global_vars():

  • coordinates: two columns specifying the lon and lat coordinates

  • pop_size: population size of each location

  • duration_stay: the average duration of stay for each location

  • first_date: the date of first recorded case

  • last_date: the date of the last recorded case

  • num_cases: the number of cases between the first and last date

Author(s)

Zhian Kamvar, Thibaut Jombart

See Also

global_vars() for definitions of global variables, estimate_risk_spread() for modelling, plot.epiflows() for plotting, add_coordinates() for adding coordinates, get_vars() for accession of metadata, get_locations() to access the locations data frame, get_flows() to access the flows data frame.

Examples

## Load data
data(YF_flows)
data(YF_locations)
YF_flows
YF_locations
## Use both to create the epiflows object.
ef <- make_epiflows(flows         = YF_flows, 
                    locations     = YF_locations, 
                    pop_size      = "location_population",
                    duration_stay = "length_of_stay",
                    num_cases     = "num_cases_time_window",
                    first_date    = "first_date_cases",
                    last_date     = "last_date_cases"
                   )
ef
# Access variable information
get_pop_size(ef)
get_vars(ef, "duration_stay")
get_vars(ef, "num_cases")
data(YF_Brazil)
(inflows   <- YF_Brazil$T_O["Espirito Santo", , drop = TRUE])
(outflows  <- YF_Brazil$T_D["Espirito Santo", , drop = TRUE])
(locations <- subset(YF_Brazil$states, location_code == "Espirito Santo", drop = FALSE))
los <- data.frame(location_code    = names(YF_Brazil$length_of_stay), 
                  length_of_stay   = YF_Brazil$length_of_stay,
                  stringsAsFactors = FALSE
                 )
locations <- merge(x   = locations, 
                   y   = los, 
                   by  = "location_code", 
                   all = TRUE)
ef <- make_epiflows(inflow = inflows, 
                    outflow = outflows, 
                    focus = "Espirito Santo", 
                    locations = locations,
                    pop_size = "location_population",
                    duration_stay = "length_of_stay",
                    num_cases = "num_cases_time_window",
                    first_date = "first_date_cases",
                    last_date = "last_date_cases"
                   )
ef