A dataset with code table summaries for census data

Description

A dataset with code table summaries for census data

Author(s)

derived from StatCan definitions

References

https://www12.statcan.gc.ca/census-recensement/2021/geo/ref/domain-domaine/index2021-eng.cfm?lang=e&id=CSDtype, https://www12.statcan.gc.ca/census-recensement/2021/geo/ref/domain-domaine/index2021-eng.cfm?lang=e&id=CDtype

A dataset City of Vancouver skytrain station locations

Description

A dataset City of Vancouver skytrain station locations

Author(s)

City of Vancouver Open Data

References

https://opendata.vancouver.ca/explore/dataset/rapid-transit-stations/information/

Convenience function for creating unique names from region list

Description

Names of municipalities are not always unique, especially at the CSD level. This function takes as input a subset of a regions list as generated from 'list_census_regions()' and de-duplicates names as needed by adding the municipal status in parenthesis. If this does not de-duplicate the name then the geographic identifier will be further added in parenthesis behind that.

Usage

add_unique_names_to_region_list(region_list)

Arguments

Value

The same list of regions with an extra column 'Name' with de-duplicated names.

Examples

## Not run: 
# This will return a warning that no match was found, but will suggest similar named regions.
library(dplyr)
list_census_regions("CA21") %>%
  filter(level=="CSD", CMA_UID=="59933") %>%
  add_unique_names_to_region_list()

## End(Not run)

Convert a (suitably filtered) data frame from list_census_regions to a list suitable for passing to get_census.

Description

Convert a (suitably filtered) data frame from list_census_regions to a list suitable for passing to get_census.

Usage

as_census_region_list(tbl)

Arguments

Examples

## Not run: 
library(dplyr, warn.conflicts = FALSE)

# Query the CensusMapper API for the total occupied dwellings
# of 20 random Census Subdivisions, in Census 2016.
regions <- list_census_regions("CA16") %>%
  filter(level == "CSD") %>%
  sample_n(20) %>%
  as_census_region_list()

occupied <- get_census("CA16", regions = regions,
                            vectors = c("v_CA16_408"),
                            level = "Regions")

## End(Not run)

Return Census variable names and labels as a tidy data frame (Deprecated)

Description

Return Census variable names and labels as a tidy data frame (Deprecated)

Usage

census_vectors(x)

Arguments

Value

A data frame with a column variable containing the truncated variable name, and a column label describing it.

Examples

## Not run: 
# Query census data with truncated labels:
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CSD', geo_format = "sf", labels="short")

# Get details for truncated vectors:
census_vectors(census_data)

## End(Not run)

List all child variables from vector hierarchies given either a list of Census variables returned by list_census_vectors, search_census_vectors, find_census_vectors, or a direct string reference to the vector code.

Description

List all child variables from vector hierarchies given either a list of Census variables returned by list_census_vectors, search_census_vectors, find_census_vectors, or a direct string reference to the vector code.

Usage

child_census_vectors(
  vector_list,
  leaves_only = FALSE,
  max_level = NA,
  keep_parent = FALSE
)

Arguments

Examples

# Query parent vectors directly using vector identifier
child_census_vectors("v_CA16_2510")

## Not run: 

# Example using multiple vectors coerced into a list
child_census_vectors(c("v_CA16_2510","v_CA16_2511","v_CA16_2512"))

# or, equivalently
selected_vectors <- c("v_CA16_2510","v_CA16_2511","v_CA16_2512")
child_census_vectors(selected_vectors)

# Example using dplyr and piped arguments
library(dplyr, warn.conflicts = FALSE)

list_census_vectors("CA16") %>%
  filter(vector == "v_CA16_2510") %>%
  child_census_vectors(TRUE)

# this will return the equivalent of c("v_CA16_2510", child_census_vectors("v_CA16_2510"))
list_census_vectors("CA16") %>%
  filter(vector == "v_CA16_2510") %>%
  child_census_vectors(TRUE, keep_parent = TRUE)

## End(Not run)

Get attribution for datasets

Description

Get attribution for datasets

Usage

dataset_attribution(datasets)

Arguments

Value

Returns a string to be used as attribution for the given datasets.

Examples

# Attribution string for the 2006 and 2016 census datasets
dataset_attribution(c('CA06','CA16'))

Interactively browse Census variables and regions on Censusmapper.ca in a new browser window

Description

