LICENSE.md
vignettes/articles/guide_composition.Rmd
guide_composition.Rmd
-library(gguidance) +library(legendry) #> Loading required package: ggplot2
library(gguidance) +library(legendry) #> Loading required package: ggplot2
library(legendry) #> Loading required package: ggplot2
The expert’s eye may have noticed that not all exported functionality -are full blown guides -or key +are full blown guides +or key constructors. Besides aforementioned important components, let’s talk a bit about the innards of guides.
In gguidance, we have the same composition operation: +
In legendry, we have the same composition operation: compose_stack(). For your regular axis guides for the x and y aesthetics, it works the same way as guide_axis_stack(). However, if the guides it stacks @@ -131,10 +131,10 @@
compose_stack()
x
y
guide_axis_stack()
guide_axis_base()
standard + guides(x = compose_stack( @@ -151,8 +151,8 @@ Introducing the rest of the familyrange -key and power the display of nested +triplet: brackets, boxes and fences. These require a more niche range +key and power the display of nested axes. range_key <- key_range_manual( diff --git a/articles/index.html b/articles/index.html index 206658a..bff6f08 100644 --- a/articles/index.html +++ b/articles/index.html @@ -1,11 +1,11 @@ -Articles • gguidance +Articles • legendry Skip to contents - gguidance + legendry 0.0.0.9001 @@ -25,7 +25,7 @@ Changelog - + diff --git a/articles/keys.html b/articles/keys.html index d02d918..1248505 100644 --- a/articles/keys.html +++ b/articles/keys.html @@ -5,7 +5,7 @@ -Key information • gguidance +Key information • legendry @@ -18,7 +18,7 @@ - gguidance + legendry 0.0.0.9001 @@ -44,7 +44,7 @@ - + @@ -60,14 +60,14 @@ Key information - Source: vignettes/articles/keys.Rmd + Source: vignettes/articles/keys.Rmd keys.Rmd -library(gguidance) +library(legendry) #> Loading required package: ggplot2 Rather than information that is key, this article will discuss information about keys. @@ -106,10 +106,10 @@ Keys in vanilla ggplot2#> 6 0.9545455 7 7 0
range_key <- key_range_manual( diff --git a/articles/index.html b/articles/index.html index 206658a..bff6f08 100644 --- a/articles/index.html +++ b/articles/index.html @@ -1,11 +1,11 @@ -Articles • gguidance +Articles • legendry Skip to contents - gguidance + legendry 0.0.0.9001 @@ -25,7 +25,7 @@ Changelog - + diff --git a/articles/keys.html b/articles/keys.html index d02d918..1248505 100644 --- a/articles/keys.html +++ b/articles/keys.html @@ -5,7 +5,7 @@ -Key information • gguidance +Key information • legendry @@ -18,7 +18,7 @@ - gguidance + legendry 0.0.0.9001 @@ -44,7 +44,7 @@ - + @@ -60,14 +60,14 @@ Key information - Source: vignettes/articles/keys.Rmd + Source: vignettes/articles/keys.Rmd keys.Rmd
vignettes/articles/keys.Rmd
keys.Rmd
Rather than information that is key, this article will discuss information about keys.
The key difference between keys in gguidance and keys in ggplot2, is -that gguidance exposes users to keys. At first, this can be an +
The key difference between keys in legendry and keys in ggplot2, is +that legendry exposes users to keys. At first, this can be an inconvenience, but it allows for a greater degree of customisation.
If you want custom labels, you can set the label -argument. Most guides in gguidance accept a key argument, +argument. Most guides in legendry accept a key argument, which will cause the guide to display the information in the key, rather than the information automatically derived from the scale.
label
key
@@ -167,7 +167,7 @@ Regular keys Some keys don’t directly return data frames, but return instructions on how these keys should interact with scales. For example -key_auto(), the default key for many guides in gguidance, +key_auto(), the default key for many guides in legendry, needs to know the range in which to populate tickmarks. key <- key_auto() @@ -180,8 +180,8 @@ Regular keys#> class(df) <- c("key_standard", "key_guide", class(df)) #> df #> } -#> <bytecode: 0x55b42287c4b8> -#> <environment: 0x55b42287f280> +#> <bytecode: 0x55b1a8fb9d20> +#> <environment: 0x55b1a8fbcae8>
Some keys don’t directly return data frames, but return instructions on how these keys should interact with scales. For example -key_auto(), the default key for many guides in gguidance, +key_auto(), the default key for many guides in legendry, needs to know the range in which to populate tickmarks.
key_auto()
key <- key_auto() @@ -180,8 +180,8 @@ Regular keys#> class(df) <- c("key_standard", "key_guide", class(df)) #> df #> } -#> <bytecode: 0x55b42287c4b8> -#> <environment: 0x55b42287f280>
We can preview what values they’d label by letting the key absorb a scale with known limits.
@@ -196,7 +196,7 @@ Regular keys Ranged keys -A special type of guide you may find in gguidance are so called +A special type of guide you may find in legendry are so called ‘ranged’ guides. The only difference with regular guides is that they do not mark a single point for an aesthetic, but rather use a start- and end-point to mark a range of the aesthetic. This can be convenient to diff --git a/articles/tour.html b/articles/tour.html index be006f2..91f99c3 100644 --- a/articles/tour.html +++ b/articles/tour.html @@ -5,7 +5,7 @@ -A guided tour • gguidance +A guided tour • legendry @@ -18,7 +18,7 @@ - gguidance + legendry 0.0.0.9001 @@ -44,7 +44,7 @@ - + @@ -60,18 +60,18 @@ A guided tour - Source: vignettes/articles/tour.Rmd + Source: vignettes/articles/tour.Rmd tour.Rmd
A special type of guide you may find in gguidance are so called +
A special type of guide you may find in legendry are so called ‘ranged’ guides. The only difference with regular guides is that they do not mark a single point for an aesthetic, but rather use a start- and end-point to mark a range of the aesthetic. This can be convenient to diff --git a/articles/tour.html b/articles/tour.html index be006f2..91f99c3 100644 --- a/articles/tour.html +++ b/articles/tour.html @@ -5,7 +5,7 @@ -
vignettes/articles/tour.Rmd
tour.Rmd
-library(gguidance) +library(legendry) #> Loading required package: ggplot2 library(scales)
library(gguidance) +library(legendry) #> Loading required package: ggplot2 library(scales)
library(legendry) #> Loading required package: ggplot2 library(scales)
This article walks through all full guide extensions to give a broad -overview of the ‘easy’ way to make use of gguidance. Rest assured, there +overview of the ‘easy’ way to make use of legendry. Rest assured, there are harder ways, but these will be covered in a separate article.
In gguidance, the staple axis is guide_axis_base(). At a +
In legendry, the staple axis is guide_axis_base(). At a first glance, these axes are utterly unremarkable and very much mirror ggplot2::guide_axis() by design.
ggplot2::guide_axis()
@@ -184,7 +184,7 @@ Brackets To change the style of the range indicators, you can choose a different bracket setting. The theme elements -gguidance.bracket and gguidance.bracket.size +legendry.bracket and legendry.bracket.size control the styling and size of the line. These settings have a shortcut in theme_guide(). @@ -219,15 +219,15 @@ Brackets coord_equal() Quite possibly, there might be bracket shapes you want to use, but -aren’t built into gguidance. Luckily, we can build custom brackets, -using a numeric matrix that: +aren’t built into legendry. Luckily, we can build custom brackets, using +a numeric matrix that: Has 2 columns corresponding to the x and y coordinates. Has at least 2 rows. Only has values between 0 and 1. The x-coordinate will be stretched along the axis, whereas y will be -squished to fit the gguidance.bracket.size theme setting. A +squished to fit the legendry.bracket.size theme setting. A custom bracket can just be provided to the bracket argument. @@ -303,7 +303,7 @@ Colours Bars and steps -Two variants for colour guides exist in {gguidance}: +Two variants for colour guides exist in {legendry}: guide_colbar() that reflects diff --git a/authors.html b/authors.html index 2d51c68..79fd7b0 100644 --- a/authors.html +++ b/authors.html @@ -1,11 +1,11 @@ -Authors and Citation • gguidance +Authors and Citation • legendry Skip to contents - gguidance + legendry 0.0.0.9001 @@ -25,7 +25,7 @@ Changelog - + @@ -47,20 +47,20 @@ Authors Citation - Source: DESCRIPTION + Source: DESCRIPTION van den Brand T (2024). -gguidance: Extended guide options for 'ggplot2'. +legendry: Extended guide options for 'ggplot2'. R package version 0.0.0.9001, -https://github.com/teunbrand/gguidance, https://teunbrand.github.io/gguidance/. +https://github.com/teunbrand/legendry, https://teunbrand.github.io/legendry/. @Manual{, - title = {gguidance: Extended guide options for 'ggplot2'}, + title = {legendry: Extended guide options for 'ggplot2'}, author = {Teun {van den Brand}}, year = {2024}, note = {R package version 0.0.0.9001, - https://github.com/teunbrand/gguidance}, - url = {https://teunbrand.github.io/gguidance/}, + https://github.com/teunbrand/legendry}, + url = {https://teunbrand.github.io/legendry/}, } diff --git a/index.html b/index.html index a9c1f7a..e6b70be 100644 --- a/index.html +++ b/index.html @@ -5,7 +5,7 @@ -Extended guide options for ggplot2 • gguidance +Extended guide options for ggplot2 • legendry @@ -13,7 +13,7 @@ - + Skip to contents @@ -21,7 +21,7 @@ - gguidance + legendry 0.0.0.9001 @@ -47,7 +47,7 @@ - + @@ -57,27 +57,27 @@ -gguidance - +legendry + -The goal of gguidance is to provide additional guide functionality to the ggplot2 ecosystem. +The goal of legendry is to provide additional guide functionality to the ggplot2 ecosystem. Installation -You can install the development version of gguidance from GitHub with: +You can install the development version of legendry from GitHub with: # install.packages("devtools") -devtools::install_github("teunbrand/gguidance") +devtools::install_github("teunbrand/legendry") Example Let’s first set up a basic plot to experiment with: -library(gguidance) +library(legendry) #> Loading required package: ggplot2 base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + @@ -88,7 +88,7 @@ Example col = "City miles\nper gallon" ) + theme(axis.line = element_line()) -The gguidance package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation: +The legendry package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation: The axis guide has an option for bidirectional ticks. The colourbar automatically recognises out-of-bounds values and displays this with a cap. @@ -103,7 +103,7 @@ Example x = guide_axis_base(bidi = TRUE) ) -Besides complete guides, gguidance also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed. +Besides complete guides, legendry also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed. # A partial guide to display a bracket efficient_bracket <- primitive_bracket( @@ -119,7 +119,7 @@ Example base + guides(y = guide_axis_stack("axis", efficient_bracket)) -The gguidance package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition. +The legendry package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition. base + scale_colour_viridis_c( @@ -135,7 +135,7 @@ Example
To change the style of the range indicators, you can choose a different bracket setting. The theme elements -gguidance.bracket and gguidance.bracket.size +legendry.bracket and legendry.bracket.size control the styling and size of the line. These settings have a shortcut in theme_guide().
bracket
gguidance.bracket
gguidance.bracket.size
legendry.bracket
legendry.bracket.size
theme_guide()
@@ -219,15 +219,15 @@ Brackets coord_equal()
Quite possibly, there might be bracket shapes you want to use, but -aren’t built into gguidance. Luckily, we can build custom brackets, -using a numeric matrix that:
The x-coordinate will be stretched along the axis, whereas y will be -squished to fit the gguidance.bracket.size theme setting. A +squished to fit the legendry.bracket.size theme setting. A custom bracket can just be provided to the bracket argument.
@@ -303,7 +303,7 @@ Colours Bars and steps -Two variants for colour guides exist in {gguidance}: +Two variants for colour guides exist in {legendry}: guide_colbar() that reflects diff --git a/authors.html b/authors.html index 2d51c68..79fd7b0 100644 --- a/authors.html +++ b/authors.html @@ -1,11 +1,11 @@ -Authors and Citation • gguidance +Authors and Citation • legendry Skip to contents - gguidance + legendry 0.0.0.9001 @@ -25,7 +25,7 @@ Changelog - + @@ -47,20 +47,20 @@ Authors Citation - Source: DESCRIPTION + Source: DESCRIPTION van den Brand T (2024). -gguidance: Extended guide options for 'ggplot2'. +legendry: Extended guide options for 'ggplot2'. R package version 0.0.0.9001, -https://github.com/teunbrand/gguidance, https://teunbrand.github.io/gguidance/. +https://github.com/teunbrand/legendry, https://teunbrand.github.io/legendry/. @Manual{, - title = {gguidance: Extended guide options for 'ggplot2'}, + title = {legendry: Extended guide options for 'ggplot2'}, author = {Teun {van den Brand}}, year = {2024}, note = {R package version 0.0.0.9001, - https://github.com/teunbrand/gguidance}, - url = {https://teunbrand.github.io/gguidance/}, + https://github.com/teunbrand/legendry}, + url = {https://teunbrand.github.io/legendry/}, } diff --git a/index.html b/index.html index a9c1f7a..e6b70be 100644 --- a/index.html +++ b/index.html @@ -5,7 +5,7 @@ -Extended guide options for ggplot2 • gguidance +Extended guide options for ggplot2 • legendry @@ -13,7 +13,7 @@ - + Skip to contents @@ -21,7 +21,7 @@ - gguidance + legendry 0.0.0.9001 @@ -47,7 +47,7 @@ - + @@ -57,27 +57,27 @@ -gguidance - +legendry + -The goal of gguidance is to provide additional guide functionality to the ggplot2 ecosystem. +The goal of legendry is to provide additional guide functionality to the ggplot2 ecosystem. Installation -You can install the development version of gguidance from GitHub with: +You can install the development version of legendry from GitHub with: # install.packages("devtools") -devtools::install_github("teunbrand/gguidance") +devtools::install_github("teunbrand/legendry") Example Let’s first set up a basic plot to experiment with: -library(gguidance) +library(legendry) #> Loading required package: ggplot2 base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + @@ -88,7 +88,7 @@ Example col = "City miles\nper gallon" ) + theme(axis.line = element_line()) -The gguidance package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation: +The legendry package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation: The axis guide has an option for bidirectional ticks. The colourbar automatically recognises out-of-bounds values and displays this with a cap. @@ -103,7 +103,7 @@ Example x = guide_axis_base(bidi = TRUE) ) -Besides complete guides, gguidance also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed. +Besides complete guides, legendry also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed. # A partial guide to display a bracket efficient_bracket <- primitive_bracket( @@ -119,7 +119,7 @@ Example base + guides(y = guide_axis_stack("axis", efficient_bracket)) -The gguidance package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition. +The legendry package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition. base + scale_colour_viridis_c( @@ -135,7 +135,7 @@ Example
Two variants for colour guides exist in {gguidance}:
Two variants for colour guides exist in {legendry}:
guide_colbar()
Source: DESCRIPTION
DESCRIPTION
van den Brand T (2024). -gguidance: Extended guide options for 'ggplot2'. +legendry: Extended guide options for 'ggplot2'. R package version 0.0.0.9001, -https://github.com/teunbrand/gguidance, https://teunbrand.github.io/gguidance/. +https://github.com/teunbrand/legendry, https://teunbrand.github.io/legendry/.
@Manual{, - title = {gguidance: Extended guide options for 'ggplot2'}, + title = {legendry: Extended guide options for 'ggplot2'}, author = {Teun {van den Brand}}, year = {2024}, note = {R package version 0.0.0.9001, - https://github.com/teunbrand/gguidance}, - url = {https://teunbrand.github.io/gguidance/}, + https://github.com/teunbrand/legendry}, + url = {https://teunbrand.github.io/legendry/}, }
The goal of gguidance is to provide additional guide functionality to the ggplot2 ecosystem.
The goal of legendry is to provide additional guide functionality to the ggplot2 ecosystem.
You can install the development version of gguidance from GitHub with:
You can install the development version of legendry from GitHub with:
# install.packages("devtools") -devtools::install_github("teunbrand/gguidance")
Let’s first set up a basic plot to experiment with:
-library(gguidance) +library(legendry) #> Loading required package: ggplot2 base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + @@ -88,7 +88,7 @@ Example col = "City miles\nper gallon" ) + theme(axis.line = element_line())
library(gguidance) +library(legendry) #> Loading required package: ggplot2 base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + @@ -88,7 +88,7 @@ Example col = "City miles\nper gallon" ) + theme(axis.line = element_line())
library(legendry) #> Loading required package: ggplot2 base <- ggplot(mpg, aes(displ, hwy, colour = cty)) + @@ -88,7 +88,7 @@ Example col = "City miles\nper gallon" ) + theme(axis.line = element_line())
The gguidance package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation:
guides()
guide
The legendry package offers a selection of what it calls ‘complete guides’. These complete guides can just be drop-in replacement of regular guides, which you can specify using ggplot2’s guides() function or using the guide argument in scales. In the example below, we’re using two custom variants of vanilla guides, namely guide_axis_base() and guide_colbar(). These custom variants have additional options that allow a greater degree of customisation:
Besides complete guides, gguidance also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed.
ggplot2::guide_axis_stack()
Besides complete guides, legendry also has incomplete guides that can be composed. The ggplot2::guide_axis_stack() is an axis composition function that can be used to display multiple guides. Here, we use a ‘primitive’ guide (incomplete building block) to display a range on the axis. By stacking it with a regular axis the primitive guide is completed.
# A partial guide to display a bracket efficient_bracket <- primitive_bracket( @@ -119,7 +119,7 @@ Example base + guides(y = guide_axis_stack("axis", efficient_bracket))
The gguidance package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition.
The legendry package extends this guide composition concept beyond the axes for other types of guides. In the example below we compose a ‘sandwich’: a central guide flanked by two others. Because our bracket is a primitive, it does not matter what aesthetic it displays and we can re-use it for the sandwich. I’ve yet to write the vignette on composition.
base + scale_colour_viridis_c( @@ -135,7 +135,7 @@ Example