plot_dot: Plot a dot plot, either with or without lollipop sticks
In flaneuse/llamar: Plotting Functions and Styles for Livelihoods Analysis Work

Creates a dot plot for a single grouping variable. Can make a simple dot plot or a lollipop plot

plot_dot(df, by_var = "region", value_var = "avg", incl_x_axis = TRUE,
  x_label = NULL, x_limits = NULL, x_breaks = waiver(),
  sort_asc = FALSE, sort_by = "avg", plot_ci = FALSE, lb_var = "lb",
  ub_var = "ub", ci_colour = grey25K, ci_alpha = 0.6, ci_size = 2,
  ref_line = FALSE, ref_text = "sample average", label_ref_val = TRUE,
  nudge_ref_label = 0.05 * diff(range(abs(df[[value_var]]))),
  ref_label_y = 1, ref_arrow = arrow(length = unit(0.007, "npc")),
  ref_stroke = 0.5, ref_colour = grey75K, lollipop = FALSE,
  lollipop_ref = "0", lollipop_stroke = 0.25, lollipop_colour = grey75K,
  facet_var = NULL, ncol = NULL, nrow = NULL, scales = "fixed",
  dot_size = 6, dot_shape = 21, dot_fill_cont = brewer.pal(9, "YlGnBu"),
  dot_fill_limits = c(min(df[[value_var]]), max(df[[value_var]])),
  label_vals = TRUE, label_size = 3, label_colour = grey75K,
  label_digits = 1, percent_vals = FALSE, value_label_offset = 0.05 *
  diff(range(abs(df[[value_var]]))), sat_threshold = 0.5, horiz = TRUE,
  file_name = NULL, width = 10, height = 6, saveBoth = FALSE,
  font_normal = "Lato", font_semi = "Lato", font_light = "Lato Light",
  panel_spacing = 1, font_axis_label = 12,
  font_axis_title = font_axis_label * 1.15, font_facet = font_axis_label *
  1.15, font_legend_title = font_axis_label,
  font_legend_label = font_axis_label * 0.8, font_subtitle = font_axis_label
  * 1.2, font_title = font_axis_label * 1.3, legend.position = "none",
  legend.direction = "horizontal", grey_background = FALSE,
  background_colour = grey10K, projector = FALSE)

`df`	data frame containing all the data.
`by_var`	string containing the variable to put along the y-axis.
`value_var`	string containing the variable to plot on the x-axis (and to use for the color values)
`incl_x_axis`	TRUE/FALSE of whether to include x-axis lables
`x_label`	(optional) string containing the label for the x-axis
`x_limits`	tuple specifying x-axis limits
`x_breaks`	list containing break point values for the x-axis.
`sort_asc`	TRUE/FALSE of whether to sort the values in ascending or descending order
`sort_by`	string containing column name within df to sort the values by
`plot_ci`	TRUE/FALSE of whether to plot segments underneath the dots containing the confidence interval limits
`lb_var`	string name within df containing the lower limit of confidence interval
`ub_var`	string name within df containing the upper limit of confidence interval
`ci_colour`	color for confidence intervals
`ci_alpha`	alpha (opacity) for confidence intervals
`ci_size`	thickness of confidence interval segment (in points)
`ref_line`	TRUE/FALSE or number. If false, no reference line will be included. If true, sample average will be calculated. Be careful: if there are a different number of observations in each observation, your average will be off. If a number, will include a reference line at that location.
`ref_text`	what to label the reference line with
`label_ref_val`	TRUE/FALSE. Whether to label the reference line with its value.
`nudge_ref_label`	value to offset the reference line label from the line
`ref_label_y`	reference label y-position
`ref_arrow`	size of arrow to connect the reference label to the line. Specified by arrow(...)
`ref_stroke`	stroke size of the reference line
`ref_colour`	colour of reference line
`lollipop`	TRUE/FALSE of whether to plot as a lollipop plot (dots connected to 'lollipop_ref' by a line)
`lollipop_ref`	string of a numeric value to connect the dots to in lollipop plot; '0' by default
`lollipop_stroke`	lollipop segment stroke size
`lollipop_colour`	lollipop colour
`facet_var`	string with variable name in df to facet by. NULL (no facetting) by default
`ncol`	number of columns in facetting
`nrow`	number of rows in facetting
`scales`	scales wtihin facetting. One of 'fixed', 'free', 'free_y', 'free_x'
`dot_size`	size of dots (in mm)
`dot_shape`	shape of dots (normal ggplot2 values for shapes)
`dot_fill_cont`	colour palette for fill of dots. Can also be a single color.
`dot_fill_limits`	limits for color fill palette
`label_vals`	TRUE/FALSE of whether to directly label the dots with their value. if include CIs, value labels are directly on top of dots.
`label_size`	size of the value labels (in mm)
`label_colour`	colour of value labels
`label_digits`	number of digits to include in value labels
`percent_vals`	TRUE/FALSE of whether to turn value labels into percents.
`value_label_offset`	numeric x-offset for value labels from their dot.
`sat_threshold`	if include CIs, numeric break point for when numbers switch from being white text to dark grey. Based on the saturation values of the underlying color.
`horiz`	= TRUE/FALSE of whether to plot horizontally or vertically.
`file_name`	if not NULL, string containing the file name or path to save the plot to (as either .pdf or .png)
`width`	= width (in inches) of exported plot
`height`	= height (in inches) of exported plot
`saveBoth`	TRUE/FALSE if should save both .png and .pdf. If TRUE, don't include file extension in 'file_name'
`font_normal`	string containing font name for boldest text.
`font_semi`	string containing font name for medium bold text.
`font_light`	string containing font name for lightest text.
`panel_spacing`	panel spacing, in lines, between facet panels
`font_axis_label`	size (in points) of axis labels
`font_axis_title`	size (in points) of axis title
`font_facet`	size (in points) of axis facet labels
`font_legend_title`	size (in points) of legend title
`font_legend_label`	size (in points) of legend text
`font_subtitle`	size (in points) of plot subtitle
`font_title`	size (in points) of plot title
`legend.position`	where to put legend. Unplotted, by default
`legend.direction`	'horizontal' or 'vertical' placement of legend
`grey_background`	TRUE/FALSE of whether to color the area outside the plot
`background_colour`	(optional) colour of the background
`projector`	if TRUE, make text and axis lines bolder for use with a projector

