#' Repulsive textual annotations
#'
#' `gf_text_repel()` adds a layer of text; `gf_label_repel()` additionally
#' draws a rectangle beneath the text, making it easier to read. In both
#' cases the labels repel away form each otehr and the data points.
#'
#' @inherit ggformula::gf_text
#' @inherit ggrepel::geom_text_repel
#' @importFrom ggrepel geom_text_repel geom_label_repel
#' @import ggplot2
#' @import ggformula
#'
#' @export
gf_text_repel <-
ggformula::layer_factory(
layer_fun = ggrepel::geom_text_repel,
geom = "text_repel",
stat = "identity",
position = "identity",
aes_form = y ~ x,
extras = alist(
label = , alpha = , angle = , color = , family = , fontface = ,
group = , hjust = , lineheight = , size = , vjust = ,
parse = FALSE,
box.padding = 0.25, point.padding = 1e-06,
segment.colour = NULL, segment.color = NULL,
segment.size = 0.5, segment.alpha = NULL,
min.segment.length = 0.5, arrow = NULL, force = 1,
max.iter = 2000, nudge_x = 0, nudge_y = 0,
xlim = c(NA, NA), ylim = c(NA, NA),
direction = c("both", "y", "x"),
seed = NA
)
)
#' @examples
#' mtcars$model <- rownames(mtcars)
#' mtcars$cylinders <- factor(mtcars$cyl)
#'
#' p <-
#' gf_point(mpg ~ wt, data = mtcars, color = ~ cylinders)
#'
#' # Avoid overlaps by repelling text labels
#' p %>% gf_text_repel(label = ~ model)
#'
#' # Labels with background
#' p %>% gf_label_repel(label = ~ model)
#'
#' # Add aesthetic mappings
#' p %>% gf_text_repel(alpha = ~ wt, size = ~ mpg, label = ~ model)
#' p %>% gf_label_repel(label = ~ model,
#' fill = ~ factor(cyl), color = "white", segment.color = "black")
#'
#' # Draw all line segments
#' p %>% gf_text_repel(label = ~ model, min.segment.length = 0)
#'
#' # Omit short line segments (default behavior)
#' p %>% gf_text_repel(label = ~ model, min.segment.length = 0.5)
#'
#' # Omit all line segments
#' p %>% gf_text_repel(label = ~ model, segment.colour = NA)
#' p %>% gf_text_repel(label = ~ model, min.segment.length = Inf)
#'
#' # Repel just the labels and totally ignore the data points
#' p %>% gf_text_repel(label = ~ model, point.padding = NA)
#'
#' # Hide some of the labels, but repel from all data points
#' mtcars$label <- rownames(mtcars)
#' mtcars$label[1:15] <- ""
#' p %>% gf_text_repel(data = mtcars, label = ~ label)
#'
#' # Nudge the starting positions
#' p %>% gf_text_repel(
#' label = ~ model,
#' nudge_x = ifelse(mtcars$cyl == 6, 2, 0),
#' nudge_y = ifelse(mtcars$cyl == 6, 7, 0))
#'
#' # Change the text size
#' p %>% gf_text_repel(label = ~ model, size = ~ wt)
#'
#' # Scale height of text, rather than sqrt(height)
#' p %>%
#' gf_text_repel(label = ~ model, size = ~ wt) %>%
#' gf_refine(scale_radius(range = c(3, 6)))
#'
#' # You can display expressions by setting parse = TRUE. The
#' # details of the display are described in `?plotmath`, but note that
#' # `gf_text_repel()` uses strings, not expressions.
#' p %>%
#' gf_text_repel(label = ~ paste(wt, "^(", cyl, ")", sep = ""),
#' parse = TRUE)
#'
#' # Add arrows
#' p %>%
#' gf_point(colour = "black") %>%
#' gf_text_repel(
#' label = ~ model,
#' arrow = arrow(length = unit(0.02, "npc")),
#' box.padding = 1
#' )
#'
#' gf_point( 1 ~ wt, data = mtcars, color = "red") %>%
#' gf_text_repel(label = ~ model,
#' nudge_y = 0.04,
#' direction = "x",
#' angle = 90,
#' vjust = 0,
#' segment.size = 0.2) %>%
#' gf_lims(x = c(1, 6), y = c(1, 0.9)) %>%
#' gf_theme(
#' axis.line.y = element_blank(),
#' axis.ticks.y = element_blank(),
#' axis.text.y = element_blank(),
#' axis.title.y = element_blank()
#' ) %>%
#' gf_theme(theme_bw())
#' @rdname gf_text_repel
#'
#' @export
gf_label_repel <-
ggformula::layer_factory(
layer_fun = ggrepel::geom_label_repel,
geom = "text_repel",
stat = "identity",
position = "identity",
pre = {
if (nudge_x != 0 || nudge_y != 0)
position <- position_nudge(nudge_x, nudge_y)
},
aes_form = y ~ x,
extras = alist(
label = , alpha = , angle = , color = , family = , fontface = ,
group = , hjust = , lineheight = , size = , vjust = ,
parse = FALSE,
box.padding = 0.25, label.padding = 0.25, point.padding = 1e-06,
label.r = 0.15, label.size = 0.25,
segment.colour = NULL, segment.color = NULL,
segment.size = 0.5, segment.alpha = NULL,
min.segment.length = 0.5, arrow = NULL, force = 1,
max.iter = 2000, nudge_x = 0, nudge_y = 0,
xlim = c(NA, NA), ylim = c(NA, NA),
direction = c("both", "y", "x"),
seed = NA
)
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.