Colouring, facetting, neither or both
Each visualisation family generally has 4 functions.
The function name specifies whether or not a visualisation is to be coloured by a variable (*_col()), facetted by a variable (*_facet()), or neither (*()) or both of these (*_col_facet()).
Colouring by a variable means that different values of a selected variable are to have different colours. Facetting means that different values of a selected variable are to have their facet.
A *() function such gg_point() requires only a dataset, an x variable and a y variable.
A *_col() function such gg_point_col() requires only a dataset, an x variable, a y variable, and a colour variable.
A *_facet() function such gg_point_facet() requires only a dataset, an x variable, a y variable, and a facet variable.
A *_col_facet() function such gg_point_col_facet() requires only a dataset, an x variable, a y variable, a colour variable, and a facet variable.
Data is generally plotted with a stat of identity, which means data is plotted as is. Only for boxplot, there is a different default stat of boxplot, which means data will be transformed to boxplot statistics.
_sf functions for maps differ slightly, which is discussed further below.
Titles
Defaults titles are:
- no title, subtitle or caption
- x, y and colour titles are converted to sentence case using the
snakecase::to_sentence_case function.
You can customise titles with title, subtitle, x_title, y_title and caption arguments.
gg_point_col(penguins, bill_length_mm, body_mass_g, species,
title = "Adult penguin mass by bill length and species",
subtitle = "Palmer station, Antarctica",
x_title = "Bill length (mm)",
y_title = "Body mass (g)",
col_title = "Penguin species",
caption = "Source: Gorman KB, Williams TD, Fraser WR (2014)")
You can also request no x_title using x_title = "" or likewise for y_title and col_title.
Scales
simplevis makes it easy to make easy scale transformations.
These use consistent prefixes based on x_*, y_*, col_* or facet_*, and as such the autocomplete can help identify what you need.
Some examples of transformations available are:
*_na to quickly not include NA observations*_labels to adjust labels for any x, y, col or facet scale*_zero to start at zero for numeric x or y scales*_pretty_n for the number of numeric bins of breaks for the x or y scale to aim for*_rev to reverse the order of categorical x, y or col scales in bars*_expand to add padding to an x or y scale.
plot_data <- storms %>%
group_by(year) %>%
summarise(wind = mean(wind))
gg_line(plot_data, year, wind,
x_pretty_n = 4,
x_labels = function(x) stringr::str_sub(x, 3, 4),
y_labels = scales::comma_format(accuracy = 0.1),
y_zero = T,
y_pretty_n = 10,
y_expand = ggplot2::expansion(mult = c(0.025, 0.025)))
sf maps
simplevis provides simple feature (sf) maps (i.e. maps with point, line or polygon features).
These functions work in the same way as the ggplot2 graph functions, but with the following noteworthy differences:
- Data must be an
sf object
- Data must be of
POINT/MULTIPOINT, LINESTRING/MULTILINESTRING, or POLYGON/MULTIPOLYGON geometry type
- Data must have a coordinate reference system (CRS) defined
- No
x_var and y_var variables are required
- Borders can added to maps by providing an
sf object to the borders argument.
A couple of example sf objects are provided with the package for learning purposes: example_sf_point and example_sf_polygon.
The borders argument allows for the user to provide an sf object as context to the map (e.g. a coastline or administrative bounrdaries). An sf object of the New Zealand coastline has been provided for learning purposes with the package.
Supported variable classes
variable types supported by the different groups of functions are outlined below.
A stat of identity refers to the value being plotted as it is. A stat of boxplot refers to boxplot statistics being calculated from the data, and these plotted.
tibble::tribble(
~family, ~data, ~x_var, ~y_var, ~col_var, ~facet_var, ~stat,
"bar", "tibble or data.frame", "Any*", "Numeric", "Categorical or numeric", "Categorical", "identity",
"hbar", "tibble or data.frame", "Numeric", "Any*", "Categorical or numeric", "Categorical", "identity",
"line", "tibble or data.frame", "Any", "Numeric", "Categorical or numeric", "Categorical", "identity",
"point", "tibble or data.frame", "Any", "Numeric", "Categorical or numeric", "Categorical", "identity",
"boxplot", "tibble or data.frame", "Any*", "Numeric", "Categorical", "Categorical", "boxplot or identity",
"sf", "sf", NA, NA, "Categorical or numeric", "Categorical", "identity",
) %>%
DT::datatable()
Where:
- Categorical refers to character, factor, or logical classes.
- Numeric refers to double or integer classes.
- Any* refers that if a numeric, date or datetime variable, values must be bins that are mutually exclusive and equidistant.
ggplotly interactive visualisation
All ggplot objects can be converted into interactive html objects using ggplotly. You can simply wrap the plot object in plotly::ggplotly().
The plotly_camera function removes plotly widgets other than the camera to keep things tidy.
simplevis also offers more customisability for making tooltips(i.e. hover values) in ggplotly (i.e. hover values).
A variable can be added to the text_var in the gg_* function. This variable is then used in the ggplotly tooltip when tooltip = text is added to the ggplotly function.
simplevis provides a mutate_text function which can produce a variable that is a string or variable names and values for a tooltip. Note this function converts column names to sentence case using the snakecase::to_sentence_case function.
The mutate_text function uses all variables in the dataset by defalut, but a subset can be used if desired.
Output objects and adding layers
All gg_* and leaflet_* wrapper functions produce ggplot or leaflet objects.
This means layers can be added to the functions in the same way you would a ggplot2 or leaflet object.
Note you need to add all aesthetics to any additional layers.
This means you can facet by more than one variable, provided that you are not using a position of “stack”.
plot_data <- penguins %>%
group_by(species, sex, island) %>%
summarise(body_mass_g = mean(body_mass_g, na.rm = TRUE))
gg_bar(plot_data, sex, body_mass_g,
width = 0.66,
x_na = FALSE,
y_pretty_n = 3) +
facet_grid(rows = vars(species),
cols = vars(island),
labeller = as_labeller(snakecase::to_sentence_case))
