R/geom_sigmark.R

In philstraforelli/ggsigmark: An Implementation of Grammar of Graphics to Denote Statistically Significant Differences

#' Significance Markers for ggplot2
#' @description Apply significance markers onto an existing \link[ggplot2]{ggplot2} chart
#' @param tbl_sig A df object created from \link[ggsigmark]{tbl_sig} functions.
#' @param x A quoted character string of the variable from the `tbl_sig` df charted on the x-axis. Typically this is "level" or "group".
#' @param y A quoted character string of the variable from the `tbl_sig` df charted on the y-axis. Typically this is "pos".
#' @param group An optional quoted character string of the variable from the `tbl_sig` df that is grouped. If needed, it likely needs to be "group".
#' @param colour A quoted character string of the variable from the `tbl_sig` df that applies the subgroup colours. Typically this is "sign".
#' @param icon A quoted character string indicating the type of icon to display to denote statistical significance. Default is "full triangle up".
#' @param size A numeric value indicating the size of the icon. Default is set to 5.
#'
#' @details This is essentially a wrapper for \link[ggplot2]{geom_point}
#'
#' @note The icon argument accepts one of the following strings:
#' \itemize{
#'   \item full triangle up
#'   \item full triangle down
#'   \item clear triangle up
#'   \item clear triangle down
#'   \item arrow up
#'   \item arrow down
#'   \item finger up
#'   \item finger down
#'   \item full star
#'   \item clear star
#'   \item checkmark
#'   \item asterisk
#'   \item heart
#'}
#' @export
#'
#' @examples
#' ### Proportions:
#' colour_vec <- c("NEW ENGLAND" = "#edc951",
#'                 "MIDDLE ATLANTIC" = "#eb6841",
#'                 "E. NOR. CENTRAL" = "#cc2a36",
#'                 "W. NOR. CENTRAL" = "#4f372d",
#'                 "SOUTH ATLANTIC" = "#00a0b0",
#'                 "E. SOU. CENTRAL" = "#2175d9",
#'                 "W. SOU. CENTRAL" = "#00308f",
#'                 "MOUNTAIN" = "#e30074",
#'                 "PACIFIC" = "#b8d000")
#'
#' gss_data1 <- dplyr::filter(gss_data, year == "2016",
#'                            conlegis %in% c("A GREAT DEAL", "ONLY SOME", "HARDLY ANY"))
#' my_results <- freq_prop_test(gss_data1, "conlegis", "region", weight = "wtssall")
#' my_chart_data <- tbl_chart(gss_data1, "conlegis", "region", weight = "wtssall")
#'
#' my_chart_data$conlegis <- forcats::fct_relevel(my_chart_data$conlegis,
#'                                             "A GREAT DEAL",
#'                                             "ONLY SOME",
#'                                             "HARDLY ANY")
#'
#' #Trial and error is needed to apply the right values for space_between and space_label
#' #to get the positioning of the markers correctly.
#' my_sig_data <- tbl_sig(my_results, "region", space_label = 0.2, space_between = 0.1)
#'
#' #Setting up a chart
#' library(ggplot2)
#' (p <- ggplot() +
#' 		geom_col(data = my_chart_data, aes(x = conlegis, fill = region, y = prop)) +
#' 		geom_text(data = my_chart_data, aes(x = conlegis,
#' 		                                    y = prop,
#' 		                                    label = scales::percent(round(prop, 2))),
#' 		                                    hjust = -0.2) +
#' 		coord_flip() +
#' 		facet_wrap(~ region) +
#' 		scale_fill_manual(values = colour_vec) + scale_colour_manual(values = colour_vec) +
#' 		scale_y_continuous(limits = c(0, 1.5), labels = scales::percent)
#' )
#'
#' p + geom_sigmark(my_sig_data)
#'
#' ### Means:
#' colour_vec <- c("LT HIGH SCHOOL" = "#edc951",
#'                 "HIGH SCHOOL" = "#eb6841",
#'                 "JUNIOR COLLEGE" = "#cc2a36",
#'                 "BACHELOR" = "#4f372d",
#'                 "GRADUATE" = "#00a0b0")
#'
#' gss_data1 <- dplyr::filter(gss_data, year == "2016", coninc > 0)
#' my_results <- freq_t_test(gss_data1, "coninc", "degree", weight = "wtssall")
#' my_chart_data <- tbl_chart(gss_data1, "coninc", "degree", weight = "wtssall")
#'
#' #Trial and error is needed to apply the right values for space_between and space_label
#' #to get the positioning of the markers correctly.
#' my_sig_data <- tbl_sig(my_results, "degree", space_label = 5000, space_between = 2100)
#'
#' #Setting up a chart
#' library(ggplot2)
#' (p <- ggplot() +
#' 		geom_col(data = my_chart_data, aes(x = degree, y = wtd.mean, fill = degree)) +
#' 		geom_text(data = my_chart_data, aes(x = degree,
#' 		                                    y = wtd.mean,
#' 		                                    label = scales::dollar(round(wtd.mean, 0))),
#' 		                                    vjust = -0.2) +
#' 		scale_fill_manual(values = colour_vec) + scale_colour_manual(values = colour_vec) +
#' 		scale_y_continuous(limits = c(0, 100000), labels = scales::dollar)
#' )
#'
#'
#' p + geom_sigmark(my_sig_data, x = "degree")

geom_sigmark <- function(tbl_sig, x = "level", y = "pos", group = NULL, colour = "sign", icon = "full triangle up", size = 5) {
	if (icon == "full triangle up") {
		icon <- base::sprintf("\u25b2")
	} else if (icon == "full triangle down") {
		icon <- base::sprintf("\u25bc")
	} else if (icon == "clear triangle up") {
		icon <- base::sprintf("\u25b3")
	} else if (icon == "clear triangle down") {
		icon <- base::sprintf("\u25bd")
	} else if (icon == "arrow up") {
		icon <- base::sprintf("\u2191")
	} else if (icon == "arrow down") {
		icon <- base::sprintf("\u2193")
	} else if (icon == "finger up") {
		icon <- base::sprintf("\u261d")
	} else if (icon == "finger down") {
		icon <- base::sprintf("\u261f")
	} else if (icon == "full star") {
		icon <- base::sprintf("\u2605")
	} else if (icon == "clear star") {
		icon <- base::sprintf("\u2606")
	} else if (icon == "checkmark") {
		icon <- base::sprintf("\u2714")
	} else if (icon == "asterisk") {
		icon <- base::sprintf("\u2731")
	} else if (icon == "heart") {
		icon <- base::sprintf("\u2764")
	}

	geom_sigmark <- base::list(
		ggplot2::geom_point(data = tbl_sig, shape = icon, size = size, ggplot2::aes_string(x = x, y = y, group = group, colour = colour)),
		ggplot2::scale_shape_manual(values = icon),
		ggplot2::guides(fill = ggplot2::guide_legend(override.aes = base::list(shape = NA), order = 1),
										shape = ggplot2::guide_legend(order = 9))
	)
	return(geom_sigmark)
}