Package 'marquee'

Description

This function facilitates construction of a complete style set based on the classic look of an HTML rendered markdown document. It contains style specifications for all the supported markdown elements as well as a sub and sup style that can be used for subscripts and superscript respectively. These are only accessible through custom spans (e.g. ⁠H{.sub 2}O⁠) as markdown doesn't provide a syntax for these formats.

Usage

classic_style(
  base_size = 12,
  body_font = "",
  header_font = "",
  code_font = "mono",
  ...
)

Arguments

Value

A style set object

Examples

classic_style(16, "serif", "sans")

Description

This theme element is a drop-in replacement for ggplot2::element_text(). It works by integrating the various style settings of the element into the base style of the provided style set. If a margin is given, it is set on the body tag with skip_inherit(). The default width is NA meaning that it will span as long as the given text is, doing no line wrapping. You can set it to any unit to make it fit within a specific width. However, this may not work as expected with rotated text (you may get lucky). Note that you may see small shifts in the visuals when going from element_text() to element_marquee() as size reporting may differ between the two elements.

Usage

element_marquee(
  family = NULL,
  colour = NULL,
  size = NULL,
  hjust = NULL,
  vjust = NULL,
  angle = NULL,
  lineheight = NULL,
  color = NULL,
  margin = NULL,
  style = NULL,
  width = NULL,
  inherit.blank = FALSE
)

Arguments

Value

An element_marquee object that can be used in place of element_text in ggplot2 theme specifications

Examples

library(ggplot2)
p <- ggplot(mtcars) +
  geom_point(aes(mpg, disp)) +
  labs(title = "A {.red *marquee*} title\n* Look at this bullet list\n\n* great, huh?") +
  theme_gray(base_size = 6) +
  theme(title = element_marquee())

plot(p)

