gf_text_repel: Repulsive textual annotations

In ProjectMOSAIC/ggformulaExtra: Extended Features for 'ggformula'

Description

'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.

Usage

gf_text_repel(object = NULL, gformula = NULL, data = NULL, 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, xlab,
  ylab, title, subtitle, caption, stat = "identity", position = "identity",
  show.legend = NA, show.help = NULL, inherit = TRUE,
  environment = parent.frame(), ...)

gf_label_repel(object = NULL, gformula = NULL, data = NULL, 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, xlab,
  ylab, title, subtitle, caption, stat = "identity", position = "identity",
  show.legend = NA, show.help = NULL, inherit = TRUE,
  environment = parent.frame(), ...)

Arguments

object	When chaining, this holds an object produced in the earlier portions of the chain. Most users can safely ignore this argument. See details and examples.
gformula	A formula with shape y ~ x. Faceting can be achieved by including | in the formula.
data	A data frame with the variables to be plotted.
label	The text to be displayed.
alpha	Opacity (0 = invisible, 1 = opaque).
angle	An angle for rotating the text.
color	A color or a formula used for mapping color.
family	A font family.
fontface	One of "plain", "bold", "italic", or "bold italic".
group	Used for grouping.
hjust	Numbers between 0 and 1 indicating how to justify text relative the the specified location.
lineheight	Line height.
size	A numeric size or a formula used for mapping size.
vjust	Numbers between 0 and 1 indicating how to justify text relative the the specified location.
parse	If TRUE, the labels will be parsed into expressions and displayed as described in ?plotmath
box.padding	Amount of padding around bounding box, as unit or number. Defaults to 0.25. (Default unit is lines, but other units can be specified by passing unit(x, "units")).
point.padding	Amount of padding around labeled point, as unit or number. Defaults to 0. (Default unit is lines, but other units can be specified by passing unit(x, "units")).
segment.colour	Colour of the line segment. Defaults to the same colour as the text. In the unlikely event you specify both US and UK spellings of colour, the US spelling will take precedence.
segment.color	Colour of the line segment. Defaults to the same colour as the text. In the unlikely event you specify both US and UK spellings of colour, the US spelling will take precedence.
segment.size	Width of line segment connecting the data point to the text label, in mm.
segment.alpha	Transparency of the line segment. Defaults to the same transparency as the text.
min.segment.length	Skip drawing segments shorter than this, as unit or number. Defaults to 0.5. (Default unit is lines, but other units can be specified by passing unit(x, "units")).
arrow	specification for arrow heads, as created by arrow
force	Force of repulsion between overlapping text labels. Defaults to 1.
max.iter	Maximum number of iterations to try to resolve overlaps. Defaults to 2000.
nudge_x	Horizontal and vertical adjustment to nudge labels by. Useful for offsetting text from points, particularly on discrete scales.
nudge_y	Horizontal and vertical adjustment to nudge labels by. Useful for offsetting text from points, particularly on discrete scales.
xlim	Limits for the x and y axes. Text labels will be constrained to these limits. By default, text labels are constrained to the entire plot area.
ylim	Limits for the x and y axes. Text labels will be constrained to these limits. By default, text labels are constrained to the entire plot area.
direction	"both", "x", or "y" – direction in which to adjust position of labels
seed	Random seed passed to set.seed. Defaults to NA, which means that set.seed will not be called.
xlab	Label for x-axis. See also gf_labs().
ylab	Label for y-axis. See also gf_labs().
title	Title, sub-title, and caption for the plot. See also gf_labs().
subtitle	Title, sub-title, and caption for the plot. See also gf_labs().
caption	Title, sub-title, and caption for the plot. See also gf_labs().
stat	A character string naming the stat used to make the layer.
position	Either a character string naming the position function used for the layer or a position object returned from a call to a position function.
show.legend	A logical indicating whether this layer should be included in the legends. NA, the default, includes layer in the legends if any of the attributes of the layer are mapped.
show.help	If TRUE, display some minimal help.
inherit	A logical indicating whether default attributes are inherited.
environment	An environment in which to look for variables not found in data.
...	Additional arguments. Typically these are (a) ggplot2 aesthetics to be set with attribute = value, (b) ggplot2 aesthetics to be mapped with attribute = ~expression, or (c) attributes of the layer as a whole, which are set with attribute = value.
label.padding	Amount of padding around label. Defaults to 0.25 lines.
label.r	Radius of rounded corners. Defaults to 0.15 lines.
label.size	Size of label border, in mm.

Details

Positional aesthetics are specified using the formula in gformula. Setting and mapping of additional attributes can be done through the use of additional arguments. Attributes can be set can be set using arguments of the form attribute = value or mapped using arguments of the form attribute = ~ expression.

In formulas of the form A | B, B will be used to form facets using facet_wrap() or facet_grid(). This provides an alternative to gf_facet_wrap() and gf_facet_grid() that is terser and may feel more familiar to users of lattice.

Evaluation of the ggplot2 code occurs in the environment of gformula. This will typically do the right thing when formulas are created on the fly, but might not be the right thing if formulas created in one environment are used to create plots in another.

Value

a gg object

geom_label_repel

Currently geom_label_repel does not support the rot argument and is considerably slower than geom_text_repel. The fill aesthetic controls the background colour of the label.

Alignment with hjust or vjust

The arguments hjust and vjust are supported, but they only control the initial positioning, so repulsive forces may disrupt alignment. Alignment with hjust will be preserved if labels only move up and down by using direction="y". For vjust, use direction="x".

See Also

ggplot2::geom_text()

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())

ProjectMOSAIC/ggformulaExtra documentation built on May 31, 2019, 6:14 p.m.