DOCSEARCHbyAlgolia
Submit Docs

legendry R Package

repository·main·Indexed 43 days ago

https://github.com/teunbrand/legendry

An R package that extends the ggplot2 ecosystem with advanced, customizable guide functionality. It provides 'complete guides' as drop-in replacements for standard ggplot2 guides, such as guide_axis_base() and guide_colbar(), and a composition system using primitives and functions like guide_axis_stack() and compose_sandwich() to build complex, layered guides.

Tokens
1K
Snippets
4
Records
4
Agent score
5%

What's inside legendry

  1. Compose guides using primitives and stacking

    main

    Beyond complete guides, legendry introduces 'incomplete guides' (primitives) that can be composed into full guides.

    One way to compose them is using guide_axis_stack(), which allows you to stack a primitive guide on top of a regular guide (like "axis") to complete it. For example, primitive_bracket() can be used to display a range on an axis when stacked.

    When using primitives like primitive_bracket(), you can configure:

    • key: Determines what is displayed (e.g., key_range_manual(start, end, name)).
    • bracket: The shape of the bracket (e.g., "square").
    • theme: A ggplot2 theme object to style the legend text or axis text.
    # A partial guide to display a bracket
efficient_bracket <- primitive_bracket(
  key = key_range_manual(start = 25, end = Inf, name = "Efficient"),
  bracket = "square",
  theme = theme(
    legend.text = element_text(angle = 90, hjust = 0.5),
    axis.text.y.left = element_text(angle = 90, hjust = 0.5)
  )
)

# Stack the primitive with a regular axis
base + guides(y = guide_axis_stack("axis", efficient_bracket))

  3. Use complete guides as drop-in replacements

    main

    The legendry package provides 'complete guides' that act as drop-in replacements for standard ggplot2 guides. You can apply them using the guide argument within a scale function or via the guides() function.

    Key complete guides include:

    • guide_axis_base(): An enhanced axis guide (e.g., supports bidirectional ticks via bidi = TRUE).
    • guide_colbar(): An enhanced colorbar (e.g., automatically handles out-of-bounds values with a cap).

    Note: When using the guide argument in a scale, you can pass the string name of the guide (e.g., guide = "colbar").

    library(legendry)
library(ggplot2)

base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + 
  geom_point() + 
  labs(x = "Engine displacement", y = "Highway miles per gallon", col = "City miles\nper gallon")

# Using guide argument in scale
base + 
  scale_colour_viridis_c(
    limits = c(NA, 30),
    guide = "colbar"
  ) +
  # Using guides() function
  guides(
    x = guide_axis_base(bidi = TRUE)
  )

  4. Compose complex guides with compose_sandwich()

    main

    The legendry package allows for advanced guide composition using patterns like a 'sandwich'. The compose_sandwich() function creates a guide composed of a central element flanked by two others.

    compose_sandwich() takes the following arguments:

    • middle: The central guide component (e.g., gizmo_density()).
    • text: The guide type for the text component (e.g., "axis_base").
    • opposite: The component for the opposite side (can be a primitive or another guide).
    base + 
  scale_colour_viridis_c(
    guide = compose_sandwich(
      middle = gizmo_density(), 
      text = "axis_base",
      opposite = efficient_bracket
    )
  )