Getting Started with benviplot

Installation

# Install remotes if needed
install.packages("remotes")

remotes::install_github("viniciusoike/benviplot")

Optional font setup

benviplot bundles the Poppins font family. When both systemfonts and ragg are available, the package registers Poppins and theme_benvi() uses it by default. Otherwise, the theme uses the system sans-serif font.

Install ragg to render Poppins in PNG files. Base PDF and PostScript devices cannot use fonts registered through systemfonts; use base_family = "sans" with those devices.

install.packages("ragg")

Check whether Poppins and ragg are available with font_status().

font_status()

Browsing palettes

show_palettes() displays the available palettes. Calling it without arguments shows every palette; pass a type name to narrow the output.

show_palettes()

Filter the display with "theme", "sequential", "qualitative", "diverging", "city", or "brand".

show_palettes("sequential")

Accessing palette colors

benvi_palette() returns a palette object backed by hexadecimal color values. Printing the object draws color swatches on the active graphics device.

# Preview a palette
benvi_palette("qual_2")

To pass the colors to another package, coerce the result to a plain character vector.

# Get hex codes as a plain character vector
as.character(benvi_palette("benvi_blue"))
#>  [1] "#021841" "#192C50" "#2F405F" "#46546E" "#5D687D" "#737C8C" "#8A919C"
#>  [8] "#A0A5AB" "#B7B9BA" "#CECDC9"

Discrete palettes contain between 4 and 9 fixed colors. Set type = "continuous" to interpolate more colors along the palette gradient.

benvi_palette("seq_greens", n = 20, type = "continuous")

Discrete scales

Discrete scales map categorical variables to fixed colors. Qualitative palettes usually work best for this purpose, but pal_name accepts any package palette.

iqaiw_total <- subset(iqaiw, rooms == "Total")

ggplot(iqaiw_total, aes(x = date, y = index, color = name_muni)) +
  geom_line(linewidth = 0.7) +
  geom_hline(yintercept = 100) +
  scale_color_benvi_d("rio_qual", name = NULL) +
  labs(
    title = "IQAIW Rental Index by City",
    x = NULL,
    y = "Index (base = 100)"
  ) +
  theme_benvi()

Continuous scales

Continuous scales interpolate colors from any package palette. Sequential palettes usually work best for ordered numeric values. Use direction = -1 to reverse the palette.

iqaiw_total <- subset(iqaiw_total, !is.na(acum12m))

ggplot(iqaiw_total, aes(x = date, y = name_muni, fill = acum12m * 100)) +
  geom_tile(height = 0.6, color = "#ffffff") +
  scale_fill_benvi_c(
    pal_name = "benvi_blue",
    name = "YoY Change (%)",
    direction = -1
  ) +
  scale_x_date(
    date_breaks = "1 year",
    date_labels = "%Y",
    expand = expansion(0)
  ) +
  labs(x = NULL, y = NULL) +
  theme_benvi() +
  theme(
    legend.title = element_text(hjust = 0.5, vjust = 0.75),
    axis.text = element_text(size = 12),
    panel.grid = element_blank()
  )

Line chart

plot_line() draws a single-series line chart. Pass color to map a grouping variable and draw multiple lines with a legend.

spo_index <- subset(iqaiw, name_muni == "São Paulo" & rooms == "Total")
plot_line(spo_index, x = date, y = index)

Bar chart

plot_column() creates a vertical bar chart. Setting text = TRUE adds value labels above each bar. Set text_inside = TRUE to place the labels inside the bars; this option requires the ggfittext package.

latest_sales <- subset(
  sales_report,
  name_muni == "Belo Horizonte" & date == max(date)
)

plot_column(latest_sales, x = name_zone, y = price_m2, text = TRUE)

Scatter plot

plot_scatter() maps x and y to a scatter plot. Pass a variable to color to apply a Benvi palette to the points. Set fit = TRUE to add a fitted line.

plot_scatter(
  mtcars,
  x = wt,
  y = mpg,
  color = as.factor(cyl),
  pal_name = "qual_5",
  scale_name = "Cylinders",
  fit = TRUE
)

Area chart

plot_area() draws a single area or maps a grouping variable to fill to draw stacked areas.

room_index <- subset(
  iqaiw,
  name_muni == "São Paulo" & rooms %in% c("1", "2", "3")
)

plot_area(room_index, x = date, y = index, fill = rooms)

Histogram

plot_histogram() selects the bin width with the Freedman–Diaconis rule by default. Set bins to choose the number of bins directly.

plot_histogram(mtcars, x = mpg)

Adding layers

Because the helpers return ggplot objects, you can add layers, scales, and theme adjustments with the usual ggplot2 syntax.

plot_line(spo_index, x = date, y = index) +
  geom_smooth(se = FALSE, color = benvi_palette("oranges")[3]) +
  labs(
    title = "Rental Price Index in São Paulo",
    subtitle = "Smoothed trend",
    x = NULL,
    y = "Index (base = 100)",
    caption = "Source: IQAIW"
  )