Package Workflow and Grammar

The package is designed with Arab Barometer’s data and workflow in mind. The functions in the package were written with the express purpose of working with Arab Barometer data. Arab Barometer data has certain structures and features that ArabBarometR functions expect; especially the functions for creating Arab Barometer branded graphs. It is of course possible for data from other sources to have the features, but that is not guaranteed. I encourage the use of the functions from ArabBarometR with Arab Barometer data, while encouraging caution for use with non Arab Barometer data.

In the same vein, there is a natural workflow to creating Arab Barometer brand graphs. You will see this workflow repeated over and over again throughout this guide. The workflow consists of three steps:

  1. Create summaries of the data.
  2. Plot the summaries.
  3. Save the plots.

In each chapter, you will see how to follow these steps to create a specific type of plot. Generally speaking, for each type of graph there is one function per step. The functions follow naming conventions associated with each step. They are:

  1. calculate_ functions
  2. plot_ functions
  3. AB_save()

The calculate_ and plot_ functions are designed to be chained together for simplicity. That is, you can pipe the output of the calculate_ function into the appropriate plot_ function using either the dplyr package pipe %>% or the native pipe |> found in R 4.0+.

Furthermore, the calculate_ and plot_ functions that are used together have the same suffix. For example, calculate_X works with plot_X, while calculate_Y works with plot_Y.

calculate_ functions

The first two required inputs for any calculate_ function are:

  1. .ab : An Arab Barometer data frame
  2. .var : A variable name from the Arab Barometer data frame

The .ab parameter is specifically referring to Arab Barometer data. The calculate_ function will look for certain features in the data frame that are specific to Arab Barometer data.

All other parameters1 are set to default values. More details on the specifics of the other parameters and their defaults are provided throughout the guide.

plot_ functions

The only required input for the (paired) plot_ functions is .df. The parameter .df is the data frame output of the paired calculate_ function. That is, the plot_ function expects its input to be the output of its matching calculate_ function. For example, plot_X expects its input to be the output of calculate_X and plot_Y expects its input to be the output of calculate_Y.

NOTE: Currently not all plot_ functions have matching calculate_ functions. As the package continues to develop, most (if not all) plot_ functions will be broken up into a matching calculate_ and plot_ function pair.

AB_save()

The function AB_save() is a simple wrapper function for ggsave() from the ggplot2 package. The function sets default saving dimension in accordance with Arab Barometer branding. The only required input is what you would like to name your graph.

  1. As of 2023-01-23; some of this will likely change in the near future.↩︎