plot_histogram: A function to create standardized CCMH histogram plot's
In jpetrovich02/CCMHr: CCMH Data Cleaning

plot_histogram

R Documentation

A function to create standardized CCMH histogram plot's

Description

Creates standardized CCMH histogram plot's using ggplot2.

Usage

plot_histogram(
  data,
  x.var,
  group.var = "",
  color = c("#666666", "#1B9E77", "#E6AB02", "#D95F02", "#6db6ff", "#b66dff", "#ff6db6",
    "#920000"),
  y.axis.type = "count",
  hist.position = "identity",
  save = FALSE,
  path = "plot.png",
  plot.width = 15.24,
  plot.height = 12.7,
  plot.units = "cm",
  plot.dpi = 320,
  plot.device = NULL,
  plot.title = NULL,
  x.title = NULL,
  y.title = NULL,
  plot.title.size = 20,
  axis.title.size = 16,
  axis.label.size = 14,
  text.font = "Avenir",
  y.label.type = "numeric",
  y.min = NULL,
  y.max = NULL,
  y.breaks = NULL,
  x.label.type = "numeric",
  x.min = NULL,
  x.max = NULL,
  x.breaks = NULL,
  caption = FALSE,
  caption.size = 12,
  legend.position = "none",
  legend.order.manual = NULL,
  legend.title = NULL,
  legend.title.size = 16,
  legend.label.size = 14,
  alpha = 1,
  bin.width = NULL,
  y.grid.major = FALSE,
  y.grid.major.color = "#d3d3d3",
  y.grid.major.size = 0.5,
  y.grid.major.linetype = 1,
  x.grid.major = FALSE,
  x.grid.major.color = "#d3d3d3",
  x.grid.major.size = 0.5,
  x.grid.major.linetype = 1,
  y.axis.line = TRUE,
  x.axis.line = TRUE,
  remove.axis.ticks = FALSE,
  plot.element1 = NULL,
  plot.element2 = NULL,
  plot.element3 = NULL,
  plot.element4 = NULL,
  plot.element5 = NULL,
  plot.element6 = NULL,
  plot.element7 = NULL,
  plot.element8 = NULL,
  plot.element9 = NULL
)

histogram_plot(
  data,
  x.var,
  group.var = "",
  color = c("#666666", "#1B9E77", "#E6AB02", "#D95F02", "#6db6ff", "#b66dff", "#ff6db6",
    "#920000"),
  y.axis.type = "count",
  hist.position = "identity",
  save = FALSE,
  path = "plot.png",
  plot.width = 15.24,
  plot.height = 12.7,
  plot.units = "cm",
  plot.dpi = 320,
  plot.device = NULL,
  plot.title = NULL,
  x.title = NULL,
  y.title = NULL,
  plot.title.size = 20,
  axis.title.size = 16,
  axis.label.size = 14,
  text.font = "Avenir",
  y.label.type = "numeric",
  y.min = NULL,
  y.max = NULL,
  y.breaks = NULL,
  x.label.type = "numeric",
  x.min = NULL,
  x.max = NULL,
  x.breaks = NULL,
  caption = FALSE,
  caption.size = 12,
  legend.position = "none",
  legend.order.manual = NULL,
  legend.title = NULL,
  legend.title.size = 16,
  legend.label.size = 14,
  alpha = 1,
  bin.width = NULL,
  y.grid.major = FALSE,
  y.grid.major.color = "#d3d3d3",
  y.grid.major.size = 0.5,
  y.grid.major.linetype = 1,
  x.grid.major = FALSE,
  x.grid.major.color = "#d3d3d3",
  x.grid.major.size = 0.5,
  x.grid.major.linetype = 1,
  y.axis.line = TRUE,
  x.axis.line = TRUE,
  remove.axis.ticks = FALSE,
  plot.element1 = NULL,
  plot.element2 = NULL,
  plot.element3 = NULL,
  plot.element4 = NULL,
  plot.element5 = NULL,
  plot.element6 = NULL,
  plot.element7 = NULL,
  plot.element8 = NULL,
  plot.element9 = NULL
)

Arguments

