ggfittext (version 0.7.0)

geom_fit_text: A 'ggplot2' geom to fit text inside a box

Description

geom_fit_text() shrinks, grows or wraps text to fit inside a defined rectangular area.

Usage

geom_fit_text(mapping = NULL, data = NULL, stat = "identity",
  position = "identity", na.rm = FALSE, show.legend = NA,
  inherit.aes = TRUE, padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(0.1, "lines"), place = "centre",
  min.size = 4, grow = FALSE, reflow = FALSE, width = NULL,
  height = NULL, formatter = NULL, ...)

Arguments

mapping

ggplot2::aes() object as standard in 'ggplot2'. Note that aesthetics specifying the box must be provided. See Details.

data, stat, position, na.rm, show.legend, inherit.aes, ...

Standard geom arguments as for ggplot2::geom_text().

padding.x, padding.y

Amount of horizontal and vertical padding around the text, expressed as grid::unit() objects. Default to 1 mm and 0.1 lines respectively.

place

Where inside the box to place the text. Default is 'centre'; other options are 'topleft', 'top', 'topright', etc.

min.size

Minimum font size, in points. If provided, text that would need to be shrunk below this size to fit the box will not be drawn. Defaults to 4 pt.

grow

If TRUE, text will be grown as well as shrunk to fill the box. See Details.

reflow

If TRUE, text will be reflowed (wrapped) to better fit the box. See Details.

width, height

When using x and/or y aesthetics, these can be used to set the width and/or height of the box. These should be either numeric values on the x and y scales or grid::unit() objects.

formatter

A function that will be applied to the text before it is drawn. This can be useful when using geom_fit_text() in an automated context, such as with the 'gganimate' package. formatter will be applied serially to each element in the label column, so it does not need to be a vectorised function.

Aesthetics

• label (required)

• (xmin AND xmax) OR x (required)

• (ymin AND ymax) OR y (required)

• alpha

• angle

• colour

• family

• fontface

• lineheight

• size

Details

Except where noted, geom_fit_text() behaves more or less like ggplot2::geom_text().

There are three ways to define the box in which you want the text to be drawn:

1. On a continuous axis, the limits of the box can be defined in the data using plot aesthetics: 'xmin' and 'xmax', and/or 'ymin' and 'ymax'.

2. Alternatively on a continuous axis, the centre of the box can be defined in the data with the 'x' and/or 'y' aesthetic, and the width and/or height of the box can be specified with a 'width' and/or 'height' argument. 'width' and 'height' should be provided as grid::unit() objects; if not, they will be assumed to use the native axis scale.

3. On a discrete (categorical) axis, the width or height will be determined automatically. This can be overridden if you wish using the 'width' and 'height' arguments.

By default, the text will be drawn as if with geom_text(), unless it is too big for the box, in which case it will be shrunk to fit the box. With grow = TRUE, the text will be made to fill the box completely whether that requires shrinking or growing.

reflow = TRUE will cause the text to be reflowed (wrapped) to better fit in the box. When grow = FALSE (default), text that fits the box will be drawn as if with geom_text(); text that doesn't fit the box will be reflowed until it does. If the text cannot be made to fit by reflowing alone, it will be reflowed to match the aspect ratio of the box as closely as possible, then be shrunk to fit the box. When grow = TRUE, the text will be reflowed to best match the aspect ratio of the box, then made to fill the box completely whether that requires growing or shrinking. Existing line breaks in the text will be respected when reflowing.

Examples

# NOT RUN {
ggplot2::ggplot(ggplot2::presidential, ggplot2::aes(ymin = start, ymax = end,
    label = name, x = party)) +
  geom_fit_text(grow = TRUE)

# }