Package {ggpop}

Type:	Package
Title:	Icon-Based Population Charts and Plots for 'ggplot2'
Version:	1.8.0
Date:	2026-08-23
Description:	Create engaging population charts and point plots in R. 'ggpop' allows users to represent population data and points proportionally using customizable icons, facilitating the creation of circular representative population charts as well as any point-plots.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, cowplot, ggforce, gganimate, ggrepel, ggtext, scales, reactable, patchwork
Config/Needs/website:	sf, geofacet, ggtext, quarto, kcuilla/reactablefmtr
Config/testthat/edition:	3
Depends:	R (≥ 4.0.5)
Imports:	ggplot2, dplyr, ggimage, magick, rlang, tidyr, purrr, fontawesome, rsvg, cli, tibble, grid, grDevices, stats, tools, utils
VignetteBuilder:	knitr
ByteCompile:	true
BugReports:	https://github.com/jurjoroa/ggpop/issues
URL:	https://jurjoroa.github.io/ggpop/
NeedsCompilation:	no
Packaged:	2026-08-23 19:15:33 UTC; jorgeroa
Author:	Jorge A. Roa-Contreras [aut, cre], Ralitza Soultanova [aut], Fernando Alarid-Escudero [aut], Carlos Pineda-Antunez [aut]
Maintainer:	Jorge A. Roa-Contreras <jorgeroa@stanford.edu>
Repository:	CRAN
Date/Publication:	2026-08-23 20:10:11 UTC

ggpop: Icon-Based Population Charts for R

Description

ggpop is a ggplot2 extension for creating icon-based population charts and pictogram plots. Use geom_pop() and geom_icon_point() to visualize proportion and population data with 2,000+ Font Awesome icons.

Main functions

• geom_pop() – proportional icon grids

• geom_icon_point() – icon scatter plots

• process_data() – prepare count data for plotting

• fa_icons() – search Font Awesome icon names

• theme_pop(), theme_pop_dark(), theme_pop_minimal() – built-in themes

process_data()

Converts count data to one row per icon. group_var and sum_var are unquoted; high_group_var takes a character string for faceted charts.

df_plot <- process_data(
  data        = data.frame(sex = c("Female", "Male"), n = c(55, 45)),
  group_var   = sex,
  sum_var     = n,
  sample_size = 20
)

geom_pop()

Draws icon grids. Add an icon column, map icon and color in aes(). Do not map x or y.

ggplot() +
  geom_pop(data = df_plot, aes(icon = icon, color = type), size = 2) +
  scale_color_manual(values = c(Female = "#C0392B", Male = "#2980B9")) +
  theme_pop()

geom_icon_point()

Drop-in replacement for geom_point() using Font Awesome icons.

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) +
  geom_icon_point(icon = "seedling", size = 1)

fa_icons()

Search the bundled Font Awesome icon list by keyword.

fa_icons(query = "person")

Themes

Three built-in themes optimized for icon charts: theme_pop(), theme_pop_dark(), theme_pop_minimal().

Author(s)

Maintainer: Jorge A. Roa-Contreras jorgeroa@stanford.edu (ORCID)

Authors:

• Ralitza Soultanova Ralitza.soultanova@gmail.com (ORCID)

• Fernando Alarid-Escudero falarid@stanford.edu (ORCID)

• Carlos Pineda-Antunez cpinedaa@uw.edu (ORCID)

See Also

Useful links:

• https://jurjoroa.github.io/ggpop/

• Report bugs at https://github.com/jurjoroa/ggpop/issues

Examples

library(ggplot2)
library(dplyr)

## -------------------------------------------------------
## geom_pop(): population icon grid
## -------------------------------------------------------
df_plot <- process_data(
  data        = data.frame(sex = c("Female", "Male"), n = c(55, 45)),
  group_var   = sex,
  sum_var     = n,
  sample_size = 20
) %>%
  mutate(icon = ifelse(type == "Female", "person-dress", "person"))

ggplot() +
  geom_pop(data = df_plot, aes(icon = icon, color = type), size = 2) +
  scale_color_manual(values = c(Female = "#C0392B", Male = "#2980B9")) +
  theme_pop() +
  labs(title = "Population by sex", color = NULL)

## -------------------------------------------------------
## geom_icon_point(): icon scatter plot
## -------------------------------------------------------
ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) +
  geom_icon_point(icon = "seedling", size = 1) +
  scale_color_manual(values = c(
    setosa     = "#43A047",
    versicolor = "#1E88E5",
    virginica  = "#E53935"
  )) +
  labs(title = "Iris dataset", x = "Sepal Length", y = "Petal Length")

