Returns a data frame with summary statistics for each entity based on the homefield map.
This function requires a CENSUS API Key.
Follow the directions here
to receive a key.
Usage
homefield_stats(
x,
continental = TRUE,
temporal = NULL,
keep_max = FALSE,
keep_visuals = FALSE
)Arguments
- x
(Required): Data frame created by other homefield functions or including the following columns:
entity - identifies each entity (ex. school name - Iowa State, Minnesota, Bowling Green).
lat - latitude of entity.
lng - longitude of entity.
color - (Optional:) hexadecimal color (ex. #cfab7a) useful for plotting with homefield_map(). Set keep_visuals = TRUE to include this column in the returned data frame.
image - (Optional:)image url or local file path useful for plotting with homefield_map(). Set keep_visuals = TRUE to include this column in the returned data frame.
Columns must also be of equal length and match the specified names exactly.- continental
(Optional - Boolean required):
If TRUE (default), only considers the continental United States.
If FALSE, also considers Alaska and Hawaii.- temporal
(Optional - Vector of date-time values required): This will alter the returned data frame to include an extra column named 'time' with the supplied temporal information in a tidy format.
The vector should contain temporal values representing the respective time of each data frame. If argument declared with a vector, x must be a list of data frames. The length of the vector supplied must equal the number of data frames in x.- keep_max
(Optional - Boolean required:) In some cases, a entity may no longer be present in future temporal instances.
If keep_max = TRUE, entities will be generated for future instances and their statistics will match the instance where they were most recently present.
If keep_max = FALSE (default), entities will be generated in future instances but their statistics will be set to 0.
If keep_max = NULL, entities will NOT be generated in future instances where they do not appear already.- keep_visuals
(Optional - Boolean required:) If x has color and image columns present, keep_visuals can be used to discard or keep these columns in the returned data frame.
If keep_visuals = TRUE, the columns will be kept.
If keep_visuals = FALSE (default), the columns will be removed.
Value
Output data frame includes four summary statistics:
land - Total land area area (in square meters) within territory
controlled by entity.
water - Total land area area (in square meters) within territory
controlled by entity.
domain - Sum of land and water area (in square meters) within
territory controlled by entity.
pop - Population that resides within territory controlled by entity.
Examples
if (FALSE) {
# standard example
cfb_map_stats <- homefield_stats(cfb_undefeated(season = 2021, week = 6))
# temporal example
x_input <- list(cfb_undefeated(season = 2021, week = 0),
cfb_undefeated(season = 2021, week = 1),
cfb_undefeated(season = 2021, week = 2),
cfb_undefeated(season = 2021, week = 3),
cfb_undefeated(season = 2021, week = 4))
# week 0 through 4
temporal_input <- lubridate::ymd(c("2021-08-28",
"2021-09-04",
"2021-09-11",
"2021-09-18"))
map_stats <- homefield::homefield_stats(x = x_input,
temporal = temporal_input)
}