Browse the Statistics Canada PUMF collection on Borealis

Lists the Statistics Canada Public Use Microdata File datasets held in the [Borealis](https://borealisdata.ca) Dataverse (the ODESI PUMF collection and the Census PUMFs). Borealis carries vintages that Statistics Canada no longer posts, such as the 1971–1986 Census PUMFs. Any dataset listed here can be loaded with `get_pumf(series, version, borealis = <doi or row>)`; see [list_borealis_pumf_files()] to inspect a dataset's files first.

Usage

list_borealis_pumf_catalogue(
  refresh = FALSE,
  verbose = TRUE,
  cache_path = getOption("canpumf.cache_path")
)

Arguments

refresh

Logical, re-fetch the catalogue even when a cached copy exists.

verbose

Logical, report paging progress.

cache_path

Directory for the persisted catalogue; defaults to `getOption("canpumf.cache_path")`.

Value

A tibble with one row per dataset: `title`, `year` (the first year in the title), `language` (`"eng"`/`"fra"`, guessed from the title), `statcan` (logical, the dataset is also available from Statistics Canada), `statcan_series` and `statcan_title` (the matching StatCan catalogue entry, `NA` when none), `series` (the Borealis series name), `doi`, `dataverse`, `file_count`, `published_at` and `url`. English and French versions of a PUMF are separate datasets.

Details

Where Statistics Canada also posts a dataset for direct download, the `statcan` column is `TRUE`. Prefer StatCan's copy in that case (via `get_pumf(series, version)` without `borealis =`): the Borealis files are re-deposits and can carry transcription errors. `get_pumf()` warns when an explicitly requested Borealis dataset is flagged this way. The flag is a heuristic match on catalogue number, series title, years and cycle number against [list_statcan_pumf_catalogue()], so check `statcan_title` before relying on it.

The catalogue is fetched from the public Dataverse search API. There are several thousand datasets and Borealis renders them slowly, so pages are requested concurrently (`getOption("canpumf.borealis_parallel", 8)`), and a full fetch takes about a minute. The result is cached for the session and, when `canpumf.cache_path` is set, persisted to `<cache_path>/borealis_catalogue.rds`. A persisted copy older than `getOption("canpumf.catalogue_max_age_days", 30)` days triggers a warning. If Borealis is unreachable the last persisted copy is returned with a warning.

See also

[list_borealis_pumf_files()], [get_pumf()]

Examples

# \donttest{
# needs internet access; fails gracefully when Borealis is unreachable
cat <- tryCatch(list_borealis_pumf_catalogue(), error = function(e) NULL)
if (!is.null(cat)) dplyr::filter(cat, grepl("1971 Census", title))
#> # A tibble: 6 × 8
#>   title              year language doi   dataverse file_count published_at url  
#>   <chr>             <int> <chr>    <chr> <chr>          <int> <date>       <chr>
#> 1 1971 Census of P…  1971 eng      doi:… odesi-19…         13 2023-10-12   http…
#> 2 1971 Census of P…  1971 eng      doi:… odesi-19…         13 2023-10-12   http…
#> 3 1971 Census of P…  1971 eng      doi:… odesi-19…         13 2023-10-12   http…
#> 4 1971 Census of P…  1971 eng      doi:… odesi-19…         13 2023-10-12   http…
#> 5 1971 Census of P…  1971 eng      doi:… odesi-19…         13 2023-10-12   http…
#> 6 1971 Census of P…  1971 eng      doi:… odesi-19…         12 2023-10-12   http…
# }