Package 'cancensus'

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)

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)

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

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/

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'))

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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()

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()

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Description

View saved API key'

Usage

show_cancensus_api_key()

Examples

show_cancensus_api_key()

Description

View saved cache path'

Usage

show_cancensus_cache_path()

Examples

show_cancensus_cache_path()