`data`	A data file containing all variables that will be used in the plot
`x.var`	A quoted string or unquoted characters to indicate the variable that will be plotted on the x-axis. The variable class must be a character or factor.
`group.var`	A quoted string to indicate the variable that will used to specify grouping. By default, `""`.
`color`	A hex code or list of hex codes that indicates the color based on grouping. See Note 1 for more details. By default, `c('#E6AB02', '#1B9E77', '#666666', '#D95F02', '#6db6ff', '#b66dff', '#ff6db6', '#920000')`.
`y.axis.type`	A quoted string to indicate the type of information displayed on the y axis. Options include `count`, `density`, and `relative_freq`. By default, `count`.
`hist.position`	A quoted string to indicate the histogram position adjustment. By default, `identity`.
`save`	A logical statement indicates whether the plot should be saved as a file under a local folder. If false, the plot will be returned as an object. By default, `FALSE`.
`path`	A quoted string to indicate the file's pathway and name if `save = TRUE`. By default, `"plot.png"`.
`plot.width`	A numeric value to indicate the plot's width. By default, `15.24`.
`plot.height`	A numeric value to indicate the plot's height. By default, `12.7`.
`plot.units`	A quoted string to indicate the plot's width and height size units. Options include `⁠in⁠`, `cm`, `mm`, and `px`. By default, `cm`.
`plot.dpi`	A numeric value to indicate the plot's image resolution. By default, `320`.
`plot.device`	A quoted string or function to indicate the plot's device. By default, `NULL`.
`plot.title`	A quoted string to indicate the title of the plot. By default, `NULL`.
`x.title`	A quoted string to indicate the x axis title. By default, `NULL`.
`y.title`	A quoted string to indicate the y axis title. By default, `NULL`.
`plot.title.size`	A numeric value to indicate the plot title text size. By default, `20`.
`axis.title.size`	A numeric value to indicate the axis title text size. By default, `16`.
`axis.label.size`	A numeric value to indicate the axis labels text size. By default, `14`.
`text.font`	A quoted string to indicate the plot's text font. By default, `Avenir`.
`y.label.type`	A quoted string or list to customize the y axis labels. Options include `"numeric"`, `"percent"`, `"comma"`, or `⁠"sci⁠`. By default, `numeric`.
`y.min`	A numeric value to indicate the minimum number presented on the y axis. By default, `NULL`.
`y.max`	A numeric value to indicate the maximum number presented on the y axis. By default, `NULL`.
`y.breaks`	Numeric values or a sequence that indicates breaks on the y axis. By default, `NULL`.
`x.label.type`	A quoted string or list to customize the x axis labels. Options include `"numeric"`, `"percent"`, `"comma"`, `⁠"sci⁠`, or `"dollar"` . By default, `numeric`.
`x.min`	A numeric value to indicate the minimum number presented on the x axis. By default, `NULL`.
`x.max`	A numeric value to indicate the maximum number presented on the x axis. By default, `NULL`.
`x.breaks`	Numeric values or a sequence that indicates breaks on the x axis. By default, `NULL`.
`caption`	A logical statement to indicate whether the CCMH caption should be included in the plot. By default, `FALSE`.
`caption.size`	A numeric value to indicate the caption text size. By default, `12`.
`legend.position`	A quoted string or numeric vector to indicate the location of the legend. Options include `"left"`,`"top"`, `"right"`, `"bottom"`, `"none"`, or numeric vector c(x,y). By default, `"none"`.
`legend.order.manual`	A list of quoted strings to indicate the order of the legend. By default, `NULL`.
`legend.title`	A quoted string to indicate the legend title. By default, `NULL`.
`legend.title.size`	A numeric value to indicate the legend title text size. By default, `16`.
`legend.label.size`	A numeric value to indicate the legend label text size. By default, `14`.
`alpha`	A numeric value to indicate the histogram bars transparency. Values may range between 0 to 1. By default, `1`.
`bin.width`	A numeric value to indicate the width of the bins. By default, `NULL`.
`y.grid.major`	A logical statement to indicate if the y axis major grid lines should be added to the plot. By default, `FALSE`,
`y.grid.major.color`	A hex code that indicates the color of the y axis major grid lines. By default, `"#d3d3d3"` or a shade of light grey.
`y.grid.major.size`	A numeric value to indicate the thickness of the y axis major grid lines. By default, `0.5`.
`y.grid.major.linetype`	A numeric value to indicate the line type of the y axis major grid. By default, `1`.
`x.grid.major`	A logical statement to indicate if the y axis major grid lines should be added to the plot. By default, `FALSE`,
`x.grid.major.color`	A hex code that indicates the color of the y axis major grid lines. By default, `"#d3d3d3"` or a shade of light grey.
`x.grid.major.size`	A numeric value to indicate the thickness of the y axis major grid lines. By default, `0.5`.
`x.grid.major.linetype`	A numeric value to indicate the line type of the y axis major grid. By default, `1`.
`y.axis.line`	A logical statement to indicate if the y axis line should be included. By default, `TRUE`.
`x.axis.line`	A logical statement to indicate if the x axis line should be included. By default, `TRUE`.
`remove.axis.ticks`	A logical statement to indicate if the axis ticks should be excluded. By default, `FALSE`.
`plot.element1`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element2`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element3`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element4`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element5`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element6`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element7`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element8`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.
`plot.element9`	A ggplot plot function and arguments needed for the plot and specified as an object. By default, `NULL`.

Value

A histogram plot returned as a object or saved under a local file.

Note

Note 1. The argument color specifies the color of items within the grouped variable. For example, the group variable items could be the name of automobile companies (i.e., Ford, Dodge, BMV). You can specify color randomly for each company using this list: c("#21501b", "#c51329", "#074e67"). Or you can specify color directly to each specific company using this list: c("Ford" = "#21501b", "Dodge" = "#c51329", "BMV" = "#074e67"). Default colors are color blind safe.

The plot.element arguments specify additional ggplot2 graphical element(s) needed to complete a specific task, but are not specified as an argument in the hist_plot function. For example, the axis label text will always be black unless specified in one of the plot.element arguments. To change the axis label text color in one of the plot.element arguments, you would first create an object to represent graphing element (e.g., green.axis.text <- ggplot2::theme(axis.text = ggplot2::element_text(color = "green"))). Then the object would be added to one of the plot.element arguments (e.g., plot.element01 = green.axis.text).