Type: | Package |
Title: | Tools and Palettes for Bivariate Thematic Mapping |
Version: | 1.0.0 |
Description: | Provides a 'ggplot2' centric approach to bivariate mapping. This is a technique that maps two quantities simultaneously rather than the single value that most thematic maps display. The package provides a suite of tools for calculating breaks using multiple different approaches, a selection of palettes appropriate for bivariate mapping and scale functions for 'ggplot2' calls that adds those palettes to maps. Tools for creating bivariate legends are also included. |
Depends: | R (≥ 3.5) |
License: | GPL-3 |
URL: | https://chris-prener.github.io/biscale/ |
BugReports: | https://github.com/chris-prener/biscale/issues |
Encoding: | UTF-8 |
LazyData: | true |
Imports: | classInt, ggplot2, stats, utils |
RoxygenNote: | 7.1.2 |
Suggests: | covr, cowplot, knitr, rmarkdown, sf, testthat |
VignetteBuilder: | knitr |
NeedsCompilation: | no |
Packaged: | 2022-05-26 18:11:15 UTC; chris |
Author: | Christopher Prener
|
Maintainer: | Christopher Prener <chris.prener@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2022-05-27 08:40:09 UTC |
Create Classes for Bivariate Maps
Description
Creates mapping classes for a bivariate map. These data will be stored
in a new variable named bi_class
, which will be added to the given
data object.
Usage
bi_class(.data, x, y, style, dim = 3, keep_factors = FALSE, dig_lab = 3)
Arguments
.data |
A data frame, tibble, or |
x |
The |
y |
The |
style |
A string identifying the style used to calculate breaks. Currently
supported styles are Note that older versions of |
dim |
The dimensions of the palette. To use the built-in palettes,
this value must be either If you are using a custom palette, this value may be larger (though these maps can be very hard to interpret). If you are using pre-made factors, both factors must have the same number of levels as this value. |
keep_factors |
A logical scalar; if |
dig_lab |
An integer that is passed to |
Value
A copy of .data
with a new variable bi_class
that contains
combinations of values that correspond to an observations values for x
and y
. This is the basis for applying a bivariate color palette.
Examples
# quantile breaks, 2x2
data <- bi_class(stl_race_income, x = pctWhite, y = medInc, style = "quantile", dim = 2)
# summarize quantile breaks, 2x2
table(data$bi_class)
# quantile breaks, 3x3
data <- bi_class(stl_race_income, x = pctWhite, y = medInc, style = "quantile", dim = 3)
# summarize quantile breaks, 3x3
table(data$bi_class)
Return Breaks
Description
This function can be used to return a list containing vectors
of either the ranges of values included in each category of x
and y
or, alternatively, the individual break values including
the minimum and maximum values. This function supports simplified
reporting as well as more descriptive legends.
Usage
bi_class_breaks(.data, x, y, style, dim = 3, clean_levels = TRUE,
dig_lab = 3, split = FALSE)
Arguments
.data |
A data frame, tibble, or |
x |
The |
y |
The |
style |
A string identifying the style used to calculate breaks. Currently
supported styles are |
dim |
The dimensions of the palette. To use the built-in palettes,
this value must be either If you are using a custom palette, this value may be larger (though these maps can be very hard to interpret). If you are using pre-made factors, both factors must have the same number of levels as this value. |
clean_levels |
A logical scalar; if |
dig_lab |
An integer that is passed to |
split |
A logical scalar; if |
Value
A list where bi_x
is a vector containing the breaks for the
x
variable and bi_y
is a vector containing the breaks for
the y
variable.
Examples
# return ranges for each category of x and y
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
dim = 4, dig_lab = c(4, 5), split = FALSE)
# ranges can be returned with brackets and parentheses
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
clean_levels = FALSE, dim = 4, dig_lab = 3, split = FALSE)
# return breaks for each category of x and y
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
dim = 4, dig_lab = c(4, 5), split = TRUE)
# optionally name vector for dig_lab for increased clarity of code
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
dim = 4, dig_lab = c(x = 4, y = 5), split = TRUE)
# scalars can also be used for dig_lab, though results may be less optimal
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
dim = 4, dig_lab = 3, split = TRUE)
Create Object for Drawing Legend
Description
Creates a ggplot
object containing a legend that is
specific to bivariate mapping.
Usage
bi_legend(pal, dim = 3, xlab, ylab, size = 10, flip_axes = FALSE,
rotate_pal = FALSE, pad_width = NA, pad_color = "#ffffff",
breaks = NULL, arrows = TRUE)
Arguments
pal |
A palette name or a vector containing a custom palette. See
the help file for |
dim |
The dimensions of the palette. To use the built-in palettes,
this value must be either If you are using a custom palette, this value may be larger (though these
maps can be very hard to interpret). See the 'Advanced Options' vignette
for details on the relationship between |
xlab |
Text for desired x axis label on legend |
ylab |
Text for desired y axis label on legend |
size |
A numeric scalar; size of axis labels |
flip_axes |
A logical scalar; if |
rotate_pal |
A logical scalar; if |
pad_width |
An optional numeric scalar; controls the width of padding between tiles in the legend |
pad_color |
An optional character scalar; controls the color of padding between tiles in the legend |
breaks |
An optional list created by |
arrows |
A logical scalar; if |
Value
A ggplot
object with a bivariate legend.
See Also
Examples
# sample 3x3 legend
legend <- bi_legend(pal = "GrPink",
dim = 3,
xlab = "Higher % White ",
ylab = "Higher Income ",
size = 16)
# print legend
legend
# sample 3x3 legend with breaks
## create vector of breaks
break_vals <- bi_class_breaks(stl_race_income, style = "quantile",
x = pctWhite, y = medInc, dim = 3, dig_lab = c(x = 4, y = 5),
split = TRUE)
## create legend
legend <- bi_legend(pal = "GrPink",
dim = 3,
xlab = "Higher % White ",
ylab = "Higher Income ",
size = 16,
breaks = break_vals,
arrows = FALSE)
# print legend
legend
Preview Palettes and Hex Values
Description
Prints either a visual preview of each palette or the associated hex values.
Usage
bi_pal(pal, dim = 3, preview = TRUE, flip_axes = FALSE, rotate_pal = FALSE)
Arguments
pal |
A palette name or a vector containing a custom palette.
If you are providing a palette name, it must be one of:
Pairs of palettes, such as If you are providing a custom palette, it must follow the formatting described in the 'Advanced Options' vignette. |
dim |
The dimensions of the palette. To use the built-in palettes,
this value must be either If you are using a custom palette, this value may be larger (though these
maps can be very hard to interpret). See the 'Advanced Options' vignette
for details on the relationship between |
preview |
A logical scalar; if |
flip_axes |
A logical scalar; if |
rotate_pal |
A logical scalar; if |
Details
The "Brown"
, "DkBlue"
, "DkCyan"
, and "GrPink"
palettes were made by
Joshua Stevens.
The "DkViolet"
palette was made by
Timo Grossenbacher and Angelo Zehr.
Many of the new palettes were inspired by Branson Fox's earlier work to expand
biscale
.
Value
If preview = TRUE
, an image preview of the legend will be returned.
Otherwise, if preview = FALSE
, a named vector with class values for names
and their corresponding hex color values.
Examples
# gray pink palette, 2x2
bi_pal(pal = "GrPink", dim = 2)
# gray pink palette, 2x2 hex values
bi_pal(pal = "GrPink", dim = 2, preview = FALSE)
# gray pink palette, 3x3
bi_pal(pal = "GrPink", dim = 3)
# gray pink palette, 3x3 hex values
bi_pal(pal = "GrPink", dim = 3, preview = FALSE)
# custom palette
custom_pal <- c(
"1-1" = "#cabed0", # low x, low y
"2-1" = "#ae3a4e", # high x, low y
"1-2" = "#4885c1", # low x, high y
"2-2" = "#3f2949" # high x, high y
)
bi_pal(pal = custom_pal, dim = 2, preview = FALSE)
Create Manual Palette
Description
This function has been deprecated and will be removed from the next release of the package. See the Advanced Options vignette for a replacement workflow.
Usage
bi_pal_manual(val_1_1, val_1_2, val_1_3, val_2_1, val_2_2, val_2_3,
val_3_1, val_3_2, val_3_3, preview = FALSE)
Arguments
val_1_1 |
A hex value for cell 1-1 |
val_1_2 |
A hex value for cell 1-2 |
val_1_3 |
A hex value for cell 1-3 |
val_2_1 |
A hex value for cell 2-1 |
val_2_2 |
A hex value for cell 2-2 |
val_2_3 |
A hex value for cell 2-3 |
val_3_1 |
A hex value for cell 3-1 |
val_3_2 |
A hex value for cell 3-2 |
val_3_3 |
A hex value for cell 3-3 |
preview |
A logical scalar; if |
Details
A function for structuring manual bi-variate palettes. All values must be entered as six-digit hex values (e.g. #000000) and must be preceded by the number symbol. Short forms of hex values (e.g. #000) are not accepted as valid inputs. For two-by-two palettes, only the 'val_1_1', 'val_1_2', 'val_2_1', and 'val_2_2' parameters are required. For three-by-three palettes, all parameters are required.
Apply Bivariate Color to ggplot Object
Description
Applies the selected palette as the color aesthetic when geom_sf
is used and the bi_class
variable is given as the color
in the aesthetic
mapping.
Usage
bi_scale_color(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)
Arguments
pal |
A palette name or a vector containing a custom palette. See
the help file for |
dim |
The dimensions of the palette. To use the built-in palettes,
this value must be either If you are using a custom palette, this value may be larger (though these
maps can be very hard to interpret). See the 'Advanced Options' vignette
for details on the relationship between |
flip_axes |
A logical scalar; if |
rotate_pal |
A logical scalar; if |
... |
Arguments to pass to |
Value
A ggplot
object with the given bivariate palette applied to the data.
See Also
bi_pal
Examples
# load dependencies
library(ggplot2)
# add breaks, 3x3
data <- bi_class(stl_race_income, x = pctWhite, y = medInc, style = "quantile", dim = 3)
# create map
plot <- ggplot() +
geom_sf(data = data, aes(color = bi_class), size = 2, show.legend = FALSE) +
bi_scale_color(pal = "GrPink", dim = 3)
Apply Bivariate Fill to ggplot Object
Description
Applies the selected palette as the fill aesthetic when geom_sf
is used and the bi_class
variable is given as the fill
in the aesthetic
mapping.
Usage
bi_scale_fill(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)
Arguments
pal |
A palette name or a vector containing a custom palette. See
the help file for |
dim |
The dimensions of the palette, either |
flip_axes |
A logical scalar; if |
rotate_pal |
A logical scalar; if |
... |
Arguments to pass to |
Value
A ggplot
object with the given bivariate palette applied to the data.
See Also
bi_pal
Examples
# load dependencies
library(ggplot2)
# add breaks, 3x3
data <- bi_class(stl_race_income, x = pctWhite, y = medInc, style = "quantile", dim = 3)
# create map
plot <- ggplot() +
geom_sf(data = data, aes(fill = bi_class), color = "white", size = 0.1, show.legend = FALSE) +
bi_scale_fill(pal = "GrPink", dim = 3)
Basic Theme for Bivariate Mapping
Description
A theme for creating a simple, clean bivariate map using
ggplot2
.
Usage
bi_theme(
base_family = "sans",
base_size = 24,
bg_color = "#ffffff",
font_color = "#000000",
...
)
Arguments
base_family |
A character string representing the font family to be used in the map. |
base_size |
A number representing the base size used in the map. |
bg_color |
A character string containing the hex value for the desired color of the map's background. |
font_color |
A character string containing the hex value for the desired color of the map's text. |
... |
Arguments to pass on to |
Examples
# load suggested dependencies
library(ggplot2)
library(sf)
# add breaks, 3x3
data <- bi_class(stl_race_income, x = pctWhite, y = medInc, style = "quantile", dim = 3)
# create map
ggplot() +
geom_sf(data = data, aes(fill = bi_class), color = "white", size = 0.1, show.legend = FALSE) +
bi_scale_fill(pal = "GrPink", dim = 3) +
bi_theme()
Race and Median Income in St. Louis by Census Tract, 2017
Description
A simple features data set containing the geometry and associated attributes for the 2013-2017 American Community Survey estimates for median household income and the percentage of white residents in St. Louis. This version of the sample data are stored as polygon data.
Usage
data(stl_race_income)
Format
A data frame with 106 rows and 4 variables:
- GEOID
full GEOID string
- pctWhite
Percent of white residents per tract
- medInc
Median household income of tract
- geometry
simple features geometry
Source
tidycensus
package
Examples
str(stl_race_income)
head(stl_race_income)
summary(stl_race_income$medInc)
Race and Median Income in St. Louis by Census Tract, 2017
Description
A simple features data set containing the geometry and associated attributes for the 2013-2017 American Community Survey estimates for median household income and the percentage of white residents in St. Louis. This version of the sample data are stored as point data.
Usage
data(stl_race_income_point)
Format
A data frame with 106 rows and 4 variables:
- GEOID
full GEOID string
- pctWhite
Percent of white residents per tract
- medInc
Median household income of tract
- geometry
simple features geometry
Source
tidycensus
package
Examples
str(stl_race_income_point)
head(stl_race_income_point)
summary(stl_race_income_point$medInc)