Finding the right Census variables or regions can be complicated. explore_census_vectors(dataset) and explore_census_regions(dataset) will open a new browser page or tab to an interactive Census variable and region exploration and selection tool on the Censusmapper.ca website. Interactive tools available for the CA16, CA11, CA06, and CA01 Census datasets and geographies.

Usage

explore_census_regions(dataset = "CA16")

Arguments

Examples

## Not run: 

explore_census_vectors(dataset = "CA16")

explore_census_regions(dataset = "CA11")


## End(Not run)

Interactively browse Census variables and regions on Censusmapper.ca in a new browser window

Description

Finding the right Census variables or regions can be complicated. explore_census_vectors(dataset) and explore_census_regions(dataset) will open a new browser page or tab to an interactive Census variable and region exploration and selection tool on the Censusmapper.ca website. Interactive tools available for the CA16, CA11, CA06, and CA01 Census datasets and geographies.

Usage

explore_census_vectors(dataset = "CA16")

Arguments

Examples

## Not run: 

explore_census_vectors(dataset = "CA16")

explore_census_regions(dataset = "CA11")


## End(Not run)

Query the CensusMapper API for vectors using exact, semantic, or keyword search

Description

Query the available list of Census vectors based on their label and return details including vector code. Default search behaviour expects an exact match, but keyword or semantic searches can be used instead by setting query_type='keyword' or query_type = 'semantic' instead. Keyword search is useful when looking to explore Census vectors based on broad themes like "income" or "language". Keyword search separates the query into unigrams and returns Census vectors with matching words, ranked by incidence of matches. Semantic search is designed for more precise searches while allowing room for error for spelling or phrasing, as well as for finding closely related vector matches. Semantic search separates the query into n-grams and relies on string distance measurement using a generalized Levenshtein distance approach.

Some census vectors return population counts segmented by Female and Male populations, in addition to a total aggregate. By default, query matches will return matches for the Total aggregation, but can optionally return only the Female or Male aggregations by adding type = 'female' or type = 'male' as a parameter.

Usage

find_census_vectors(query, dataset, type = "all", query_type = "exact", ...)

Arguments

Examples

find_census_vectors('Oji-cree', dataset = 'CA16', type = 'total', query_type = 'exact')

find_census_vectors('commuting duration', dataset = 'CA11', type = 'female', query_type = 'keyword')

find_census_vectors('after tax income', dataset = 'CA16', type = 'total', query_type = 'semantic')

## Not run: 
# This incorrect spelling will return a warning that no match was found,
# but will suggest trying semantic or keyword search.
find_census_vectors('Ojibwey', dataset = 'CA16', type = 'total')

# This will find near matches as well
find_census_vectors('Ojibwey', dataset = 'CA16', type = 'total', query_type = "semantic")

find_census_vectors('commute duration', dataset = 'CA16', type = 'female', query_type = 'keyword')

find_census_vectors('commute duration', dataset = 'CA11', type = 'all', query_type = 'keyword')

find_census_vectors('ukrainian origin', dataset = 'CA16', type = 'total', query_type = 'keyword')


## End(Not run)

Access to Canadian census data through the CensusMapper API

Description

This function allows convenient access to Canadian census data and boundary files through the CensusMapper API. An API key is required to retrieve data.

Usage

get_census(
  dataset,
  regions,
  level = NA,
  vectors = c(),
  geo_format = NA,
  resolution = "simplified",
  labels = "detailed",
  use_cache = TRUE,
  quiet = FALSE,
  api_key = Sys.getenv("CM_API_KEY")
)

Arguments

Details

For help selecting regions and vectors, see list_census_regions and list_census_vectors, or check out the interactive selection tool at https://censusmapper.ca/api by calling explore_census_vectors()

Source

Census data and boundary geographies are reproduced and distributed on an "as is" basis with the permission of Statistics Canada (Statistics Canada 1996; 2001; 2006; 2011; 2016).

Examples

# Query the API for data on dwellings in Vancouver, at the census subdivision
# level:
## Not run: 
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CSD')

# Query the API for data on dwellings in Vancouver, at the census subdivision
# level, and return the associated geography files in \code{sf} format:
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CSD', geo_format = "sf")

# Make the same query, but this time drop descriptive vector names:
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CSD', geo_format = "sf", labels="short")

# Get details for truncated vectors:
label_vectors(census_data)

## End(Not run)

Deprecated, use 'get_census' instead

Description

This function will be removed in future versions.

