dbConvert: Convert population database

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

Convert population database

Description

Converts a population database to another geography using a conversion table and, possibly, raking.

Usage

dbConvert(
  db,
  conv_table,
  years = NULL,
  rake = TRUE,
  change_rake_args = FALSE,
  full_BC = TRUE
)

Arguments

db	Data variable containing the source database to be converted. Expects data to be in data.frame with columns: Year, Type, TypeID, Age, Male, Female, Total.
conv_table	Name of conversion table to be read in to provide the proportional relationship ("split") between source and destination geographies. Conversion table path is hardcoded to ensure consistency across population systems, and will find conversion table in ".../ConversionTables/" folder (on the LAN).
years	Vector of one or more years to be included in the converted destination data. Default = NULL. If NULL, the function will convert for all years in the source data. If not NULL, the function will convert only the year(s) specified, but return all years in source data (which can be confusing; therefore, it is recommended to include in db only the year(s) to be converted.)
rake	Whether raking is required (default) or not. Default = TRUE. While the dbRake function requires InputData and CtrlPopTotals (either already in the environment or to be read in from an "inputs" folder), 'dbConvert' will create these from "db" and the conversion table, so does not need these arguments specified.
change_rake_args	Logical value whether raking argument defaults need to be changed. Default = FALSE. If set to TRUE, user will be asked to set the following arguments: CtrlAgeGrpsTotals (default = NULL); VarRegion (otherwise pre-specified as From geography found in name of the conversion table, e.g., HA); VarSex (otherwise pre-specified as "Sex"); VarSexTotal (otherwise pre-specified from data's column names); AgeGrpMax (default = NULL which would trigger dbRake to use age 75 if exists; however, dbConvert sets this to the strongly recommended age 75); allowNegatives (default = FALSE, should only be TRUE for migration data); saveInterimFiles (default = FALSE); writeOutputFile (default = FALSE); writeRakingLog (default = FALSE). Regardless of 'change_rake_args' value, dbRake's argument 'readFiles' will be set to FALSE because the input files will be created during the conversion process.
full_BC	Logical value whether the region covers all of BC. Default = TRUE. Those regions (e.g., VI, CMAs) that do not cover all of BC should have full_BC = FALSE, and their sum is not checked against the BC total. As well, during conversion, source geographies not included in the destination geographies are dropped from the From and To working datafiles.

Details

Conversion tables should be in the ".../ConversionTables/" LAN folder so that they can be found, and are expected to be .xlsx files with three unnamed columns with the proportional relationship (aka, "split"), source and destination geographies.

The conversion process is as follows:

1. Evaluate the conversion table between Geography A (source)and B (destination) for regions that require no conversion (i.e., regions are converted 1-to-1 from Geography A to B). Remove these regions from the conversion process.

2. Sequentially share out the data relating to the region in Geography A using the conversion factor to the respective region(s) in Geography B.

3. Aggregate Geography B components that received contributions from multiple regions in Geography A.

4. If not all regions are 1-to-1, "split" destination geographies must conform to source totals (aka, "control population totals"), achieved using raking (dbRake). If Step (1) removed some 1-to-1 regions, the control totals will be adjusted downward. Destination control totals (aka, "control region totals", or dbRake's "CtrlRegionTotals") are set as NULL and will be generated during the raking process from the converted destination data (aka, "InputData").

5. Any 1-to-1 regions removed during Step (1) are added back to Geography B (under the Geography B naming convention).

Value

Database converted from source to destination geography. If not all allocations were 100, (i.e., some splits < 100), then raking was also done (unless explicitly set to FALSE). Note that Age can be a positive age (e.g., 0, 1, 2, ...), a 5-year age group (e.g., 0-4) or TOTAL.

See Also

Overall package documentation: dbutils()

Other conversion helpers: conversionRead(), conversionTables(), geogConvert()

Examples

## Not run:  dbConvert(db = "POPHAP20", conv_table = "Table-LHA-HSDA-2019.xlsx", rake = FALSE)  ## all 100%
## Not run:  dbConvert(db = "POPHAP20", conv_table = "Table-LHA-SD-2019")           ## some split
## Not run:  dbConvert(db = "POPCSE21", conv_table = "Table-CSD-VI_NO_CRD-2020", full_BC = FALSE) 

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