| Title: | Color Palettes and 'ggplot2' Extensions for Data Visualization |
|---|---|
| Description: | Provides 'ggplot2' scale functions and a custom theme derived from the 'Benvi' visual identity of QuintoAndar Group. Offers qualitative, sequential, and diverging color palettes with both discrete and continuous scale variants. |
| Authors: | Vinicius Oike [aut, cre, cph] (ORCID: <https://orcid.org/0009-0005-8015-9189>), The Poppins Project Authors [cph] (Poppins font (SIL Open Font License 1.1), https://github.com/itfoundry/Poppins) |
| Maintainer: | Vinicius Oike <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.2.2 |
| Built: | 2026-10-21 06:26:29 UTC |
| Source: | https://github.com/viniciusoike/benviplot |
Returns the hex codes of a named Benvi palette. Use show_palettes() to see
the available palettes. The interface follows the
ghibli package.
benvi_palette( pal_name = "qual_2", n, direction = 1, type = c("discrete", "continuous") )benvi_palette( pal_name = "qual_2", n, direction = 1, type = c("discrete", "continuous") )
pal_name |
Name of the palette. Defaults to |
n |
Number of colors to return. Defaults to the number of colors in the selected palette. |
direction |
Either |
type |
Either |
A palette object containing hexadecimal color values.
# Use default palette benvi_palette() # Specify palette name benvi_palette("greens") benvi_palette("greens", n = 20, type = "continuous") benvi_palette("greens", n = 2, type = "discrete")# Use default palette benvi_palette() # Specify palette name benvi_palette("greens") benvi_palette("greens", n = 20, type = "continuous") benvi_palette("greens", n = 2, type = "discrete")
Reports whether Poppins, systemfonts, and the ragg graphics device are
available.
font_status()font_status()
A list with poppins_available and ragg_available, invisibly.
font_status()font_status()
Formats numbers with a period as the thousands separator and a comma as the decimal separator. The result is suitable for labels in tables and plots.
format_num_br(x, digits = 1, percent = FALSE)format_num_br(x, digits = 1, percent = FALSE)
x |
A numeric vector. |
digits |
Number of decimal places to include. Can be negative to round to tens, hundreds, etc. |
percent |
Whether to append a percent sign. |
Brazilian number formatting uses . as the thousands separator and , as
the decimal separator.
For example, 1234567.89 becomes "1.234.567,9" when digits = 1.
A character vector containing the formatted numbers.
# Basic formatting x <- 1235134.123 format_num_br(x) # Different decimal places format_num_br(x, digits = 3) format_num_br(x, digits = 0) # With percentage format_num_br(12.5, digits = 1, percent = TRUE) # Negative digits round to tens, hundreds, etc. format_num_br(1234567, digits = -3) # Works with vectors format_num_br(c(100, 1000, 10000))# Basic formatting x <- 1235134.123 format_num_br(x) # Different decimal places format_num_br(x, digits = 3) format_num_br(x, digits = 0) # With percentage format_num_br(12.5, digits = 1, percent = TRUE) # Negative digits round to tens, hundreds, etc. format_num_br(1234567, digits = -3) # Works with vectors format_num_br(c(100, 1000, 10000))
Map continuous values to colors interpolated from a Benvi palette.
scale_colour_benvi_c(pal_name = "benvi_blue", direction = 1, ...) scale_color_benvi_c(pal_name = "benvi_blue", direction = 1, ...) scale_fill_benvi_c(pal_name = "benvi_blue", direction = 1, ...)scale_colour_benvi_c(pal_name = "benvi_blue", direction = 1, ...) scale_color_benvi_c(pal_name = "benvi_blue", direction = 1, ...) scale_fill_benvi_c(pal_name = "benvi_blue", direction = 1, ...)
pal_name |
Name of the palette. Defaults to |
direction |
Either |
... |
Additional arguments passed to
|
A continuous ggplot2 scale that can be added to a ggplot object.
library(ggplot2) ggplot(mtcars, aes(x = wt, y = mpg, color = hp)) + geom_point() + scale_color_benvi_c("benvi_blue")library(ggplot2) ggplot(mtcars, aes(x = wt, y = mpg, color = hp)) + geom_point() + scale_color_benvi_c("benvi_blue")
A wrapper around ggplot2::ggsave() that uses the ragg graphics device for
PNG output. Registered fonts such as the bundled Poppins are only visible to
systemfonts-aware devices, so ragg is what lets theme_benvi() render its
font in saved files.
If ragg is not installed, the function uses the default graphics device.
ggsave_benvi( filename, plot = ggplot2::last_plot(), device = NULL, width = 7, height = 5, units = "in", dpi = 300, ... )ggsave_benvi( filename, plot = ggplot2::last_plot(), device = NULL, width = 7, height = 5, units = "in", dpi = 300, ... )
filename |
File name to create on disk. The file extension determines
the graphics device (for example, |
plot |
Plot to save. Defaults to the last plot displayed. |
device |
Graphics device. Uses |
width, height
|
Plot size. Defaults to 7 by 5 inches. |
units |
Units for width and height. Choose |
dpi |
DPI to use for raster graphics. Defaults to 300. |
... |
Additional arguments passed to |
filename, invisibly.
p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() ggsave_benvi(tempfile(fileext = ".png"), plot = p)p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() ggsave_benvi(tempfile(fileext = ".png"), plot = p)
Historical rental price index data from QuintoAndar. This is the legacy IQA
index, which has been superseded by the IQAIW (see iqaiw).
iqaiqa
A data frame with 96 observations and 6 variables.
Date of the observation (first day of month)
Name of the municipality (city)
Rental price index, normalized to 100 at first observation
Monthly percent variation of the index (decimal form)
12-month accumulated variation of the index (decimal form)
Estimated rental price per square meter (R$/m²)
QuintoAndar
# To visualize the dataset head(iqa) str(iqa) # Plot index over time for all cities library(ggplot2) ggplot(iqa, aes(x = date, y = index, color = name_muni)) + geom_line() + scale_color_benvi_d(pal_name = "qual_9", name = "City") + labs( title = "IQA: Rental Price Index", x = "Date", y = "Index (base = 100)" ) + theme_benvi(base_family = "sans")# To visualize the dataset head(iqa) str(iqa) # Plot index over time for all cities library(ggplot2) ggplot(iqa, aes(x = date, y = index, color = name_muni)) + geom_line() + scale_color_benvi_d(pal_name = "qual_9", name = "City") + labs( title = "IQA: Rental Price Index", x = "Date", y = "Index (base = 100)" ) + theme_benvi(base_family = "sans")
The IQAIW (Índice QuintoAndar ImovelWeb) is a rental index for major Brazilian cities. The index is based on both new rental contracts (managed by QuintoAndar) and online listings published by QuintoAndar and ImovelWeb.
iqaiwiqaiw
A data frame with 1,660 observations across six cities and multiple periods.
Date of the observation (first day of month)
Name of the municipality. Values include Belo Horizonte, Brasília, Curitiba, Porto Alegre, Rio de Janeiro, and São Paulo
Number of rooms in the property, or "Total" for city-level aggregate
Rental price index, normalized to 100 at first observation per city
Monthly percent variation of the index (decimal form)
12-month accumulated variation of the index (decimal form)
Estimated rental price per square meter (R$/m²)
The IQAIW was developed in 2023 and replaced the former IQA index. Given the change in methodology and data sources, the IQAIW is not directly comparable to the IQA index.
The index uses double imputation with a hedonic model. A generalized additive model (GAM) controls for property characteristics and location. The sample combines new rental contracts with online listings, so the index does not measure either source in isolation.
# To visualize the dataset head(iqaiw) str(iqaiw) # Plot index over time for all cities library(ggplot2) iqaiw_rooms <- subset(iqaiw, rooms != "Total" & !is.na(acum12m)) ggplot(iqaiw_rooms, aes(x = date, y = acum12m, color = rooms)) + geom_line(lwd = 0.5) + geom_hline(yintercept = 0) + scale_color_benvi_d(pal_name = "qual_6", name = "Rooms") + facet_wrap(vars(name_muni), ncol = 3, scales = "free") + labs( title = "IQAIW: 12-month rental price change", x = "Date", y = "12-month change (decimal)" ) + theme_benvi(base_family = "sans")# To visualize the dataset head(iqaiw) str(iqaiw) # Plot index over time for all cities library(ggplot2) iqaiw_rooms <- subset(iqaiw, rooms != "Total" & !is.na(acum12m)) ggplot(iqaiw_rooms, aes(x = date, y = acum12m, color = rooms)) + geom_line(lwd = 0.5) + geom_hline(yintercept = 0) + scale_color_benvi_d(pal_name = "qual_6", name = "Rooms") + facet_wrap(vars(name_muni), ncol = 3, scales = "free") + labs( title = "IQAIW: 12-month rental price change", x = "Date", y = "12-month change (decimal)" ) + theme_benvi(base_family = "sans")
Plot an area chart
plot_area( data, x, y, fill = NULL, zero = TRUE, order = TRUE, pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), position = "stack" )plot_area( data, x, y, fill = NULL, zero = TRUE, order = TRUE, pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), position = "stack" )
data |
A data frame. |
x |
< |
y |
< |
fill |
Fill color for the area. Either a color string (e.g., |
zero |
Whether to draw a horizontal line at |
order |
Whether to order stacked areas by size. The default, |
pal_name |
Name of the palette. |
scale_name |
Fill legend title. |
scale_label |
Fill legend labels. |
position |
Position adjustment passed to |
A ggplot object.
# Simple area chart sao_paulo <- subset(iqa, name_muni == "São Paulo") plot_area(data = sao_paulo, x = date, y = index) # Stacked area chart with fill mapping total <- subset(iqaiw, rooms == "Total") plot_area(data = total, x = date, y = index, fill = name_muni)# Simple area chart sao_paulo <- subset(iqa, name_muni == "São Paulo") plot_area(data = sao_paulo, x = date, y = index) # Stacked area chart with fill mapping total <- subset(iqaiw, rooms == "Total") plot_area(data = total, x = date, y = index, fill = name_muni)
Plot a column chart
plot_column( data, x, y, fill = NULL, zero = TRUE, text = FALSE, text_inside = FALSE, text_place = NULL, text_padding = NULL, pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), digits = 0, percent = FALSE, text_color = "gray20", text_family = getOption("theme_benvi.font_family", "sans"), text_size = 3, position_col = "stack", position_text = position_col, ... )plot_column( data, x, y, fill = NULL, zero = TRUE, text = FALSE, text_inside = FALSE, text_place = NULL, text_padding = NULL, pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), digits = 0, percent = FALSE, text_color = "gray20", text_family = getOption("theme_benvi.font_family", "sans"), text_size = 3, position_col = "stack", position_text = position_col, ... )
data |
A data frame. |
x |
< |
y |
< |
fill |
Fill color for the columns. Either a color string (e.g.,
|
zero |
Whether to draw a horizontal line at |
text |
Whether to add value labels to the columns. |
text_inside |
Whether to place labels inside the columns with
|
text_place |
Placement of labels inside the columns. Choose |
text_padding |
Padding around inside labels, supplied as a
|
pal_name |
Name of the palette. |
scale_name |
Fill legend title. |
scale_label |
Fill legend labels. |
digits |
Number of digits to show in text labels. |
percent |
Whether to append a percent sign to text labels. |
text_color |
Color of the text label. Default is |
text_family |
Font family for the text label. Defaults to
|
text_size |
Size of the text label. Default is |
position_col |
Position adjustment passed to |
position_text |
Position adjustment passed to |
... |
Additional arguments passed to |
A ggplot object.
# Column chart by city at the latest date latest <- subset(iqa, date == max(iqa$date)) plot_column(data = latest, x = name_muni, y = index) # With text labels above bars plot_column(data = latest, x = name_muni, y = index, text = TRUE) # With text labels inside bars latest <- subset(iqa, date == max(iqa$date)) plot_column(data = latest, x = name_muni, y = index, text = TRUE, text_inside = TRUE)# Column chart by city at the latest date latest <- subset(iqa, date == max(iqa$date)) plot_column(data = latest, x = name_muni, y = index) # With text labels above bars plot_column(data = latest, x = name_muni, y = index, text = TRUE) # With text labels inside bars latest <- subset(iqa, date == max(iqa$date)) plot_column(data = latest, x = name_muni, y = index, text = TRUE, text_inside = TRUE)
Plot a histogram chart
plot_histogram( data, x, color = "#FFFFFF", fill = NULL, pal_name = "qual_benvi", scale_name = "", zero = TRUE, bins = NULL, method = "fd", density = FALSE, facet = NULL, ... )plot_histogram( data, x, color = "#FFFFFF", fill = NULL, pal_name = "qual_benvi", scale_name = "", zero = TRUE, bins = NULL, method = "fd", density = FALSE, facet = NULL, ... )
data |
A data frame. |
x |
< |
color |
Color of the column border. Defaults to |
fill |
Fill color for the columns. Either a color string (e.g., |
pal_name |
Name of the palette used when |
scale_name |
Fill legend title. |
zero |
Whether to draw a horizontal line at |
bins |
Number of bins. When specified, overrides |
method |
Binning method. Choose |
density |
Whether to map density to the y-axis. |
facet |
< |
... |
Additional arguments passed to |
The method parameter controls how the function computes the bin width.
"fd" or "FD"
Freedman-Diaconis rule. Uses the interquartile
range: .
"Scott"Scott's rule. The formula uses the standard deviation,
.
"Sturges"Sturges' formula. Uses
bins.
"Rice"Rice rule. Uses
bins.
"sqrt"Square-root rule. Uses
bins.
A ggplot object.
# Default parameters use Freedman-Diaconis plot_histogram(data = mtcars, x = mpg) # Use bins to manually choose number of bins plot_histogram(data = mtcars, x = mpg, bins = 10) # Example of alternative methods: square root and Rice plot_histogram(data = mtcars, x = mpg, method = "sqrt") plot_histogram(data = mtcars, x = mpg, method = "Rice") # Facet by rooms category spo <- subset(iqaiw, name_muni == "São Paulo" & rooms != "Total") plot_histogram(data = spo, x = index, facet = rooms)# Default parameters use Freedman-Diaconis plot_histogram(data = mtcars, x = mpg) # Use bins to manually choose number of bins plot_histogram(data = mtcars, x = mpg, bins = 10) # Example of alternative methods: square root and Rice plot_histogram(data = mtcars, x = mpg, method = "sqrt") plot_histogram(data = mtcars, x = mpg, method = "Rice") # Facet by rooms category spo <- subset(iqaiw, name_muni == "São Paulo" & rooms != "Total") plot_histogram(data = spo, x = index, facet = rooms)
Plot a line chart
plot_line( data, x, y, color = NULL, zero = TRUE, point = FALSE, pal_name, scale_name = "", scale_label = ggplot2::waiver(), ... )plot_line( data, x, y, color = NULL, zero = TRUE, point = FALSE, pal_name, scale_name = "", scale_label = ggplot2::waiver(), ... )
data |
A data frame. |
x |
< |
y |
< |
color |
Color of the line. Either a color string (e.g., |
zero |
Whether to draw a horizontal line at |
point |
Whether to draw points over the line. |
pal_name |
Name of the color palette. |
scale_name |
Color legend title. |
scale_label |
Color legend labels. |
... |
Additional arguments passed to |
A ggplot object.
# Single series sao_paulo <- subset(iqa, name_muni == "S\u00e3o Paulo") plot_line(data = sao_paulo, x = date, y = index) # Multiple series with color mapping total <- subset(iqaiw, rooms == "Total") plot_line(data = total, x = date, y = index, color = name_muni)# Single series sao_paulo <- subset(iqa, name_muni == "S\u00e3o Paulo") plot_line(data = sao_paulo, x = date, y = index) # Multiple series with color mapping total <- subset(iqaiw, rooms == "Total") plot_line(data = total, x = date, y = index, color = name_muni)
Plot a scatter chart
plot_scatter( data, x, y, color = NULL, fit = FALSE, fit_variable = FALSE, fit_method = "auto", fit_formula = NULL, fit_color = NULL, fit_ci = FALSE, zero = "none", pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), ... )plot_scatter( data, x, y, color = NULL, fit = FALSE, fit_variable = FALSE, fit_method = "auto", fit_formula = NULL, fit_color = NULL, fit_ci = FALSE, zero = "none", pal_name = "qual_benvi", scale_name = "", scale_label = ggplot2::waiver(), ... )
data |
A data frame. |
x |
< |
y |
< |
color |
Color of the points. Either a color string (e.g., |
fit |
Whether to draw a fitted line over the points. |
fit_variable |
Whether to fit separate lines for groups mapped to
|
fit_method |
Smoothing method passed to |
fit_formula |
Formula passed to |
fit_color |
Color of the fitted regression line. Only applied when
|
fit_ci |
Whether to draw the confidence interval around fitted lines.
Defaults to |
zero |
Axis lines to draw. Choose |
pal_name |
Name of the palette. |
scale_name |
Fill legend title. |
scale_label |
Fill legend labels. |
... |
Additional arguments passed to |
A ggplot object.
plot_scatter(data = mtcars, x = wt, y = mpg) # With regression line plot_scatter(data = mtcars, x = wt, y = mpg, fit = TRUE)plot_scatter(data = mtcars, x = wt, y = mpg) # With regression line plot_scatter(data = mtcars, x = wt, y = mpg, fit = TRUE)
Contract prices per square meter at the zone level for major Brazilian cities.
sales_reportsales_report
A data frame with 272 observations across multiple cities and zones.
Date of the observation (first day of month)
Name of the municipality. Values include Belo Horizonte, Rio de Janeiro, and São Paulo
Name of the zone within the city
Median contract price per square meter (R$/m²)
QuintoAndar (Sales Report 2020-Q1/2023-Q3). https://publicfiles.data.quintoandar.com.br/sale_report/RelatorioCV_4T_2022.pdf
# Compare contract prices across zones library(ggplot2) bhe_sales <- subset(sales_report, name_muni == "Belo Horizonte" & date == max(date)) bhe_sales$name_zone <- factor( bhe_sales$name_zone, levels = bhe_sales$name_zone[order(bhe_sales$price_m2)] ) ggplot(bhe_sales, aes(x = price_m2, y = name_zone)) + geom_col(fill = benvi_palette("benvi_blue")[3]) + labs(x = "Median price per m² (R$)", y = NULL) + theme_benvi(base_family = "sans")# Compare contract prices across zones library(ggplot2) bhe_sales <- subset(sales_report, name_muni == "Belo Horizonte" & date == max(date)) bhe_sales$name_zone <- factor( bhe_sales$name_zone, levels = bhe_sales$name_zone[order(bhe_sales$price_m2)] ) ggplot(bhe_sales, aes(x = price_m2, y = name_zone)) + geom_col(fill = benvi_palette("benvi_blue")[3]) + labs(x = "Median price per m² (R$)", y = NULL) + theme_benvi(base_family = "sans")
Map discrete values to colors from a Benvi palette.
scale_colour_benvi_d(pal_name = "qual_benvi", direction = 1, ...) scale_color_benvi_d(pal_name = "qual_benvi", direction = 1, ...) scale_fill_benvi_d(pal_name = "qual_benvi", direction = 1, ...)scale_colour_benvi_d(pal_name = "qual_benvi", direction = 1, ...) scale_color_benvi_d(pal_name = "qual_benvi", direction = 1, ...) scale_fill_benvi_d(pal_name = "qual_benvi", direction = 1, ...)
pal_name |
Name of the palette. Defaults to |
direction |
Either |
... |
Additional arguments passed to |
A discrete ggplot2 scale that can be added to a ggplot object.
library(ggplot2) # Discrete color scale with rental index data iqaiw_total <- subset(iqaiw, rooms == "Total") ggplot(iqaiw_total, aes(x = date, y = index, colour = name_muni)) + geom_line() + scale_color_benvi_d("qual_benvi")library(ggplot2) # Discrete color scale with rental index data iqaiw_total <- subset(iqaiw, rooms == "Total") ggplot(iqaiw_total, aes(x = date, y = index, colour = name_muni)) + geom_line() + scale_color_benvi_d("qual_benvi")
Draws the available Benvi palettes in a grid. The layout follows
RColorBrewer::display.brewer.all().
show_palettes(type = "all", n = NULL)show_palettes(type = "all", n = NULL)
type |
Palette type to display. Choose |
n |
Number of colors to display from each palette. If |
NULL, invisibly. This function is called for its plotting side
effect.
# Display all palettes show_palettes() # Display only theme palettes show_palettes("theme") # Display sequential palettes show_palettes("sequential")# Display all palettes show_palettes() # Display only theme palettes show_palettes("theme") # Display sequential palettes show_palettes("sequential")
A ggplot2 base theme for Benvi-styled plots.
The Poppins font is bundled with the package and registered automatically on
load when systemfonts is installed. When both systemfonts and ragg are
available, the theme uses Poppins by default. Otherwise it falls back to the
system's default sans-serif font.
Registered fonts only work with systemfonts-aware devices such as
ragg::agg_png(). Base R devices (PDF and PostScript) cannot render them. If you
see font warnings when saving to PDF, pass base_family = "sans" or set
options(theme_benvi.font_family = "sans"). See font_status() to check
your setup.
theme_benvi( base_family = getOption("theme_benvi.font_family", default_font_family()), base_size = 10, background = FALSE )theme_benvi( base_family = getOption("theme_benvi.font_family", default_font_family()), base_size = 10, background = FALSE )
base_family |
Argument passed to |
base_size |
Argument passed to |
background |
Whether to use an off-white background. |
A ggplot2 theme object.
library(ggplot2) series <- subset(iqaiw, name_muni == "São Paulo" & rooms == "Total") # Base theme (using "sans" for portability) ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "sans") # Optional offwhite (creme) background ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "sans", background = TRUE) ## Not run: # Use Poppins with a ragg device (requires systemfonts and ragg) ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "Poppins") ## End(Not run)library(ggplot2) series <- subset(iqaiw, name_muni == "São Paulo" & rooms == "Total") # Base theme (using "sans" for portability) ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "sans") # Optional offwhite (creme) background ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "sans", background = TRUE) ## Not run: # Use Poppins with a ragg device (requires systemfonts and ragg) ggplot(series, aes(date, index)) + geom_line(color = benvi_palette("benvi_blue")[1], lwd = 1) + labs(x = NULL, y = "Index (base = 100)", title = "IQAIW") + theme_benvi(base_family = "Poppins") ## End(Not run)