Usage

get_census_geometry(dataset, regions, level = NA, geo_format = "sf", ...)

Arguments

Source

Census data and boundary geographies are reproduced and distributed on an "as is" basis with the permission of Statistics Canada (Statistics Canada 2006; 2011; 2016).

Examples

# Query the API for data geographies in Vancouver, at the census subdivision
# level:
## Not run: 
# Query the API for geographies in Vancouver, at the census subdivision
# level, and return the associated geography files in \code{sf} format:
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          level='CSD', geo_format = "sf")

## End(Not run)

Get identifiers for census regions intersecting a geometry

Description

This function returns a list of regions that intersect a given geometry input. This list of regions can be used directly to query census when one is interested in census data for a particular geographic region that does not coincide with defined census geometries. The returned value can be used as the regions parameter in get_census to get corresponding census geographies and variables that cover the give geometry. Input spatial objects can be any sf or sfc class objects such as POINT, MULTIPOINT or POLYGON.

This function comes with CensusMapper API limits

Usage

get_intersecting_geometries(
  dataset,
  level,
  geometry,
  simplified = FALSE,
  use_cache = TRUE,
  quiet = FALSE,
  api_key = Sys.getenv("CM_API_KEY")
)

Arguments

Source

Census data and boundary geographies are reproduced and distributed on an "as is" basis with the permission of Statistics Canada (Statistics Canada 1996; 2001; 2006; 2011; 2016).

Examples

