Add a population column to an outcome table, for use as a population offset in timeseries_1stage_glm()
add_population_offset.Rdmake_outcome_table() doesn't produce a population column, since it's not
needed for the conditional Poisson design (condPois_1stage). It IS
needed for the time-series design (timeseries_1stage_glm) if you want to
adjust for population size/changes via population_col. This helper joins
a separate population dataset onto an already-built outcomes_tbl,
matching on geo_unit + either year or date (whichever granularity your
population data has), and validates that every row got a match before
returning.
Usage
add_population_offset(
outcomes_tbl,
population_data,
population_columns,
population_col_name = "population",
verbose = TRUE
)Arguments
- outcomes_tbl
an object of class "outcome", as produced by
make_outcome_table()- population_data
a data.frame/data.table of population estimates. Commonly one row per geo_unit per year (e.g. annual census/ACS estimates), but can also be one row per geo_unit per day if you have finer-grained estimates.
- population_columns
a named list mapping columns in
population_data. Must include:"geo_unit": column identifying the geographic unit (must use the same codes/values as outcomes_tbl's geo_unit column)"population": column with the population value (numeric, > 0)EITHER
"year"(integer year, for annual population data – the typical case) OR"date"(for daily/finer population data) – supply exactly one of these, not both
- population_col_name
name of the new column to add to
outcomes_tbl. Default "population". This is the string you'd then pass aspopulation_coltotimeseries_1stage_glm().- verbose
print a short confirmation message. Default TRUE.
Value
outcomes_tbl with a new population column added, class
"outcome" and column_mapping attributes preserved
Examples
# outcomes_tbl already built via make_outcome_table()
# boston_deaths_tbl <- make_outcome_table(boston_deaths, outcome_columns,
# time_subset = list(month = 5:9))
# suppose you have annual town-level population estimates:
# head(ma_population)
# TOWN20 year population
# BOSTON 2010 617594
# BOSTON 2011 624567
population_columns <- list(
"geo_unit" = "TOWN20",
"year" = "year",
"population" = "population"
)
# boston_deaths_tbl <- add_population_offset(
# outcomes_tbl = boston_deaths_tbl,
# population_data = ma_population,
# population_columns = population_columns
# )
# then:
# m1_ts <- timeseries_1stage_glm(
# exposure_matrix = boston_exposure_mat,
# outcomes_tbl = boston_deaths_tbl,
# time_trend = "season",
# population_col = "population"
# )