Package 'statcanR'

Download a Statistics Canada data table

Description

Downloads a complete table from Statistics Canada's Web Data Service (WDS) and returns it as a data frame. Product IDs can be supplied in the familiar hyphenated form (for example, "27-10-0014-01") or as an eight-digit PID (for example, "27100014").

Usage

statcan_data(tableNumber, lang)

Arguments

tableNumber	A Statistics Canada table number or Product ID. Both "27-10-0014-01" and "27100014" are accepted.
lang	Language of the downloaded table: "eng" or "fra".

Details

The function keeps the interface used by earlier statcanR releases. English and French downloads share the same processing rules. In particular, the first column is named REF_DATE, coordinates are stored as character, and the table title from the metadata file is added as INDICATOR.

Value

A data frame containing the complete Statistics Canada table.

Examples

## Not run: 
science <- statcan_data("27-10-0014-01", "eng")
science_fr <- statcan_data("27100014", "fra")

## End(Not run)

---

Download a Statistics Canada table and save a CSV file

Description

Calls statcan_data() and also writes the returned table to a CSV file. Existing calls with only tableNumber and lang remain supported; path can be used to select a different output directory.

Usage

statcan_download_data(tableNumber, lang, path = ".")

Arguments

tableNumber	A Statistics Canada table number or Product ID. Both "27-10-0014-01" and "27100014" are accepted.
lang	Language of the downloaded table: "eng" or "fra".
path	Directory in which to save the CSV file. The directory must already exist. Defaults to the current working directory.

Value

The downloaded table. The CSV path is available in the statcan_file attribute of the returned data frame.

Examples

## Not run: 
science <- statcan_download_data("27-10-0014-01", "eng")
science <- statcan_download_data(
  "27-10-0014-01", "eng", path = tempdir()
)
attr(science, "statcan_file")

## End(Not run)

---

Find Statistics Canada tables using a natural-language query

Description

Interprets a short description of the data needed and returns ranked Statistics Canada table candidates. The query can contain a topic, Canadian geography, and reference year or range. For example, "R&D expenditures in Quebec since 2020" is interpreted as a research and development expenditure topic, a Quebec geography constraint, and coverage beginning in 2020.

Usage

statcan_find(query, lang = c("eng", "fra"), n = 5L, refresh = FALSE)

Arguments

query	One non-empty character string describing the desired data.
lang	Language of the table titles: "eng" or "fra".
n	Maximum number of candidates to return, from 1 to 20.
refresh	Logical; if TRUE, request a fresh catalogue and fresh candidate metadata from WDS.

Details

This function finds tables; it does not download or filter their observations. Use the returned id with statcan_data(), then apply any required geography and date filters to the downloaded data. Rankings are a discovery aid, so review the candidate title before downloading a large table.

The catalogue is cached for 24 hours. When a geography is present in the query, metadata for a small set of leading candidates is retrieved through WDS to confirm that the geography is a table member. That metadata is cached for seven days. If metadata is temporarily unavailable, candidates can still be returned with geography_match = NA.

Value

A data frame of ranked candidates. id contains the table number, score is the relevance score, and match_reason explains the ranking. Coverage dates describe the table as a whole. geography_match is TRUE when WDS metadata confirms every geography in the query, FALSE when it does not, and NA when no geography was requested or validation was not possible.

Examples

## Not run: 
matches <- statcan_find(
  "R&D expenditures in Quebec since 2020",
  lang = "eng"
)
matches[, c("title", "id", "match_reason")]

## End(Not run)

---

Search Statistics Canada data tables

Description

Searches the catalogue of tables published through Statistics Canada's Web Data Service (WDS). The catalogue is cached for 24 hours in the user's cache directory. If WDS is temporarily unavailable, the most recent valid cache is used.

Usage

statcan_search(keywords, lang = c("eng", "fra"), refresh = FALSE)

Arguments

keywords	Character vector of words that must appear in the table title. Matching is case-insensitive.
lang	Language of the returned titles: "eng" or "fra".
refresh	Logical; if TRUE, ignore a fresh cache and request the catalogue from WDS.

Value

A DT::datatable containing matching table titles, Product IDs, release dates, and language.

Examples

## Not run: 
statcan_search(c("economy", "export"), "eng")
statcan_search("population", "fra")

## End(Not run)

---