,
Timo Grossenbacher [aut],
Angelo Zehr [aut],
Joshua Stevens [ctb]| Title: | Tools and Palettes for Bivariate Thematic Mapping |
|---|---|
| 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. |
| Authors: | Christopher Prener [aut, cre] ,
Timo Grossenbacher [aut],
Angelo Zehr [aut],
Joshua Stevens [ctb] |
| Maintainer: | Christopher Prener <[email protected]> |
| License: | GPL-3 |
| Version: | 1.1.0.9000 |
| Built: | 2025-01-17 06:09:31 UTC |
| Source: | https://github.com/chris-prener/biscale |
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.
bi_class(.data, x, y, style, dim = 3, keep_factors = FALSE, dig_lab = 3)bi_class(.data, x, y, style, dim = 3, keep_factors = FALSE, dig_lab = 3)
.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 |
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.
# 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)# 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)
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.
bi_class_breaks(.data, x, y, style, dim = 3, clean_levels = TRUE, dig_lab = 3, si_levels = FALSE, split = FALSE)bi_class_breaks(.data, x, y, style, dim = 3, clean_levels = TRUE, dig_lab = 3, si_levels = FALSE, split = FALSE)
.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 |
si_levels |
A logical scalar or vector of length 2 that where |
split |
A logical scalar; if |
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.
# 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) # show SI prefix bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc, dim = 4, dig_lab = c(4, 5), si_levels = c(y = TRUE), 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)# 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) # show SI prefix bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc, dim = 4, dig_lab = c(4, 5), si_levels = c(y = TRUE), 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)
Creates a ggplot object containing a legend that is
specific to bivariate mapping.
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, base_family = "sans")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, base_family = "sans")
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 |
base_family |
A character string; by default, it is set to |
A ggplot object with a bivariate legend.
# 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 # sample 3x3 legend with Chinese characters ## set language preference showtext::showtext_auto() ## create legend legend <- bi_legend(pal = "GrPink", dim = 3, xlab = "白人 ", ylab = "收入 ", size = 16, base_family = "") ## print legend legend# 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 # sample 3x3 legend with Chinese characters ## set language preference showtext::showtext_auto() ## create legend legend <- bi_legend(pal = "GrPink", dim = 3, xlab = "白人 ", ylab = "收入 ", size = 16, base_family = "") ## print legend legend
Prints either a visual preview of each palette or the associated hex values.
bi_pal(pal, dim = 3, preview = TRUE, flip_axes = FALSE, rotate_pal = FALSE)bi_pal(pal, dim = 3, preview = TRUE, flip_axes = FALSE, rotate_pal = FALSE)
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 |
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.
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.
# 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)# 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)
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.
bi_scale_color(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)bi_scale_color(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)
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 |
A ggplot object with the given bivariate palette applied to the data.
bi_pal
# 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)# 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)
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.
bi_scale_fill(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)bi_scale_fill(pal, dim = 3, flip_axes = FALSE, rotate_pal = FALSE, ...)
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 |
A ggplot object with the given bivariate palette applied to the data.
bi_pal
# 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)# 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)
A theme for creating a simple, clean bivariate map using
ggplot2.
bi_theme( base_family = "sans", base_size = 24, bg_color = "#ffffff", font_color = "#000000", ... )bi_theme( base_family = "sans", base_size = 24, bg_color = "#ffffff", font_color = "#000000", ... )
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 |
# 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()# 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()
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.
data(stl_race_income)data(stl_race_income)
A data frame with 106 rows and 4 variables:
full GEOID string
Percent of white residents per tract
Median household income of tract
simple features geometry
tidycensus package
str(stl_race_income) head(stl_race_income) summary(stl_race_income$medInc)str(stl_race_income) head(stl_race_income) summary(stl_race_income$medInc)
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.
data(stl_race_income_point)data(stl_race_income_point)
A data frame with 106 rows and 4 variables:
full GEOID string
Percent of white residents per tract
Median household income of tract
simple features geometry
tidycensus package
str(stl_race_income_point) head(stl_race_income_point) summary(stl_race_income_point$medInc)str(stl_race_income_point) head(stl_race_income_point) summary(stl_race_income_point$medInc)