## Not run: 
# Example using a POINT-class object from a pair of lat/lon coordinates
point_geo <- sf::st_sfc(sf::st_point(c(-123.25149, 49.27026)), crs=4326)
regions <- get_intersecting_geometries(dataset = 'CA16', level = 'CT', geometry = point_geo)
census_data <- get_census(dataset='CA16', regions=regions,
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CT')

# Example using a POLYGON-class object from a bounding box with four coordinates
poly_geo <- sf::st_as_sfc(sf::st_bbox(c(ymin = 49.25, ymax = 49.30,
                          xmin = -123.25, xmax = -123.30)), crs = 4326)
regions <- get_intersecting_geometries(dataset = 'CA16', level = 'CT', geometry = poly_geo)
census_data <- get_census(dataset='CA16', regions=regions,
                         vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CT')


## End(Not run)

Get metadata for recalled data

Description

Grabs recall data from server if needed and returns list of recalled data

Usage

get_recalled_database(refresh = FALSE, warn_only_once = FALSE)

Arguments

Value

tibble with rows describing recalled data

Examples

## Not run: 
get_recalled_database()

## End(Not run)

Read the geosuite data

Description

Reads the geosuite data for the given level and census year. Data gets cached after first download if the cancensus cache path has been set. For older years 'get_statcan_geographic_attributes()' can fill in most of the information

Usage

get_statcan_geo_suite(level, census_year = "2021", refresh = FALSE)

Arguments

Value

tibble with the geosuite data

Examples

# list add the cached census data
## Not run: 
get_statcan_geo_suite("DA","2021")

## End(Not run)

Read the Geographic Attributes File

Description

Reads the Geographies Attributes File for the given census year. The table contains the information on how all the geographic levels are related for each area, and population, dwelling and household counts. Data gets cached after first download if the cancensus cache path has been set. A reference guide is available at https://www150.statcan.gc.ca/n1/en/catalogue/92-151-G2021001

Usage

get_statcan_geographic_attributes(census_year = "2021", refresh = FALSE)

Arguments

Value

tibble with the relationship data

Examples

# list add the cached census data
## Not run: 
get_statcan_geographic_attributes("2021")

## End(Not run)

Read the geosuite data

Description

Reads the original unprocessed geographic boundary files from Statistics Canada

Usage

get_statcan_geographies(
  census_year,
  level,
  type = "cartographic",
  cache_path = NULL,
  timeout = 1000,
  refresh = FALSE,
  quiet = FALSE
)

Arguments

Value

a spatial dataframe with the geographic data

Examples

# get the digital geographic boundaries for provinces and territories
## Not run: 
get_statcan_geographies(census_year="2021",level="PR",type="digital")

## End(Not run)

Read the Dissemination Geographies Relationship File

Description

Reads the Dissemination Geographies Relationship File for the given census year. The table contains the information on how all the geographic levels are related for each area. Data gets cached after first download if the cancensus cache path has been set. A reference guide is available at https://www150.statcan.gc.ca/n1/en/catalogue/982600032021001

Usage

get_statcan_geography_relationships(census_year = "2021", refresh = FALSE)

Arguments

Value

tibble with the relationship data

Examples

# list add the cached census data
## Not run: 
get_statcan_geography_relationships("2021")

## End(Not run)

Query the StatCan WDS for data

Description

Get official census data from Statistics Canada for a given set of DGUIDs. Only available for the 2021 census. The downloaded data gets enriched by geographic and characteristic names based on metadata obtained via 'get_statcan_wds_metadata()'. Data is cached for the duration of the R session.

Usage

get_statcan_wds_data(
  DGUIDs,
  members = NULL,
  version = NULL,
  gender = "All",
  language = "en",
  refresh = FALSE
)

Arguments

Value

tibble with the enriched census data

Examples

# get data for federal electoral district 2013A000459021
## Not run: 
get_statcan_wds_data(DGUIDs="2013A000459021",level="FED")

## End(Not run)

Query the StatCan WDS for metadata

Description

Get official metadata information from Statistics Canada for a given geographic level. Only available for the 2021 census. Data is cached for the duration of the R session.

Usage

get_statcan_wds_metadata(census_year, level, version = NULL, refresh = FALSE)

Arguments

Value

tibble with the metadata

Examples

# get metadata for federal electoral districts
## Not run: 
get_statcan_wds_metadata(census_year="2021",level="FED")

## End(Not run)

Return Census variable names and labels as a tidy data frame

Description

Return Census variable names and labels as a tidy data frame

Usage

label_vectors(x)

Arguments

Value

A data frame with a column variable containing the truncated variable name, and a column label describing it.

Examples

## Not run: 
# Query census data with truncated labels:
label_data <- get_census(dataset='CA16', regions=list(CMA="59933"),
                          vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"),
                          level='CSD', geo_format = "sf", labels="short")

# Get details for truncated vectors:
label_vectors(label_data)

## End(Not run)

List cached files

Description

Lists all cached data and metadata if available

Usage

list_cancensus_cache()

Value

tibble with metadata on cached data

Examples

# list add the cached census data
list_cancensus_cache()

Query the CensusMapper API for available datasets.

Description

Query the CensusMapper API for available datasets.

Usage

list_census_datasets(use_cache = TRUE, quiet = FALSE)

Arguments

Value

Returns a data frame with a column dataset containing the code for the dataset, a column description describing it, a geo_dataset column identifying the geography dataset the data is based on, a attribution column with an attribution string, a reference column with a reference identifier, and a reference_url column with a link to reference materials.

Examples

# List available datasets in CensusMapper
list_census_datasets()

Query the CensusMapper API for available regions in a given dataset.

Description

Query the CensusMapper API for available regions in a given dataset.

Usage

list_census_regions(dataset, use_cache = TRUE, quiet = FALSE)

Arguments

Value

Returns a data frame with the following columns:

region

The region identifier.

name

The name of that region.

level

The census aggregation level of that region.

pop

The population of that region.

municipal_status

Additional identifiers to distinguish the municipal status of census subdivisions.

CMA_UID

The identifier for the Census Metropolitan Area the region is in (if any).

CD_UID

The identifier for the Census District the region is in (if any).

PR_UID

The identifier for the Province the region is in (if unique).

Examples

## Not run: 
list_census_regions('CA16')

## End(Not run)

Query the CensusMapper API for available vectors for a given dataset.

Description

Query the CensusMapper API for available vectors for a given dataset.

Usage

list_census_vectors(dataset, use_cache = TRUE, quiet = TRUE)

Arguments

Value

Returns a data frame detailing the available Census vectors (i.e. variables) for a given Census dataset. This data frame has columns vector containing the short code for the variable, type describing whether it's a female, male, or total aggregate, label indicating the name of the variable, units indicating whether the value represents a numeric integer, percentage, dollar figure, or ratio, parent_vector to show hierarchical relationship, aggregation indicating whether the value is additive or a transformation, and a column details with a detailed description of the variable generated by traversing all labels within its hierarchical structure.

Examples

## Not run: 
# List all vectors for a given Census dataset in CensusMapper
list_census_vectors('CA16')

## End(Not run)

List recalled data stored in local cache

Description

Checks the local cached database for recalled data and lists all recalled cached entries

Usage

list_recalled_cached_data(
  cached_data = list_cancensus_cache(),
  warn_only_once = FALSE
)

Arguments

Value

tibble with rows describing locally cached recalled data

Examples

## Not run: 
list_recalled_cached_data()

## End(Not run)

List all parent variables from vector hierarchies given either a list of Census variables returned by list_census_vectors, search_census_vectors, find_census_vectors, or a direct string reference to the vector code.

Description

List all parent variables from vector hierarchies given either a list of Census variables returned by list_census_vectors, search_census_vectors, find_census_vectors, or a direct string reference to the vector code.

Usage

parent_census_vectors(vector_list)

Arguments

Examples

# Query parent vectors directly using vector identifier
parent_census_vectors("v_CA16_2519")
## Not run: 
# Example using multiple vectors coerced into a list
parent_census_vectors(c("v_CA16_2519","v_CA16_2520","v_CA16_2521"))

# or, equivalently
selected_vectors <- c("v_CA16_2519","v_CA16_2520","v_CA16_2521")
parent_census_vectors(selected_vectors)

# Example using dplyr and piped arguments
library(dplyr, warn.conflicts = FALSE)

list_census_vectors("CA16") %>%
  filter(vector == "v_CA16_2519") %>%
  parent_census_vectors()

## End(Not run)

Remove cached files

Description

Remove cached data for paths given

Usage

remove_from_cancensus_cache(paths)

Arguments

Value

freed-up disk space

Examples

## Not run: 
# remove the first cached dataset
cache_data <- list_cancensus_cache()

remove_from_cancensus_cache(cache_data$path[1])

## End(Not run)

Remove recalled data from local cache

Description

Checks the local cached database for recalled data and removes cached data that has been recalled

Usage

remove_recalled_cached_data()

Value

Storage size of removed locally cached data that got freed up in number of bytes.

Examples

## Not run: 
remove_recalled_cached_data()

## End(Not run)

Query the CensusMapper API for regions with names matching a searchterm.

Description

Runs a query against the CensusMapper API to retrieve region data with names matching specific queries. Users can optionally specify the target geography level (e.g. level = 'CMA', level = 'CSD', etc.). Alternatively, calling explore_census_vectors() will launch the interactive region selection tool on the CensusMapper site in a new web page or tab.

Usage

search_census_regions(searchterm, dataset, level = NA, ...)

Arguments

Value

A census region list of the same format as 'list_census_regions()' containing the matches.

Examples

## Not run: 
# This will return a warning that no match was found, but will suggest similar named regions.
search_census_regions('Victorea', 'CA16')

# This will limit region results to only include CMA level regions
search_census_regions('Victoria', 'CA16', level = "CMA")

## End(Not run)

Query the CensusMapper API for vectors with descriptions matching a search term or phrase (deprecated)

Description

Query the CensusMapper API for vectors with descriptions matching a search term or phrase (deprecated)

Usage

search_census_vectors(searchterm, dataset, type = NA, ...)

Arguments

Examples

search_census_vectors('Ojibway', 'CA16')
## Not run: 
# This will return a warning that no match was found, but will suggest similar terms.
search_census_vectors('Ojibwe', 'CA16', 'Total')

## End(Not run)

Set Censusmapper API key

Description

Cancensus requires a free Censusmapper API key to retrieve data. This function helps set the key for either the duration of the session (default) or permanently for use across sessions.

Usage

set_cancensus_api_key(key, overwrite = FALSE, install = FALSE)

Arguments

Examples

## Not run: 
set_cancensus_api_key("YOUR_CM_API_KEY")

# This will set the key permanently until overwritten again
set_cancensus_api_key("YOUR_CM_API_KEY", install = TRUE)

## End(Not run)

Set persistent cancensus cache location

Description

Cancensus provides session caching for retrieved data to increase speeds and reduce API usage. This function will create a persistent cache across sessions.

Usage

set_cancensus_cache_path(cache_path, overwrite = FALSE, install = FALSE)

Arguments

Examples

## Not run: 
set_cancensus_cache_path("~/cancensus_cache")

# This will set the cache path permanently until overwritten again
set_cancensus_cache_path("~/cancensus_cache", install = TRUE)

## End(Not run)

View saved Censusmapper API key

Description

View saved API key'

Usage

show_cancensus_api_key()

Examples

show_cancensus_api_key()

View saved cache directory path

Description

View saved cache path'

Usage

show_cancensus_cache_path()

Examples

show_cancensus_cache_path()