Search and list Font Awesome icons

Description

Retrieves Font Awesome icon names, optionally filtered by a search query or category. Results can be returned as a plain character vector or as a tibble with category classification.

Usage

fa_icons(
  query = NULL,
  category = NULL,
  regex = FALSE,
  classify = TRUE,
  include_unclassified = TRUE,
  class_map = NULL,
  primary_only = TRUE,
  as_vector = FALSE
)

Arguments

Value

When as_vector = TRUE, a sorted character vector of icon names. Otherwise a tibble with columns:

icon

Icon name (character).

primary_class

Primary category the icon belongs to, or NA when unclassified (character).

all_classes

All matching categories (list-column of character vectors). Only present when primary_only = FALSE.

Examples

# All icons as a classified tibble
fa_icons()

# Quick lookup -- plain sorted vector
head(fa_icons(as_vector = TRUE), 10)

# Search for icons whose name contains "heart"
fa_icons(query = "heart")

# Filter by category
fa_icons(category = "animals")

# Regex search -- all icons starting with "arrow"
fa_icons(query = "^arrow", regex = TRUE)

Fetches the df_coordinates_final Dataset

Description

Downloads and caches the df_coordinates_final dataset if it is not already cached locally. This function ensures that the dataset is downloaded only once and loaded into memory without cluttering the global environment. The dataset is stored in a package-specific cache directory and retrieved efficiently for subsequent uses.

Usage

fetch_df_coordinates()

Details

The dataset is downloaded from GitHub The file is cached in a directory specific to the package, which is determined using R_user_dir. If the dataset is already cached, it will be loaded directly from the cache instead of downloading again.

Value

A data frame containing the df_coordinates_final dataset.

Examples

df <- fetch_df_coordinates()
head(df)

Create a scatter plot with Font Awesome icons instead of points

Description

Works exactly like geom_point(), but renders Font Awesome icons instead of dots. Pass any data with x and y variables - no special formatting required.

Usage

geom_icon_point(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  icon = NULL,
  size = 1,
  dpi = 50,
  legend_icons = TRUE,
  stroke_width = NULL,
  icon_path = NULL,
  ...
)

Arguments

Value

A ggplot layer.

Aesthetics

geom_icon_point uses standard ggplot2 scatter plot aesthetics:

• x - Numeric variable for x-axis

• y - Numeric variable for y-axis

• icon - Font Awesome icon name (optional, column or mapped)

• color/colour - Color grouping

• alpha - Transparency

• size - Icon size

Examples

library(ggplot2)
data <- data.frame(
  x = rnorm(20),
  y = rnorm(20),
  category = sample(c("A", "B", "C"), 20, replace = TRUE),
  icon = sample(c("heart", "star", "circle"), 20, replace = TRUE)
)

# Map icon to a column
ggplot(data, aes(x = x, y = y, icon = icon, color = category)) +
  geom_icon_point()

# Use a fixed icon
ggplot(data, aes(x = x, y = y, color = category)) +
  geom_icon_point(icon = "star")

Create a circular representative population chart

Description

Draws a circular representative population chart based on group proportions, where each point (person) represents a fixed number of individuals. Each person is rendered as a Font Awesome icon.

Usage

geom_pop(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  icon = "ggmale",
  group_var = NULL,
  sample_size = NULL,
  arrange = FALSE,
  seed = NULL,
  sum_var = NULL,
  facet = NULL,
  size = 1,
  dpi = 50,
  legend_icons = TRUE,
  stroke_width = NULL,
  icon_path = NULL,
  ...
)

Arguments

Value

A ggplot layer that renders a circular population chart with icons.

Aesthetics

geom_pop understands the following aesthetics:

• icon: Font Awesome icon name (mapped column)

• group: grouping variable for raw data mode

• color/colour: icon color

• alpha: transparency (must be mapped)

• size: icon size (mapped or fixed)

See Also

geom_icon_point, process_data, geom_image

Examples

library(ggplot2)

df <- data.frame(
  sex  = rep(c("F", "M"), each = 10),
  icon = rep(c("female", "male"), each = 10)
)

ggplot() +
  geom_pop(
    data = df,
    aes(icon = icon, group = sex, color = sex),
    size = 3,
    dpi = 80
  )

List the icon markers ggpop can render by name

Description

Returns the bundled ggpop marker names and, if an icon directory is given, the names of the user SVGs found there. These names (plus any Font Awesome name) are valid values for the icon aesthetic of geom_pop() and geom_icon_point().

Usage

