geogConvert: Convert source geography to destination geography, when no...

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

Convert source geography to destination geography, when no age or sex data is available.

Description

Converts a one-dimensional population database to another geography using a conversion table and, likely, prorating as needed.

Usage

geogConvert(
  db,
  TypeTo = "CH",
  conv_table,
  conv_path = NULL,
  years = NULL,
  allowNegatives = FALSE,
  readFiles = FALSE
)

Arguments

db	Data variable containing the source database to be converted. Expects data to be in data.frame with columns: Year, Type, TypeID, Total. (If Age, Male or Female are included, function will stop and ask for such columns to be dropped or to use dbConvert instead.) If 'readFiles' is set to TRUE, 'db' should be the name of the source database to be read in (e.g., "POPECS21") or full path to csv file of the source database.
TypeTo	Two-character geographical code for the type of destination geography. Default = "CH" for CHSA (Community Health Service Area).
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). This is not necessary if 'conv_path' is set instead.
conv_path	The full path to the conversion table Excel file. Default = NULL. If NULL, the function requires that 'conv_table' be set. This is an alternate method to reading in the conversion table.
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.
allowNegatives	Logical value for whether or not negative population values are allowed. Default = FALSE. Only migration data should be allowed to have negative values.
readFiles	Logical value for whether or not db file needs to be read in. Default = FALSE. If FALSE, file is already in environment, likely by being called or created through another function (e.g., dbRead).

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. This function differs from dbConvert in that there are no age or sex variables in the database. Therefore, raking is not required; only, prorating will be needed to ensure that the destination geographies total sums to source geographies total (for each year). This function will likely only be used during Estimates Breakdown System (EBS) to convert lowest-level geographies from Statistics Canada (Census Sub-divisions, aka "CS" or "CSD") to the lowest-level geography BC Stats produces (CHSAs, aka "CH").

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 prorating (subset of steps taken in dbRake). If Step (1) removed some 1-to-1 regions, the control totals will be adjusted downward. Destination control totals (aka, "control region totals") are set as NULL and will be generated during the prorating process.

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 prorating was also done.

See Also

Overall package documentation: dbutils()

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

Examples

## Not run:   geogConvert(db = CSDs_to_convert, conv_table = "Table-CSD-CHSA-2021.xlsx")  
## Not run:   geogConvert(db = CSDs_to_convert, conv_path = "I:/ConversionTables/Table-CSD-CHSA-2021.xlsx")  

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