# 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")