ggpop_markers(icon_path = getOption("ggpop.icon_path"))

Arguments

Value

A list with element bundled (character vector of marker names) and, when icon_path resolves to a directory, user.

Examples

ggpop_markers()

Build icon grid rows from plot data

Description

Derives the icon row/column positions from the unique combinations in df, returning a plain data frame ready to rbind() with group and symbol rows before passing to legend_canvas.

Usage

icon_grid(df, icon, label, row, col, label_fn = NULL, section = "grid")

Arguments

Value

A data frame with columns section, type, label, color, icon, row, col. Rows are sorted by row then column (factor level order respected).

See Also

legend_canvas

Examples

# df_icons <- icon_grid(
#   df, icon = "icon", label = "AgeLabel",
#   row = "StartAge", col = "StopAge",
#   label_fn = function(x) gsub(" ", "", x)
# )

Add typed symbol entries to a legend canvas

Description

Adds a column of symbol + label entries to an existing ggplot canvas (typically the output of marker_legend) using the same ggplot2::annotate() approach. The coordinate system is shared with the base plot, so positions integrate seamlessly with the rest of the legend.

Three entry types are supported:

swatch

A filled rectangle (colour bands, modality tiles).

line

A horizontal segment (frontier or trend lines).

point

A bold "*" glyph rendered as text.

A fourth entry kind, icon, exists in legend_canvas's df_legend vocabulary but is not a key_legend() type - icon rows are rendered separately via marker_legend.

Two y-placement modes:

• y_start = NULL (default) - first entry is placed at the section-title row (row_spacing * title_frac), matching the position where marker_legend() puts section headers. Use this when entry\,1 is both the title and its own symbol (e.g. the "Efficient frontier" line entry).

• y_start = 0 - first entry at row\,1, second at -row_spacing, etc. Use this with a text-only title.

Usage

key_legend(
  entries,
  x = 0,
  y_start = NULL,
  title = NULL,
  title_frac = 0.85,
  row_spacing = 1,
  key_width = 1.2,
  label_gap = 0.3,
  label_size = 2.8,
  label_color = "black",
  label_inside = FALSE,
  label_fontface = "plain",
  title_color = NULL,
  swatch_height = 0.45,
  point_size = 1.6
)

Arguments

Value

A ggpop_key_legend object. Add it to any ggplot with + to inject the annotate layers onto that canvas. Print it (or use it standalone) to render a self-contained legend panel.

See Also

marker_legend

Examples

library(ggplot2)
s  <- 0.78
rs <- 0.34 * s

ef <- data.frame(
  type  = c("line",               "swatch",    "point"),
  label = c("Efficient frontier", "Grey zone",  "Near efficient"),
  color = c("black",              "grey50",     "black"),
  stringsAsFactors = FALSE
)

# Standalone panel:
print(key_legend(ef, row_spacing = rs, key_width = 0.22))

# Added to a marker_legend canvas:
# p <- marker_legend(age_entries, ...) +
#        key_legend(ef, x = 1.10, row_spacing = rs, key_width = 0.22)

Draw a border tightly around a composite legend's rendered content

Description

legend_canvas positions its sections from nominal geometry, but text labels overflow their anchor points by an amount that depends on the font, the label strings, and the final output size - none of which are known when the layers are built. A border drawn from that nominal geometry therefore clips the labels. legend_box() sidesteps this by rendering the legend once at the intended output size, measuring the true pixel extent of the drawn content, mapping it back to data coordinates, and adding a border rectangle around it.

Because it renders once to measure, the border reflects exactly what will be drawn - long labels, mixed fonts, any content - with no per-figure hand tuning.

Usage

legend_box(
  plot,
  width,
  height,
  padding = c(0.02, 0.12),
  colour = "black",
  linewidth = 0.7,
  fill = NA,
  threshold = 150,
  dpi = 150
)

Arguments

Value

plot with a border ggplot2::annotate("rect", ...) layer added.

See Also

legend_canvas, legend_strip

Build a composite legend from a plain data frame

Description

Renders a legend from a data frame that combines icon grid rows (built with icon_grid), colour tile rows, and typed-symbol rows via rbind(). Layout parameters determine where each section is positioned. The scale parameter multiplies all size and spacing values so the data frame can be written in round numbers.

Usage

