What is cancensus
In the Introduction to the “Working with Statistics Canada Data in R” series, I discussed the three main types of data available from Statistics Canada. It is now time to move on to the second of those data types – the Canadian National Census data.
cancensus is a specialized R package that allows you to retrieve Statistics Canada census data and geography. It follows the tidy approach to data processing. The package’s authors are Jens von Bergmann, Dmitry Shkolnik, and Aaron Jacobs. I am not associated with the authors, I just use this great package in my work on a regular basis. The package’s GitHub repository can be found here. There is also a tutorial by the package’s authors, which I recommend taking a look at before proceeding.
Further in this series, I will provide an in-depth real-life example of working with Canadian Census data using the
cancensus package. But first, let’s install
Setting up cancensus: Adding API Key and Cache Path to .Rprofile
cancensus relies on queries to the CensusMapper API, which requires a CensusMapper API key. The key can be obtained for free as per the package authors’ instructions. Once you have the key, you can add it to your R environment:
options(cancensus.api_key = "CensusMapper_your_api_key")
Note that although the authors are warning that API requests are limited in volume, I have significantly exceeded my API quota on some occasions, and still had no issues with retrieving data.
That said, depending on how much data you need, you can draw down your quota very quickly, and here’s where local cache comes to the rescue.
cancensus caches data every time you retrieve it, but by default the cache is not persistent between sessions. To make it persistent, as well as to remove the need to enter your API key every time you use
cancensus, you can add both the API key and the cache path to your
If you’d like to learn in-depth what
.Rprofile is and how to edit it, consider taking a look at sections 2.4.2 to 2.4.5 of “Efficient R Programming” by Colin Gillespie and Robin Lovelace. For a quick and simple edit, just keep reading.
Editing .Rprofile on Linux
First, find your R home directory with
R.home(). Most likely, it will be in /usr/lib/R. If that is where your R home is, in the Linux Terminal (not in R), run:
sudo nano /usr/lib/R/library/base/R/.Rprofile # edit path if needed
On some systems, .Rprofile may not be hidden, so if the above command doesn’t open the
.Rprofile file, try removing the dot before ‘Rprofile’:
sudo nano /usr/lib/R/library/base/R/Rprofile
( ! ) Note that this will edit the system
.Rprofile file, which will always run on startup and will apply to all your R projects. The file itself will warn you that “it is a bad idea to use this file as a template for personal startup files”. You can safely ignore this warning as long as the only edit you are making is the one shown below, i.e. adding
cancensus cache path and API key.
In the “options” section, add these two lines (remember to paste in your CensusMapper API key and a path to the directory where you’d like to keep your
options(cancensus.api_key = "CensusMapper_your_api_key") options(cancensus.cache_path = "/home/your_username/path_to_your_R_directory/.cancensus_cache")
Y for “yes”, and press
Enter to save changes. When you first retrieve data with
cancensus, R will create
.cancensus_cache directory for you.
Editing .Rprofile on Windows
.Rprofile on Windows is a bit tricky. The best thing for you would be not to touch the Windows system
.Rprofile, or else risk weird errors and crashes (I was not able to figure out where they come from).
Instead, set up a project-specific
.Rprofile. The downside is that you may need to set it separately for every project in which you are going to use
cancensus. The upside is that the contents of the
.Rprofile file should be exactly the same every time. In R or Rstudio (not in the command line), run:
Or use the
usethis::edit_r_profile() function from the
Then, add these two lines and save the file:
options(cancensus.api_key = "CensusMapper_your_api_key") options(cancensus.cache_path = "C:\\Users\\Home\\Documents\\R\\cancensus_cache")
Note that when used inside R, backslash
\ symbols in file paths in Windows may need to be escaped with another
\ symbol. If this file path doesn’t work, try replacing duplicate
\\ with a single
At this point you should be ready to start retrieving data with
cancensus, which will be addressed in detail in my next post.