dbRead: Read population database

In bcgov/dbutils: Utility functions to process and modify BC Stats' population databases

Read population database

Description

Reads a population database file (population, births, deaths) in default database format (Year, Type, TypeID, Age, Male, Female, Total) and returns data. Database path can be either a full path to a csv database file with the correct columns, or a vector including the type, region and year of database to be used through getDBPath. For example, db_path = c("estimates", "HA", "19") would read the July 1st 2019 population estimates database for Local Health Areas. Format of loaded data can be adjusted to default, long or wide and pre-filtered for specific age groups.

Note that dbCheck is run before reading the file. User will be warned if any database checks fail.

Usage

dbRead(
  db_path,
  return_format = "default",
  age_filter = NULL,
  db_check = TRUE,
  full_BC = TRUE
)

Arguments

db_path	Either vector of database type ("estimates", "projections", "births", "deaths"), region code and two-character year OR full path to database csv file.
return_format	Format of returned data.frame. Default is the same columns as default database format (Year, Type, TypeID, Age, Male, Female, Total), long format gathers sex as a new column (Year, Type, TypeID, Age, Sex, N), wide format gathers sex as a new column and spreads ages as columns (Year, Type, TypeID, Sex, 0, 1,... 89, 90+, Total). Allowed values are "default", "long" or "wide". Default = "default".
age_filter	Filters ages based on input vector before returning data in requested format. Must be a vector. Default = NULL.
db_check	Logical value whether to run dbCheck on data. Default = TRUE. This should be set to FALSE only if specific database is known to be ok, or to troubleshoot database errors other than column names (i.e., NOT database error 1a or 1b. That is, database must have the 7 columns: Year, Type, TypeID, Age, Male, Female, and Total).
full_BC	Logical value whether the region covers all of BC. Those regions (e.g., CMAs) that do not cover all of BC have full_BC = FALSE, and their sum is not checked against the BC total. Default = TRUE.

Details

The complete list of region IDs and ages for each type of database (population, deaths, births) can be found in dbutils. For historical reasons, population data is saved as POPRREYY (population estimates), POPRRPYY (population projections), BIRRRYY (births) or DEARRYY (deaths), where RR is the shorthand for the region code, and YY is the last two digits of the year.

Value

A data.frame object in the requested format.

Author(s)

Sebastien Lavoie (formerly, BC Stats)

See Also

Overall package documentation: dbutils()

Other database access helpers: dbCheck(), dbInfo(), dbWrite(), getDBPath()

Examples

dbRead(c("estimates", "HA", "19"), return_format = "wide", age_filter = c(0, 1, 2, 3, 4, -999))
## Not run:    dbRead("I://PopulationR/Database/Estimates/POPHAE19.csv", return_format = "wide",
                   age_filter = c(0, 1, 2, 3, 4, -999))  
## End(Not run)
dbRead(c("births", "HA", "19"), db_check = FALSE)

bcgov/dbutils documentation built on Sept. 30, 2022, 12:04 a.m.