legend_canvas(
  df_legend,
  grid_section = "grid",
  grid_title = NULL,
  group_section = NULL,
  group_title = NULL,
  group_width = NULL,
  group_gap = 0.08,
  group_label_size = NA_real_,
  group_label_color = "white",
  group_swatch_height = 0.44,
  symbol_section = NULL,
  symbol_right_gap = 0.3,
  symbol_key_width = 0.2,
  symbol_label_gap = NULL,
  col_spacing,
  row_spacing,
  label_gap,
  marker_size,
  label_size,
  label_fontface = "plain",
  scale = 1,
  label_scale = 1,
  dpi = 300,
  xlim = NULL,
  ylim = NULL,
  x_margin = c(1, 1),
  align = NULL,
  y_margin = c(1.1, 1.1),
  valign = NULL,
  clip = "off"
)

Arguments

Value

A ggplot ready to save or pass to legend_strip.

See Also

icon_grid, key_legend, legend_strip

Build a bordered composite legend in one call

Description

Opinionated wrapper over legend_canvas + legend_box for the recurring three-section legend (an icon grid, a block of colour tiles, and a small typed-symbol key). You supply the content (df_legend) and the strip size; the wrapper applies a fixed proportion ladder (legend_ratios) driven by three base sizes, centres the content in the strip, and fits a border to the rendered result.

Every layout length is a multiple of one module; every text size is a multiple of one text base; icons use one marker size. A label_size column on the symbol-section rows is read as multiples of text.

The base sizes are calibrated for a base_width-inch strip and are scaled by width / base_width, so a legend keeps identical proportions at any output width - pass your width and the text, markers, and layout all follow. The group and symbol blocks may hold more entries than the grid has rows; the border grows to enclose whichever section runs deepest.

The group colour swatches are rectangles in data coordinates, so shrinking content_range to make sparse content fill a wide strip stretches them into banners while the fixed-size icons stay put. legend_composite() warns (class "ggpop_swatch_aspect_warning") when the rendered swatch aspect ratio gets banner-like, pointing you to raise content_range or reduce width - keep sparse legends compact rather than stretched.

Usage

legend_composite(
  df_legend,
  width,
  height,
  grid_title = NULL,
  group_title = NULL,
  grid_section = "grid",
  group_section = "group",
  symbol_section = "symbol",
  module = 0.44294,
  text = 7.756,
  marker = 4.562,
  content_range = 7.21636,
  base_width = 27,
  swatch_height = 0.8,
  fontface = "plain",
  border = "#231F20",
  border_padding = c(0.018, 0.09),
  ratios = legend_ratios(),
  dpi = 300
)

Arguments

Value

A ggplot with a fitted border, ready for legend_strip.

See Also

legend_canvas, legend_box, legend_ratios, legend_strip

Default proportion ladder for legend_composite

Description

Returns the fixed layout proportions used by legend_composite as a named list. Lengths are multiples of the layout module (see the module argument there); the two *_label entries are multiples of the text base (text there). Override individual entries and pass the result back via legend_composite(ratios = ...).

Usage

legend_ratios()

Value

A named list of proportions.

See Also

legend_composite

Attach a legend strip below a ggplot

Description

Returns a ggpop_legend_strip object. When added to a ggplot with +, produces a ggpop_composite that stacks the main plot above the strip at the specified physical height. The composite works with ggplot2::ggsave() and print(). The main plot (the object legend_strip() is added to) may itself be a patchwork object (e.g. several panels combined with +/plot_layout)

• this requires the patchwork package to be installed.

Usage

legend_strip(strip_plot, height)

Arguments

Value

A ggpop_legend_strip object; add it to a ggplot with +.

See Also

marker_legend, key_legend

Examples

# p_legend <- marker_legend(entries, ...) + key_legend(...)
# p_full   <- p_scatter + legend_strip(p_legend, height = 1.326)
# ggplot2::ggsave("out.png", p_full, width = 10.5, height = 8.826, dpi = 150)

Build a standalone composite legend of icon markers

Description

For an ordinary legend keyed to your plot data you do not need this function - map an aesthetic and let ggplot2 build the legend natively: geom_icon_point(..., legend_icons = TRUE) + scale_legend_icon().

Use marker_legend() only for a standalone composite legend that ggplot2's guide system cannot express - a multi-column grouped legend decoupled from any plot, often combined with extra annotations and exported at fixed pixel dimensions (for example the screening-strategy Legend_*.png figures).

Usage

marker_legend(
  entries,
  layout = c("column", "grid"),
  ncol = 1,
  title = NULL,
  marker_size = 3,
  label_size = 2.8,
  dpi = 300,
  icon_path = NULL,
  col_spacing = 10,
  row_spacing = 1,
  label_gap = 0.6,
  label_colour = "black",
  label_fontface = "plain",
  default_color = "black"
)

Arguments

Details

