Tips

Essential rules when using ggpop.

1. Valid icon names only. The icon column must contain valid Font Awesome names. Use fa_icons(query = "...") to find them.

2. Reserved column names. Rename any column named x1, y1, pos, image, alpha, coord_size, icon_size, or icon_stroke_width before calling either geom.

3. Use color, not fill. fill is not supported in geom_pop() or geom_icon_point() and will error.

# Wrong
aes(icon = icon, fill = sex)

# Correct
aes(icon = icon, color = sex)

4. alpha is a reserved column name. Rename transparency columns (e.g. to opacity) before mapping them. Suppress the auto-generated alpha legend with guides(alpha = "none").

# Wrong -- alpha is reserved internally
df$alpha <- c(1.0, 0.6, 0.3)
aes(alpha = alpha)

# Correct
df$opacity <- c(1.0, 0.6, 0.3)
aes(alpha = opacity)
# + guides(alpha = "none") to hide the extra legend entry

5. Max 1,000 icons per panel in geom_pop() function Use process_data(sample_size = ...) to stay within limits. With facet_wrap(), the cap applies per panel, not globally. This is ignored in geom_icon_point(), which can handle more icons but may become cluttered.

6. Do not map x or y in geom_pop(). Layout is computed internally. Mapping x or y raises a warning and is silently ignored.

# Wrong
geom_pop(data = df, aes(icon = icon, color = sex, x = sex, y = sex))

# Correct
geom_pop(data = df, aes(icon = icon, color = sex))

7. scale_legend_icon() must come after all theme() calls. A theme() call placed after scale_legend_icon() resets the legend key size.

# Correct order
ggplot(...) +
  geom_pop(..., legend_icons = TRUE) +
  theme_pop() +
  theme(...) +
  scale_legend_icon(size = 8)

8. One icon per legend group when legend_icons = TRUE. Each value of the color aesthetic must map to exactly one icon name. Multiple icons mapped to the same color group will raise a warning.

9. Use seed for reproducible layouts. Pass a fixed integer to get identical icon placement across runs.

geom_pop(..., seed = 42)

10. high_group_var takes a character string. in porcess_data() function

# Wrong
process_data(data = df, group_var = sex, sum_var = n,
             high_group_var = region)

# Correct
process_data(data = df, group_var = sex, sum_var = n,
             high_group_var = "region")