Skip to contents

{simplevis} ggplot2 functions are soft-deprecated!

As of {simplevis} 6.4, essentially all ggplot2 wrapper functions in {simplevis} soft deprecated. Users should not rely on these, and use the {ggblanket} package instead.

Purpose

{simplevis} is a package of {ggplot2} and {leaflet} wrapper functions that aims to to simplify beautiful {ggplot2} and {leaflet} visualisation.

Visualisation families

{simplevis} supports many visualisation family types.

4 functions per family: colouring, facetting, neither or both

Each visualisation family generally has four functions.

This is based on whether or not a visualisation is to be:

  • not coloured by a variable and not facetted (*())
  • coloured by a variable, but not facetted (*_col())
  • facetted, but not coloured by a variable (*_facet())
  • coloured by a variable and facetted (*_col_facet())

In {simplevis}, {ggplot2} concepts of col and fill aesthetics have been unified into one for simplicity.

The premise is that these 4 types of visualisation are most common for each visualisation family, and therefore it is useful to make functions that quickly enable these.

All arguments for variables are required unquoted, and follow an *_var format (i.e. x_var, y_var, col_var and facet_var)

For example, code below shows these combinations with code and output for the gg_point*() family.

gg_point(penguins, 
         x_var = bill_length_mm, 
         y_var = body_mass_g)

gg_point_col(penguins, 
             x_var = bill_length_mm, 
             y_var = body_mass_g, 
             col_var = sex)

gg_point_facet(penguins, 
               x_var = bill_length_mm, 
               y_var = body_mass_g, 
               facet_var = species)

gg_point_col_facet(penguins, 
                   x_var = bill_length_mm, 
                   y_var = body_mass_g, 
                   col_var = sex, 
                   facet_var = species)

Minimal code and effort

{simplevis} works with the pipe.

The order of variables in functions is always x_var, y_var, col_var and facet_var as appliable.

So, once familiar with the package, you may choose not to name the arguments of x_var, y_var, col_var and facet_var.

Other variables should always be named.

This can enable great looking plots with minimal code and effort.

penguins %>% 
  gg_point_col_facet(bill_length_mm, body_mass_g, sex, species)

Palettes

For all functions, change the colour palette by supplying a vector of hex code colours to the pal argument.

gg_point(penguins, 
         x_var = bill_length_mm,  
         y_var = body_mass_g,  
         pal = "#da3490")

This method is the same for when you are colouring by a variable, or just colouring all of the geometry in the visualisation a single colour.

gg_point_col(penguins, 
             x_var = bill_length_mm, 
             y_var = body_mass_g, 
             col_var = species, 
             pal = c("#da3490", "#9089fa", "#47e26f"))

Customising with consistent prefixes & autocomplete

There are lots of arguments available to modify the defaults.

In general, arguments have consistent prefixes based on x_*, y_*, col_* or facet_*.

This helps you identify and explore what you need by using the Rstudio autocomplete.

Some common arguments are:

  • *_title to adjust the titles for any x, y or col scale
  • *_labels to adjust labels for any x, y, col or facet scale
  • *_na_rm to remove NA observations in the x, y, col or facet scale
  • *_zero to start at zero for numeric x or y scales
  • *_breaks_n the number of numeric bins of breaks for numeric x, y or col scales to aim for
  • *_rev to reverse the order of categorical x, y, col or facet scales
  • *_expand to add padding to an x or y scale
  • *_zero_mid to place zero in the middle of a numeric scale
  • col_legend_none to turn the legend off.

Below illustrates how to customise titles and control labels through all possible ways.

plot_data <- storms %>%
  group_by(year, status) %>%
  summarise(wind = mean(wind))

col_labels <- c("Hcane", "TDep", "TSt")
names(col_labels) <- sort(unique(plot_data$status))
col_labels
#>           hurricane tropical depression      tropical storm 
#>             "Hcane"              "TDep"               "TSt"

gg_line_col_facet(plot_data, 
                  x_var = year, 
                  y_var = wind, 
                  col_var = status, 
                  facet_var = status, 
                  title = "US storms storm wind speed, 1975-2020",
                  x_title = "Storm year",
                  y_title = "Average storm wind speed",
                  col_title = "Storm status",
                  x_labels = function(x) stringr::str_sub(x, 3, 4),
                  y_labels = scales::label_comma(accuracy = 0.1),
                  col_labels = col_labels,
                  facet_labels = ~ stringr::str_to_sentence(stringr::str_wrap(.x, 5)),
                  y_zero = TRUE,
                  y_breaks_n = 6,
                  y_expand = ggplot2::expansion(add = c(0, 10)),
                  size_point = 1)

The size_ and alpha_ prefixes are used to modify the size and opacity of various aspects of the visualisation.

