Thematic choropleth maps are used to display quantities of some variable within areas, such as mapping median income across a city’s neighborhoods. However, we often think in bivariate terms - “how do race and income vary together?”. Maps that captures this, known as bivariate choropleth maps, are often perceived as difficult to create and interpret. The goal of
biscale is to implement a consistent approach to bivariate mapping entirely within
R. The package’s workflow is based on a recent tutorial written by Timo Grossenbacher and Angelo Zehr, and supports both two-by-two and three-by-three bivariate maps.
Since the package does not directly use functions from
sf, it is a suggested dependency rather than a required one. However, the most direct approach to using
biscale is with
sf objects, and we therefore recommend users install
sf before proceeding with using
biscale. Windows users should be able to install
sf without significant issues, but macOS and Linux users will need to install several open source spatial libraries to get
sf itself up and running. The easiest approach for macOS users is to install the GDAL 2.0 Complete framework from Kyng Chaos.
For Linux users, steps will vary based on the flavor being used. Our configuration file for Travis CI and its associated bash script should be useful in determining the necessary components to install.
sf is installed, the easiest way to get
biscale is to install it from CRAN:
Alternatively, the development version of
biscale can be accessed from GitHub with
All functions within
biscale use the prefix
bi_ to leverage the auto-completion features of RStudio and other IDEs.
biscale contains a data set of U.S. Census tracts for the City of St. Louis in Missouri. Both median income and the percentage of white residents are included, both of which can be used to demonstrate the package’s functionality.
Once data are loaded, bivariate classes can be applied with the
Note that, as of v0.2 of the
sf is imported when you load
biscale. This resolves issues related to not loading
sf ahead of time, though it does add a dependency that a small number of users may have wished not to install.
dim argument is used to control the extent of the legend - do you want to produce a two-by-two map (
dim = 2) or a three-by-three map (
dim = 3)?
Classes can be applied with the
style parameter using four approaches for calculating breaks:
"jenks". The default
"quantile" approach will create relatively equal “buckets” of data for mapping, with a break created at the median (50th percentile) for a two-by-two map or at the 33rd and 66th percentiles for a three-by-three map.
With the sample data, this creates a very broad range for the percent white measure in particular. Using one of the other approaches to calculating breaks yields a narrower range for the breaks and produces a map that does not overstate the percent of white residents living on the north side of St. Louis: