Add Census covariate datasets

DESCRIPTION

@@ -1,14 +1,14 @@
 Package: debiasRdata
 Title: Empirical Data Companion for debiasR
-Version: 0.0.0.9002
+Version: 0.0.0.9003
 Authors@R:
     c(
       person("Francisco", "Rowe", email = "fcorowe@liverpool.ac.uk", role = c("aut", "cre")),
       person("Carmen", "Cabrera", email = "c.cabrera@liverpool.ac.uk", role = "aut")
     )
 Description: Documented empirical MSOA and LAD/LTLA travel-to-work
-    origin-destination data for debiasR examples, vignettes, validation
-    workflows, and empirical tests.
+    origin-destination data, area covariates, and supporting geography assets
+    for debiasR examples, vignettes, validation workflows, and empirical tests.
     The package supplies data assets only; bias adjustment, modelling, validation,
     and example-data loading logic remain in debiasR.
 License: file LICENSE

R/data.R

@@ -132,3 +132,74 @@
 #'
 #' @seealso [lad_OD_travel2work]
 "lad_centroids"
+
+#' Census 2021 MSOA covariates
+#'
+#' Selected Census 2021 topic-summary covariates for Middle Layer Super Output
+#' Areas (MSOAs), using the requested label-5 variable names from
+#' `dictionary.csv`.
+#'
+#' @format A data frame with 7,264 rows and 10 variables:
+#' \describe{
+#'   \item{area}{Character. MSOA21 code.}
+#'   \item{name}{Character. MSOA name.}
+#'   \item{year}{Integer. Census year.}
+#'   \item{per_ukborn}{Numeric. Percentage UK-born.}
+#'   \item{per_age_20.29}{Numeric. Percentage aged 20-29.}
+#'   \item{per_age_70plus}{Numeric. Percentage aged 70 or over.}
+#'   \item{per_level4}{Numeric. Percentage with level 4 qualifications.}
+#'   \item{per_hh_no_centralheat}{Numeric. Percentage of households without
+#'     central heating.}
+#'   \item{per_NS_SeC_L13_routine}{Numeric. Percentage in NS-SeC L13 routine
+#'     occupations.}
+#'   \item{rural_pct}{Numeric. Percentage rural.}
+#' }
+#'
+#' @source Office for National Statistics Census 2021 topic-summary inputs,
+#'   `combined-data-msoa.csv`, with variable names selected from
+#'   `dictionary.csv`. Source data are available under the Open Government
+#'   Licence v3.0.
+#'
+#' @details The packaged table renames `geography.code` to `area`,
+#'   `geography` to `name`, and `date` to `year`. The source column
+#'   `per_age_20-29` is renamed to the label-5/R-facing name
+#'   `per_age_20.29`. All covariates are finite numeric percentages between
+#'   0 and 100, and the areas cover the packaged MSOA OD flow assets.
+#'
+#' @seealso [msoa_OD_travel2work], [census_msoa_OD_travel2work]
+"msoa_covariates"
+
+#' Census 2021 LAD covariates
+#'
+#' Selected Census 2021 topic-summary covariates for Local Authority Districts
+#' (LADs), using the requested label-5 variable names from `dictionary.csv`.
+#'
+#' @format A data frame with 331 rows and 10 variables:
+#' \describe{
+#'   \item{area}{Character. LAD/LTLA area code.}
+#'   \item{name}{Character. LAD/LTLA name.}
+#'   \item{year}{Integer. Census year.}
+#'   \item{per_ukborn}{Numeric. Percentage UK-born.}
+#'   \item{per_age_20.29}{Numeric. Percentage aged 20-29.}
+#'   \item{per_age_70plus}{Numeric. Percentage aged 70 or over.}
+#'   \item{per_level4}{Numeric. Percentage with level 4 qualifications.}
+#'   \item{per_hh_no_centralheat}{Numeric. Percentage of households without
+#'     central heating.}
+#'   \item{per_NS_SeC_L13_routine}{Numeric. Percentage in NS-SeC L13 routine
+#'     occupations.}
+#'   \item{rural_pct}{Numeric. Percentage rural.}
+#' }
+#'
+#' @source Office for National Statistics Census 2021 topic-summary inputs,
+#'   `combined-data-lad.csv`, with variable names selected from
+#'   `dictionary.csv`. Source data are available under the Open Government
+#'   Licence v3.0.
+#'
+#' @details The packaged table renames `geography.code` to `area`,
+#'   `geography` to `name`, and `date` to `year`. The source column
+#'   `per_age_20-29` is renamed to the label-5/R-facing name
+#'   `per_age_20.29`. All covariates are finite numeric percentages between
+#'   0 and 100, and the areas cover the packaged LAD/LTLA OD flow assets.
+#'
+#' @seealso [lad_OD_travel2work], [census_lad_OD_travel2work]
+"lad_covariates"