Themes

You can adjust the theme of any {simplevis} plot by providing a {ggplot2} theme object to the theme argument. You can also create your own quick themes with the {simplevis} gg_theme() function.

custom_theme <- gg_theme(
  pal_body = "white",
  pal_title = "white",
  pal_subtitle = "white",
  pal_background = c("#232323", "black"),
  pal_grid = "black", 
  y_grid = TRUE,
  x_grid = TRUE)

gg_point_col(penguins,
             species,
             x_var = bill_length_mm,
             y_var = body_mass_g, 
             theme = custom_theme)

Maps

{simplevis} also supports sf and stars maps. sf refers to point, line or polygon features, whereas stars refers to arrays (i.e. grids).

For gg_sf*() functions, data must be an sf object and of POINT/MULTIPOINT, LINESTRING/MULTILINESTRING, or POLYGON/MULTIPOLYGON geometry type.

For gg_stars*() functions, data must be a stars object.

For both gg_sf*() and gg_stars*() functions:

  • 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.

The following example objects are provided withing the package for learning purposes: example_point, example_polygon and example_stars.

The borders argument allows for the user to provide an sf object as context to the map (e.g. a coastline or administrative boundaries).

gg_sf_col(example_point, 
          col_var = trend_category, 
          borders = example_borders)

gg_stars_col(example_stars,
             col_var = nitrate,
             col_na_rm = TRUE,
             borders = example_borders)

{simplevis} also provides {leaflet} wrapper functions for sf and stars objects. These functions work in a similar way, but have a leaf_ prefix. Note there is no borders argument available in the leaf_*() functions.

leaf_sf_col(example_point, 
            col_var = trend_category)

Refer to the {leaflet} article for further information.

Extending {simplevis}

All gg_* and leaf_* 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 geom_* layers.

The below example adds error bars, labels, and a new y scale. Note that 25 percentiles and 75 percentiles have been used to demonstrate the errorbars, rather than confidence intervals which would normally be used with error bars.

plot_data <- penguins %>%
  filter(!is.na(body_mass_g)) %>% 
  group_by(species) %>%
  summarise_boxplot_stats(body_mass_g) 

gg_bar_col(plot_data,
           x_var = species,
           y_var = middle,
           col_var = species,
           col_legend_none = TRUE,
           y_title = "Body mass g") +
  ggplot2::geom_errorbar(ggplot2::aes(x = species, ymin = lower, ymax = upper),
                         width = 0.2) +
  ggplot2::geom_text(ggplot2::aes(x = species, y = lower - 500, label = middle),
                     col = "white") +
  ggplot2::scale_y_continuous(
    name = "Body mass g",
    breaks = function(x) pretty(x, 5),
    limits = function(x) c(min(pretty(x, 5)), max(pretty(x, 5))),
    expand = c(0, 0)
  )            

The {patchwork} package can be used to patch visualisations together.

library(patchwork)

p1 <- gg_point(penguins, 
               x_var = species, 
               y_var = body_mass_g, 
               x_jitter = 0.2, 
               alpha_point = 0.5) 

p2 <- gg_boxplot(penguins, 
                 x_var = species, 
                 y_var = body_mass_g) 

p1 + p2

All ggplot objects can be converted into interactive html objects using the plotly::ggplotly function from the {plotly} library.

plot <- gg_point_col(penguins,
                     x_var = bill_length_mm,
                     y_var = body_mass_g,
                     col_var = species)

plotly::ggplotly(plot) %>%
  plotly_camera()

{simplevis} also offers more customisability for making tooltips (i.e. hover values) in ggplotly.

Supported variable classes

Variable types supported by the different families of functions are outlined below.

family data x_var y_var col_var facet_var
bar dataframe Any* Numeric Categorical or numeric Categorical
boxplot dataframe Categorical Numeric Categorical Categorical
density dataframe Numeric NA Categorical Categorical
histogram dataframe Numeric NA Categorical Categorical
line dataframe Any Numeric Categorical Categorical
point dataframe Any Numeric Categorical or numeric Categorical
pointrange dataframe Any Numeric Categorical or numeric Categorical
sf sf NA NA Categorical or numeric Categorical
smooth dataframe Numeric Numeric Categorical Categorical
stars stars NA NA Categorical or numeric NA
tile dataframe Categorical Categorical Categorical or numeric Categorical
violin dataframe Categorical Numeric Categorical Categorical
hbar dataframe Numeric Any* Categorical or numeric Categorical
hboxplot dataframe Numeric Categorical Categorical Categorical
hviolin dataframe Numeric Categorical Categorical Categorical
hpointrange dataframe Numeric Any Categorical or numeric Categorical

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.

Further information

For further information, see the articles on the {simplevis} website.