ggplot(mtcars) +
  geom_histogram(aes(x = mpg)) +
  labs(title =
"I put a plot in your title so you can plot while you title

![](p)

What more could you _possibly_ want?") +
  theme(title = element_marquee())

Description

The geom is an extension of geom_text() and geom_label() that allows you to draw richly formatted text in marquee-markdown format in your plot. For plain text it is a near-drop-in replacement for the above geoms except some sizing might be very slightly different. However, using this geom you are able to access the much more powerful font settings available in marquee, so even then it might make sense to opt for this geom.

Usage

geom_marquee(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  size.unit = "mm",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Styling of the text is based on a style set with the exception that the standard aesthetics such as family, size, colour, fill, etc. are recognized and applied to the base tag style. The default style set (classic_style) can be changed using the style aesthetic which can take a vector of style sets so that each text can rely on it's own style if needed. As with element_marquee(), the fill aesthetic is treated differently and not applied to the base tag, but to the body tag as a skip_inherit() style so as to not propagate the fill.

Contrary to the standard text and label geoms, geom_marquee() takes a width aesthetic that can be used to turn on soft wrapping of text. The default value (NA) lets the text run as long as it want's (honoring hard breaks), but setting this to something else will instruct marquee to use at most that amount of space. You can use grid units to set it to an absolute amount.

Value

A ggplot2 layer that can be added to a plot

Examples

library(ggplot2)
# Standard use
p <- ggplot(mtcars, aes(wt, mpg))
p + geom_marquee(aes(label = rownames(mtcars)))

# Make use of more powerful font features (note, result may depend on fonts
# installed on the system)
p + geom_marquee(
  aes(label = rownames(mtcars)),
  style = classic_style(weight = "thin", width = "condensed")
)

# Turn on line wrapping
p + geom_marquee(aes(label = rownames(mtcars)), width = unit(2, "cm"))

# Style like label
label_style <- modify_style(
  classic_style(),
  "body",
  padding = skip_inherit(trbl(4)),
  border = "black",
  border_size = skip_inherit(trbl(1)),
  border_radius = 3
)
p + geom_marquee(aes(label = rownames(mtcars), fill = gear), style = label_style)

# Use markdown to style the text
red_bold_names <- sub("(\\w+)", "{.red **\\1**}", rownames(mtcars))
p + geom_marquee(aes(label = red_bold_names))

Description

This legend appears similar to a subtitle and uses marquee syntax to typeset the text and interpolate legend glyphs.

Usage

guide_marquee(
  title = ggplot2::waiver(),
  style = marquee::style(background = NA),
  detect = FALSE,
  theme = NULL,
  position = "top",
  override.aes = list(),
  order = 1
)

Arguments

Value

A GuideMarquee object that can be passed to the guides() function or used as the guide argument in a scale.

Text formatting

In addition to standard marquee syntax, there is additional syntax to make building a guide easier. In the text below, n marks the n-th break in the scale, label represents any of the scale's labels and foo represents arbitrary text.

• ⁠<<n>>⁠ or ⁠<<label>>⁠ can be used to insert key glyphs into the text.

• ⁠![](n)⁠ or ⁠![](label)⁠ can also be used to insert key glyphs into the text.

• ⁠{.n foo}⁠ or ⁠{.label foo}⁠ applies the style argument to foo, including recoloring when the guide represents a colour or fill scale.

• !!n or !!label translates to ⁠{.label label}⁠ to insert the label verbatim with the application of the style argument.

Examples

library(ggplot2)
# A standard plot
base <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

# Using key glyphs
base + aes(shape = drv) +
  scale_shape_discrete(
    # Same as using <<1>>, <<2>> and <<3>>,
    # or ![](1), ![](2) and ![](3)
    # or ![](4), ![](f) and ![](r)
    name = "Cars with four wheel <<4>>, forward <<f>> or reverse <<r>> drive.",
    guide = "marquee"
  )

# Recolouring text
base <- base +
  aes(colour = drv) +
  labs(
    colour = "Cars with {.4 four wheel}, {.f forward} or {.r reverse} drive."
  )
base + guides(colour = "marquee")

# Adjust display of labels
st <- style(weight = "bold", italic = TRUE, background = NA)
base + guides(colour = guide_marquee(style = st))

# Using background instead of text colour by setting it to NULL
st <- style(color = "black", background = NULL)
base + guides(colour = guide_marquee(style = st))

# Customising style of each label through style sets
# Note: tag names must be universal per `vctrs::vec_as_names` and
# prefixed with `lab_`.
st <- classic_style()
st <- modify_style(st, tag = "lab_f", background = NULL, color = "black")
st <- modify_style(st, tag = "lab_r", border_size = trbl(1),
                   color = "black", background = NA)
base + guides(colour = guide_marquee(style = st))

# Alternatively:
base + guides(colour = "marquee") +
  theme(plot.subtitle = element_marquee(style = st))

# Splicing in labels by number (!!2) or label (!!subcompact)
base + aes(colour = class) +
  labs(colour = "Cars including !!2 and !!subcompact vehicles") +
  guides(colour = "marquee")

# Using automatic detection
base + aes(colour = class) +
  labs(colour = "Cars including suv and minivan vehicles") +
  guides(colour = guide_marquee(detect = TRUE))

Description

Marquee measures the extent of the box around text with bearings, that is, the height of the string "mean" is the same as the height of the string "median", despite the latter having a "d" extending upwards. This makes it easier to justification text irrespective of the glyphs used to render it. However, if you want alignment to be relative to the "tight" box around the text (the bounding box of where ink has been placed), you can use the ink() function to inform marquee of your intend. In general the effect is often minuscule for horizontal justifications but can have a big effect on vertical justification depending on the presence of ascenders and descenders in the rendered glyphs.

Usage

ink(x = numeric(), use_ink = TRUE)

Arguments

Value

A marquee_ink vector

Examples

# Plot to illustrate the difference in vertical alignment
library(grid)
grid.newpage()
grid.draw(
  marquee_grob(
    c("### Textbox justification (default)",
      "### Bounding box justification (using `ink()`)"),
    x = 0.5,
    y = c(0.95, 0.45),
    hjust = 0.5,
    width = NA
  )
)

# Standard justification
grid.draw(
  marquee_grob(
    "mean",
    x = 0.5,
    y = 0.75,
    hjust = "right",
    vjust = 0.5,
    width = NA
  )
)
grid.draw(
  marquee_grob(
    "median",
    x = 0.5,
    y = 0.75,
    hjust = "left",
    vjust = 0.5,
    width = NA
  )
)

# Justification using `ink()`
grid.draw(
  marquee_grob(
    "mean",
    x = 0.5,
    y = 0.25,
    hjust = "right",
    vjust = ink(0.5),
    width = NA
  )
)
grid.draw(
  marquee_grob(
    "median",
    x = 0.5,
    y = 0.25,
    hjust = "left",
    vjust = ink(0.5),
    width = NA
  )
)

Description

If you want to create your markdown programmatically you'd probably want to use some sort of string interpolation such as glue(). However, the custom span syntax of marquee interferes with the standard interpolation syntax of glue. This function let's you use both together.

Usage

marquee_glue(
  ...,
  .sep = "",
  .envir = parent.frame(),
  .open = "{",
  .close = "}",
  .na = "NA",
  .null = character(),
  .comment = character(),
  .literal = FALSE,
  .transformer = NULL,
  .trim = TRUE
)

marquee_glue_data(
  .x,
  ...,
  .sep = "",
  .envir = parent.frame(),
  .open = "{",
  .close = "}",
  .na = "NA",
  .null = character(),
  .comment = character(),
  .literal = FALSE,
  .transformer = NULL,
  .trim = TRUE
)

Arguments

For `glue_data()`, elements in `...` override the values in `.x`.

Details

If you choose a different set of delimiters than "{" and "}" for the interpolation the functions will call the equivalent glue functions directly. However, if you keep the defaults, the functions will use a custom transformer that will make sure to keep the marquee custom span notation. You can both interpolate the content of the span, as well as the span class (see examples)

Value

A character vector

Examples

# standard use
red_text <- "this text will be red"
marquee_glue("This will be black and {.red {red_text}}!")

# if the span is not valid it will be treated as standard glue interpolation
try(
  marquee_glue("This will be black and {.red}!")
)

# You can interpolate the tag name as well
col <- "green"
marquee_glue("This will be black and {.{col} this text will be {col}}!")

# Tag name interpolation must follow a `.` or a `#` as these identify the
# bracket pair as a custom span class
col <- ".yellow"
# This is not what you want probably
marquee_glue("This will be black and {{col} this text will be {col}}!")

# Tag interpolation should also interpolate the full tag and be followed by
# a space in order to be valid
part <- "l"
marquee_glue("This will be black and {.ye{part}low this text will be {col}}!")
try(
  marquee_glue("This will be black and {.{part}avender this text will be {col}}!")
)

Description

This is the main function of marquee. It takes a vector of markdown strings, parses them with the provided style, and returns a grob capable of rendering the parsed text into rich text and (possibly) images. See marquee_parse() for more information about how markdown is parsed and see details below for further information on how rendering proceeds.

Usage

marquee_grob(
  text,
  style = classic_style(),
  ignore_html = TRUE,
  force_body_margin = FALSE,
  x = 0,
  y = 1,
  width = NULL,
  default.units = "npc",
  hjust = "left",
  vjust = "top",
  angle = 0,
  vp = NULL,
  name = NULL
)

Arguments

Value

A grob of class marquee

Rendering style

The rendering more or less adheres to the styling provided by marquee_parse(), but has some intricacies as detailed below:

Tight lists

If a list is tight, the bottom margin of each li tag will be set so the spacing matches the lineheight. Further, the top margin will be set to 0.

Block images

In markdown, image tags are span elements so they can be placed inline. However, if an image tag is the only thing that is contained inside a p tag marquee determines that it should be considered a block element. In that case, the parent p element inherits the styling from the image element so that the image can e.g. adhere to align properties, or provide their own padding.

Horizontal rulers

These elements are rendered as an empty block. The standard style sets a bottom border size and no size for the other sides.

Margin collapsing

Margin calculations follows the margin collapsing rules of HTML. Read more about these at mdn. Margin collapsing means that elements with margin set to 0 might end up with a margin. Specifically for the body element this can be a problem if you want to enforce a tight box around your text. Because of this the force_body_margin argument allows you to overwrite the margins for the body element with the original values after collapsing has been performed.

Underline and strikethrough

Underlines are placed 0.1em below the baseline of the text. Strikethrough are placed 0.3em above the baseline. The width of the line is set to 0.075em. It inherits the color of the text. No further styling is possible.

Spans with background

Consecutive spans with the same background and border settings are merged into a single rectangle. The padding of the span defines the size of the background but will not modify the placement of glyph (i.e. having a left padding will not move the first glyph further away from it's left neighbor).

Bullet position

Bullets are placed, right-aligned, 0.25em to the left of the first line in the li element.

Border with border radius

If borders are not the same on all sides they are drawn one by one. In this case the border radius is ignored.

Image rendering

The image tag can be used to place images. There are support for both png and jpeg images. If the path instead names a grob, ggplot, or patchwork object then this is rendered instead. If the file cannot be read, if it doesn't exist, or if the path names an object that is not a grob, ggplot or patchwork, a placeholder is rendered in it's place (black square with red cross).

Image sizing

There is no standard in markdown for specifying the size of images. By default, block-level images fill the width of it's container and maintain it's aspect ratio. Inline images have a default width of 0.65em and a height matching the aspect ration.

However, if you wish to control sizing, you can instead provide the image as a grob with a viewport with fixed dimensions, in which case this will be used as long as the width doesn't exceed the width of the container (in which case it will get downsized). If a rastergrob is provided without absolute sizing, the aspect ratio will match the raster, otherwise the aspect ratio will be taken from the styling of the element (defaults to 1.65)

Table rendering

While marquee does not support the extended table syntax for markdown it does allow you to include tables in the output. It does so by supporting gt objects as valid paths in image tags in the same way as ggplots etc. This meeans that you can style your tables any way you wish and with the full power of gt, which is much more flexible than the markdown table syntax.

Textbox justification

The justification options exceeds the classic ones provided by grid. While numeric values are available as always, the number of possible text values are larger. Horizontal justification add "left-ink", "center-ink", and "right-ink" which uses the left-most and right-most positioned glyph (or halfway between them) as anchors. Vertical justification has the equivalent "bottom-ink", "center-ink", and "top-ink" anchors, but also "first-line" and "last-line" which sets the anchor at the baseline of the first or last line respectively.

Description

marquee uses an extension of CommonMark with no support for HTML code (it is rendered verbatim). The focus is to allow easy formatting of text for graphics, rather than fully fledged typesetting. See marquee syntax for more about the format.

Usage

marquee_parse(text, style = classic_style(), ignore_html = TRUE)

Arguments

Value

A data frame describing the various tokens of the text and the style to apply to them. The output is mainly meant for programmatic consumption such as in marquee_grob()

marquee tags

marquee tokenizes the input text into blocks and spans. It recognises the following tags:

Block tags

body is the parent tag of a markdown document. It never contains any text itself, only other blocks.

ul is an unordered list. It contains a number of li children

ol is an ordered list. It contains a number of li children

li is a list element. If the list is tight it contains text directly inside of it. If not, text are placed inside child p blocks

hr is a horizontal line, spanning the width of the parent block. For styling, the bottom border size is used when rendering

h1-h6 are headings at different levels

cb is a code block. Text inside code blocks are rendered verbatim, i.e. it cannot contain any children

p is a standard paragraph block. Text separated by two line-ends are separated into separate paragraphs

qb is a quote block. It may contain children

Span tags

em is an emphasized text span. Often this means italicizing the text, but it is ultimately up to the renderer

str is strong text, often rendered with bold text

a is a link text. While marquee rendering doesn't allow for links, it can still be rendered in a particular way

code is text rendered as code. Often this uses a monospaced font. Text inside this span is rendered verbatim

u is text that should be underlined

del is text that should have strikethrough

custom spans is a marquee specific extension to the syntax that allows you to make up tags on the fly. See the section on marquee syntax for more.

marquee syntax

marquee uses md4c which is a fully CommonMark compliant markdown parser. CommonMark is an effort to create an internally coherent markdown specification, something that was missing from the original markdown description. If you are used to writing markdown, you are used to CommonMark. Below is a list of notable additions or details about the specific way marquee handles CommonMark

Underlines and strikethrough

While not part of the basic CommonMark spec, underline and strikethrough are supported by marquee using ⁠_⁠ and ~ (e.g. ⁠_underline this_⁠ and ⁠~this was an error~⁠).

Images

Image tags (⁠![image title](path/to/image)⁠) are supported, but the title is ignored. The path is returned as the token text.

HTML

HTML tags are ignored, i.e. they are rendered verbatim. This is not that different from classic markdown rendering except that people often convert markdown to HTML where these tags suddenly have meaning. They do not carry any special significance when rendered with marquee

Custom tags

While markdown provides most of what is necessary for standard text markup, there are situations, especially in visualisation, where we need something more. Often users reach for inline HTML spans for that, but since HTML is fully ignored in marquee this is not an option. Further, adding in HTML decreases readability of the unformatted text a lot.

With marquee you can create a custom span using the ⁠{.tag <some text>}⁠ syntax, e.g. ⁠{.sm small text}⁠ to wrap "small text" in the sm tag. You can alternatively use ⁠{#tag <some text>}⁠ for the same effect. The only difference is that in the former syntax the . is stripped from the tag name, whereas in the latter the ⁠#⁠ remains part of the name. See the Styling section for the primal use of the latter syntax.

Styling

During parsing, each token is assigned a style based on the provided style set. The styling is cascading, but without the intricacies of CSS. A child element inherits the styling of it's parent for the options that are set to NULL in the style matching the child tag. Any style element that are relative() are computed based on the value of the parent style element. em() elements are resolved based on the size element of the child style, and rem() elements are resolved using the size element of the body style. If a style is not provided for the tag, it fully inherits the style of it's parent.

Automatic coloring Recognizing that the primary use for custom tags may be to change the color of some text, marquee provides a shortcut for this. If a style is not found for the tag in the provided style set, marquee will check if the tag matches a valid color (i.e. a string from grDevices::colors(), or a valid hex string, e.g. ⁠#53f2a9⁠). If it is a valid color it will set this as the font color of the style. This means that parsing "Color {.red this} red" automatically sets the color of "this" to red, even if no style is provided for the red tag. Likewise, parsing "Color {#00FF00 me} green" will automatically set the color of "me" to #00FF00 (fully saturated green).

Additional parsing information

Apart from splitting the text up into tokens, marquee_parse() also provides some additional information useful for rendering the output in the expected way. The id column refers the tokens back to the original input text, the block relates tokens together into blocks. Block elements increment the block count when they are entered, and decrement it when they are excited. The type column provides the type of the block. The indentation column provides the node level in the tree. A child block will increase the indentation for as long as it is active. ol_index provides the number associated with the ordered list element. tight indicates whether the list is tight (i.e. it was provided with no empty lines between list elements). The ends column indicate until which row in the output the tag is active (i.e. the tag is closed after the row indicated by the value in this column).

Examples

marquee_parse("# Header of the example\nSome body text", classic_style())

Description

While element_marquee() should behave similar to ggplot2::element_text() when used on plain text (i.e. text without any markdown markup), the reality can be different. This is because the text shaping engine used by marquee (textshaping::shape_text()) may differ from the one used by the graphics device (which is responsible for laying out text in element_text()). Differences can range from slight differences in letter spacing to using a different font altogether (this is because the font keywords "", "sans", "serif", "mono", and "symbol" may be mapped to different fonts depending on the shaper). One way to handle this is to provide an explicit font name for the elements, but alternatively you can use this function to convert all text elements in a theme to element_marquee()

Usage

marquefy_theme(theme)

Arguments

Value

theme with all text elements substituted for marquee elements

Examples

library(ggplot2)
ggplot(mtcars) +
  geom_point(aes(disp, mpg)) +
  ggtitle("How about that") +
  marquefy_theme(theme_gray())

Description

style() constructs a marquee_style object specifying the styling for a single tag. The meaning of NULL is to inherit the value from the parent element. It follows that top parent (the body element), must have values for all it's options. The base_style() constructor is a convenient constructor for a style with sensible defaults for all it's options.

Usage

style(
  family = NULL,
  weight = NULL,
  italic = NULL,
  width = NULL,
  features = NULL,
  size = NULL,
  color = NULL,
  lineheight = NULL,
  align = NULL,
  tracking = NULL,
  indent = NULL,
  hanging = NULL,
  margin = NULL,
  padding = NULL,
  background = NULL,
  border = NULL,
  border_size = NULL,
  border_radius = NULL,
  bullets = NULL,
  underline = NULL,
  strikethrough = NULL,
  baseline = NULL,
  img_asp = NULL
)

base_style(
  family = "",
  weight = "normal",
  italic = FALSE,
  width = "normal",
  features = systemfonts::font_feature(),
  size = 12,
  color = "black",
  lineheight = 1.6,
  align = "left",
  tracking = 0,
  indent = 0,
  hanging = 0,
  margin = trbl(0, 0, rem(1)),
  padding = trbl(0),
  background = NA,
  border = NA,
  border_size = trbl(0),
  border_radius = 0,
  bullets = marquee_bullets,
  underline = FALSE,
  strikethrough = FALSE,
  baseline = 0,
  img_asp = 1.65
)

Arguments

Value

A marquee_style object

Examples

# A partial style
style(color = "red", underline = TRUE)

# Full style
base_style()

Description

A style set contains information on how to style the various tags in a markdown text. While it is not necessary to provide a style for all tags (it will just inherit the parent if missing), it is required to provide a complete style for the body tag so an option is avialable through inheritance for all tags and all style options. It can often be easier to derive a new style set from an existing one rather than building one from scratch.

Usage

style_set(...)

modify_style(x, tag, ...)

remove_style(x, tag)

Arguments

Value

A marquee_style_set object

Examples

# Create a style
s_set <- style_set(base = base_style(), p = style(indent = em(2)))

# Modify an existing tag
modify_style(s_set, "p", size = 16)

# Add a new tag, supplying a full style object
modify_style(s_set, "str", style(weight = "bold"))

# Same as above, but style object created implicitly
modify_style(s_set, "str", weight = "bold")

# Remove a tag style
remove_style(s_set, "p")

Description

marquee provides a small set of helpers for constructing the needed styles. relative() specifies a numeric value as relative to the value of the parent style by a certain factor, e.g. a font size of relative(0.5) would give a style a font size half of it's parent. em() specify a numeric value as relative to the font size of the current style. If the font size is 12, and indent is set to em(2), then the indent will be equivalent to 24. rem() works like em() but rather than using the font size of the current style it uses the font size of the root style (which is the body element). trbl() helps you construct styles that refers to sides of a rectangle (margin, padding, and border size). The function names refers to the order of the arguments (top, right, bottom, left). skip_inherit() tells the style inheritance to ignore this value and look for the value one above in the stack. marquee_bullets is just a character vector with 6 sensible bullet glyphs for unordered lists.

Usage

relative(x)

em(x)

rem(x)

trbl(top = NULL, right = top, bottom = top, left = right)

skip_inherit(x)

marquee_bullets

Arguments

Format

An object of class character of length 6.

Value

Objects of the relevant class

Examples

relative(0.35)

em(2)

rem(1.2)

# Argument default means it recycles like CSS if fewer values are specified
trbl(6, em(1.5))

skip_inherit("sans")

marquee_bullets