R/paths.R

@@ -7,7 +7,7 @@
 #' @param name Character scalar naming a known packaged asset. Accepted values
 #'   are `"msoa_OD_travel2work"`, `"census_msoa_OD_travel2work"`,
 #'   `"lad_OD_travel2work"`, `"census_lad_OD_travel2work"`, and
-#'   `"lad_centroids"`.
+#'   `"lad_centroids"`, `"msoa_covariates"`, and `"lad_covariates"`.
 #'
 #' @return A character scalar containing the installed file path.
 #' @export
@@ -20,7 +20,9 @@ debiasRdata_path <- function(name) {
     census_msoa_OD_travel2work = "census_msoa_OD_travel2work.csv.gz",
     lad_OD_travel2work = "lad_OD_travel2work.csv.gz",
     census_lad_OD_travel2work = "census_lad_OD_travel2work.csv.gz",
-    lad_centroids = "lad_centroids.csv.gz"
+    lad_centroids = "lad_centroids.csv.gz",
+    msoa_covariates = "msoa_covariates.csv.gz",
+    lad_covariates = "lad_covariates.csv.gz"
   )
 
   if (!is.character(name) || length(name) != 1L || is.na(name) || !nzchar(name)) {

README.md

@@ -45,6 +45,9 @@ directly by `ODWP01EW_LTLA.csv`.
 lets `debiasR` compute selected-area LAD distances without packaging a full OD
 distance matrix.
 
+`msoa_covariates` and `lad_covariates` contain selected Census 2021
+topic-summary covariates for MSOA and LAD/LTLA areas.
+
 The four OD datasets use the same normalized schema:
 
 | Column | Type | Meaning |
@@ -53,6 +56,21 @@ The four OD datasets use the same normalized schema:
 | `destination` | character | Destination MSOA or LAD/LTLA code |
 | `flow` | numeric | Non-negative OD flow |
 
+The two covariate datasets use this schema:
+
+| Column | Type | Meaning |
+| --- | --- | --- |
+| `area` | character | MSOA or LAD/LTLA code |
+| `name` | character | Area name |
+| `year` | integer | Census year |
+| `per_ukborn` | numeric | Percentage UK-born |
+| `per_age_20.29` | numeric | Percentage aged 20-29 |
+| `per_age_70plus` | numeric | Percentage aged 70 or over |
+| `per_level4` | numeric | Percentage with level 4 qualifications |
+| `per_hh_no_centralheat` | numeric | Percentage of households without central heating |
+| `per_NS_SeC_L13_routine` | numeric | Percentage in NS-SeC L13 routine occupations |
+| `rural_pct` | numeric | Percentage rural |
+
 ## Usage
 
 ```r
@@ -63,6 +81,8 @@ head(census_msoa_OD_travel2work)
 head(lad_OD_travel2work)
 head(census_lad_OD_travel2work)
 head(lad_centroids)
+head(msoa_covariates)
+head(lad_covariates)
 ```
 
 `debiasR` consumes these objects conditionally:
@@ -83,6 +103,8 @@ debiasRdata_path("census_msoa_OD_travel2work")
 debiasRdata_path("lad_OD_travel2work")
 debiasRdata_path("census_lad_OD_travel2work")
 debiasRdata_path("lad_centroids")
+debiasRdata_path("msoa_covariates")
+debiasRdata_path("lad_covariates")
 ```
 
 The helper only locates installed files. It does not download data during
@@ -139,6 +161,19 @@ The LAD centroid table is derived from:
   northing, and longitude / latitude fields were retained and renamed to
   `area`, `name`, `easting`, `northing`, `longitude`, and `latitude`.
 
+The covariate tables are derived from:
+
+- Collection: Census 2021 topic-summary inputs
+- Source files: `combined-data-msoa.csv`, `combined-data-lad.csv`, and
+  `dictionary.csv`
+- Source institution: Office for National Statistics
+- License: Open Government Licence v3.0,
+  <https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/>
+- Packaged modifications: `geography.code` was renamed to `area`, `geography`
+  to `name`, and `date` to `year`; the seven requested label-5 covariates were
+  retained; source column `per_age_20-29` was renamed to the label-5/R-facing
+  name `per_age_20.29`.
+
 Build metadata, checksums, row counts, and transformation notes are recorded in
 `inst/metadata/source-metadata.json`.