# generate random data
library(dplyr)
df = data.frame(avg = sample(1:100, 10), region = letters[1:10], ci = sample(1:100, 10)/10) %>% mutate(lb = avg - ci, ub = avg + ci)

# sans confidence intervals
plot_dot(df, by_var = 'region', value_var = 'avg')

# remove sorting
plot_dot(df, by_var = 'region', value_var = 'avg', sort_by = 'region')

# with confidence intervals, no labels
plot_dot(df, by_var = 'region', value_var = 'avg', plot_ci = TRUE, label_vals = FALSE)

# with confidence intervals and labels
plot_dot(df, by_var = 'region', value_var = 'avg', plot_ci = TRUE)
# adjusting breakpoint for text value labels on top of dots.
plot_dot(df, by_var = 'region', value_var = 'avg', plot_ci = TRUE, sat_threshold = 0.2)

# as lollipops
df2 = data.frame(avg = sample(-100:100, 10)/100, region = letters[1:10], ci = sample(1:100, 20)/1000) %>% mutate(lb = avg - ci, ub = avg + ci)
library(RColorBrewer)
plot_dot(df2, by_var = 'region', value_var = 'avg', lollipop = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'))

# change the lollipop reference point to 0.25
plot_dot(df2, by_var = 'region', value_var = 'avg', lollipop = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'), lollipop_ref = '0.25')

# percent labels
plot_dot(df2, by_var = 'region', value_var = 'avg', percent_vals = TRUE, lollipop = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'))

# with reference line
plot_dot(df2, by_var = 'region', value_var = 'avg', ref_line = 0, ref_text = 'no change', label_ref = FALSE, lollipop = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'), percent_vals = TRUE)

# horizontal
plot_dot(df2, by_var = 'region', value_var = 'avg', horiz = FALSE, ref_line = 0, ref_text = 'no change', label_ref = FALSE, lollipop = TRUE, plot_ci = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'))

# in-built facet_wrap. Note: may screw up ordering, since will sort based on ALL the data.
df3 = data.frame(avg = sample(-100:100, 20), region = rep(letters[1:10], 2), group = c(rep('group1', 10), rep('group2', 10)))
plot_dot(df3, by_var = 'region', value_var = 'avg', facet_var = 'group', lollipop = TRUE, dot_fill_cont = brewer.pal(10, 'RdYlBu'))