Repository files navigation

The goal of gghdx is to make it as simple as possible to follow the HDXvisual guidelines when creating graphs using ggplot2. While most of thefunctionality is in allowing easy application of the HDX color ramps,the package also streamlines some of the other recommendations and bestpractices regarding plotted text, axis gridlines, and other visualfeatures. The key functionalities are:

• theme_hdx() is the general package theme.
• scale_color_hdx_...() andscale_fill_hdx_...() applies the HDXcolor scale to the relevant aesthetics.
• hdx_colors(),hdx_hex(), andhdx_pal_...() provide easy useraccess to the HDX color template. You can view the colors
• geom_text_hdx() andgeom_label_hdx() wrap the respective basefunctions to plot text using HDX fonts and aesthetics.
• scale_y_continuous_hdx() wrapsscale_y_continuous() to plot datadirectly starting from the y-axis.
• gghdx() ensures plot for the session use HDX defaults for color andfill scales, usestheme_hdx() for all plots, and appliesscale_color_hdx_...() andscale_fill_hdx_...()
• label_number_hdx() andformat_number_hdx() supplement thescales::label_...() series of functions to format and create labelsfor numbers in the HDX style.

You can install gghdx directly from CRAN:

install.packages("gghdx")

You can install the development version from GitHub:

## install.packages("remotes")remotes::install_github("OCHA-DAP/gghdx")

The package is designed so the user just has to rungghdx() once asession and mainly forget about it. This will automatically set yourggplot2 to use the HDX theme, palettes, fonts, and more by default. Ifyou want more control or want to better understand how the packageworks, please see the details below!

A quick and simple example would be plotting theiris dataset includedin base R.

library(ggplot2)p<- ggplot(iris,  aes(x=Sepal.Length,y=Petal.Length,color=Species  ))+  geom_point()+  labs(title="Iris species distributed by sepal and petal lengths",y="Petal length",x="Sepal length"  )p

This output using the base ggplot style doesn’t look particularly bad,but we can usetheme_hdx() to quickly adjust some of the styling tofit the style guide.

library(gghdx)p+ theme_hdx(base_family="sans")

Now, axis lines have been cleaned up and the plot better resemblesrecommendations from the visual guide with just that single line ofcode.

However, the color palette for the points is still using the base Rpalette. We can use one of the manyscale_...hdx() functions to useHDX colors. Let’s just use the primary discrete color scale that willalign each species with one of the 3 non-gray colorramps (sapphire,mint, and tomato).

p+ theme_hdx(base_family="sans")+ scale_color_hdx_discrete()

You can check the documentation of any of thescale_...hdx() functionsto see all available scales, or directly access the colors usinghdx_colors() or the raw list inhdx_color_list. The availablepalettes can be easily visualized usinghdx_display_pal().

We also would like to use the HDX font family. Since Source Sans 3 is afree Google font, it makes it relatively easy to access in R. gghdx usesthesysfonts package toload the Google font and thenshowtext to include themin our plot. You can also use theextrafont package as analternative if you have the font installed locally. This requiresghostscript to be installed locally and can run into other issues, suchasfont names not beingfound.

Below, I use the showtext package because it’s simpler.

library(showtext)#> Loading required package: sysfonts#> Loading required package: showtextdbfont_add_google("Source Sans 3")showtext_auto()p+ theme_hdx(base_family="Source Sans 3")+ scale_color_hdx_discrete()

As clear above, even though we have an HDX theme function, we still haveto separately call the scale function to adjust our colors. And we haveto call these every time we make a new plot. So, to make life simpler,gghdx() is provided as a convenience function that sets ggplot to:

• automatically use the HDX theme by default;
• use default HDX sapphire for point and line colors and and HDX mintfor fill when not an aesthetic;
• usescale_fill_hdx_discrete() andscale_color_hdx_discrete() asthe default discrete fill and color respectively;
• usescale_fill_gradient_hdx_mint() andscale_color_gradient_hdx_sapphire() as the default continuous filland color;
• loads the Source Sans 3 font from Google and activates its usage forthe current session.

You just have to rungghdx() once a session, and then our plots willalready be where we would like!

gghdx()p

And voíla, we have our graph without specifying the theme or colorscale.

As a final example, we can closely match the COVID plots referenced inthe visual guide using the theme and color scales in the package.

The inbuilt datagghdx::df_covid has aggregated COVID data we can useto mirror this plot. To make the data start at the y-axis, we can usescale_y_continuous_hdx() which setsexpand = c(0, 0) by default, andthelabel_number_hdx() function to create custom labels.

p_blue<- ggplot(df_covid,  aes(x=date,y=cases_monthly  ))+  geom_bar(stat="identity",width=6,fill= hdx_hex("sapphire-hdx")# use sapphire for fill  )+  scale_y_continuous_hdx(labels= label_number_hdx()  )+  scale_x_date(date_breaks="1 month",labels=function(x) toupper(strftime(x,"%b"))  )+  labs(title="Monthly global COVID-19 confirmed cases in 2020",subtitle="DATA | JUL 2022 | World Health Organization",x="",y=""  )p_blue# create red plotp_blue+  geom_bar(    aes(fill=flag    ),width=6,stat="identity"  )+  scale_fill_hdx_tomato()+  theme(legend.position="none"  )+  labs(title="Monthly COVID-19 # of cases surpasses 8 million"  )

We’ve used relatively few lines of code to match fairly closely theseexamples plots!