Lays out icon + label entries into a self-contained ggplot object. Each entry is drawn with geom_icon_point, so any icon source is accepted - Font Awesome names, bundled ggpop markers, or user-supplied .svg paths (see ggpop_markers) - and the three may be mixed in a single legend. The result is a plain ggplot you can extend with further ggplot2::annotate() layers (frontier segments, colour bands, asterisks) and export at any size with ggplot2::ggsave().

Value

A ggplot object with theme_void() applied.

See Also

geom_icon_point, ggpop_markers

Examples

# For a normal data-driven legend, prefer the native path instead:
#   geom_icon_point(aes(icon = icon, colour = group), legend_icons = TRUE) +
#   scale_legend_icon()

# marker_legend() is for a STANDALONE composite legend - here two semantic
# colour-columns, the kind ggplot2 guides cannot produce in one figure.
df_legend <- data.frame(
  column = c(1, 1, 2, 2),
  icon   = c("square-inset", "circle-solid", "square-hollow", "diamond-cross"),
  label  = c("Start 45y", "Start 50y", "Stop 75y", "Stop 80y"),
  colour = c("#FF1493", "#FF1493", "#006400", "#006400"),
  stringsAsFactors = FALSE
)
marker_legend(df_legend, col_spacing = 12)

Process Population Data for Visualization

Description

The process_data function processes a dataset to calculate group proportions and generates a sampled dataset based on specified parameters. This processed data is suitable for creating visual representations, such as population charts, where each sample represents a group with associated counts and proportions.

Usage

process_data(
  data,
  high_group_var = NULL,
  group_var,
  sum_var = NULL,
  sample_size = 100
)

Arguments

Value

A tibble (data frame) with the following columns:

type

The sampled group type.

group

The group identifier.

n

The count of individuals in the group.

prop

The proportion of the group relative to the total population.

Legend helper for geom_pop/geom_icon_point legends

Description

A convenience function to set appropriate legend key sizes for icon-based legends. This is equivalent to using theme(legend.key.size = ...) but provides sensible defaults for population icon plots.

Usage

scale_legend_icon(
  size = 10,
  unit = "mm",
  spacing = 0.2,
  size_multiplier = 2,
  ...
)

Arguments

Value

A ggplot2 theme object that can be added to a plot.

Examples

library(ggplot2)
df <- data.frame(
  type = rep(c("A", "B"), each = 10),
  icon = rep(c("circle", "square"), each = 10)
)
ggplot(df, aes(icon = icon, color = type)) +
  geom_pop() +
  scale_legend_icon(size = 20)

Population Plot Theme

Description

A minimal theme optimized for icon-based population plots. Similar to theme_void() but with automatic legend key sizing, appropriate margins, and sensible defaults for population visualizations.

Usage

theme_pop(
  base_size = 11,
  base_family = "",
  base_line_size = base_size/22,
  base_rect_size = base_size/22,
  legend_icon_size = NULL,
  legend_spacing = NULL,
  plot_margin = NULL,
  legend_position = "right"
)

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
df <- data.frame(
  type = rep(c("A", "B"), each = 10),
  icon = rep(c("circle", "square"), each = 10)
)
ggplot(data = df, aes(icon = icon, color = type)) +
  geom_pop(size = 1) +
  theme_pop()

Dark Population Plot Theme

Description

A dark variant of theme_pop() with white text on black background. Perfect for presentations or dark-mode visualizations.

Usage

theme_pop_dark(
  base_size = 11,
  base_family = "",
  base_line_size = base_size/22,
  base_rect_size = base_size/22,
  legend_icon_size = NULL,
  legend_spacing = NULL,
  plot_margin = NULL,
  legend_position = "right",
  bg_color = "black",
  text_color = "white"
)

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
df <- data.frame(
  type = rep(c("A", "B"), each = 10),
  icon = rep(c("circle", "square"), each = 10)
)
ggplot(data = df, aes(icon = icon, color = type)) +
  geom_pop(size = 1) +
  theme_pop_dark(base_size = 40)

Minimal Population Plot Theme

Description

An ultra-minimal variant with no margins or legend, perfect for icon arrays without annotations.

Usage

theme_pop_minimal(base_size = 11, base_family = "")

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
df <- data.frame(
  type = rep(c("A", "B"), each = 10),
  icon = rep(c("circle", "square"), each = 10)
)
ggplot(data = df, aes(icon = icon, color = type)) +
  geom_pop(size = 1) +
  theme_pop_minimal()

Validation Functions for geom_pop

Description

Internal validators for parameter and data validation in geom_pop(). These functions are not exported and are used internally by the package.