plot_freq: Plot frequencies for a variable (histogram without binning)

In statuser: Statistical Tools Designed for End Users

Plot frequencies for a variable (histogram without binning)

Description

Creates a frequency plot showing the frequency of every observed value, optionaly by group. Most frequent values are labeled by default.

Usage

plot_freq(
  formula,
  y2 = NULL,
  data = NULL,
  freq = TRUE,
  order = NULL,
  col = "dodgerblue",
  lwd = 9,
  width = NULL,
  value.labels = "auto",
  ticks.max = 30,
  show.x.value = "auto",
  show.legend = TRUE,
  legend.title = NULL,
  col.text = NULL,
  ...
)

Arguments

formula	Two possible uses (similar to t.test()): Single Variable (possibly by subgroup): plot_freq(y) or plot_freq(y~x) Contrast Two Variables: plot_freq(y1, y2)
y2	optional second variable when contrasting two variables plot_freq(y1,y2)
data	An optional data frame containing the variables in the formula.
freq	Logical. If TRUE (default), displays frequencies. If FALSE, displays percentages.
order	Controls the order in which groups appear in the plot and legend. Use -1 to reverse the default order. Alternatively, provide a vector specifying the exact order (e.g., c("B", "A", "C")). If NULL (default), groups are ordered by their factor levels (if the grouping variable is a factor) or sorted alphabetically/numerically. Only applies when using grouped plots or comparing two variables.
col	Color for the bars.
lwd	Line width for the frequency bars. Default is 9.
width	Numeric. Width of the frequency bars. If NULL (default), width is automatically calculated based on the spacing between values.
value.labels	Controls value labeling. If numeric, shows labels for the value.labels highest-frequency values (including ties). Use -1 or "all" to show all labels and 0 to show none. Use "auto" to label all values when there are 30 or fewer unique values; otherwise label the single most frequent value. For backward compatibility, TRUE is treated as -1 and FALSE as 0.
ticks.max	Integer. Maximum number of unique x values to label on the x-axis. If there are more than ticks.max unique values, pretty() ticks are used instead of labeling every value.
show.x.value	Either "auto" (default), TRUE, or FALSE. If enabled, draws a small x=<value> label just above each frequency value label. When "auto", x labels are shown only when plot_freq is not already labeling all x values on the x-axis.
show.legend	Logical. If TRUE (default), displays a legend when group is specified. If FALSE, no legend is shown.
legend.title	Character string. Title for the legend when group is specified. If NULL (default), no title is shown.
col.text	Color for the value labels. If not specified, uses col for non-grouped plots or group colors for grouped plots.
...	Pass on any argument accepted by plot() e.g., xlab='x-axis' , main='Distribution of X'

Details

This function creates a frequency plot where each observed value is shown with its frequency. Unlike a standard histogram, there is no binning, unlike a barplot, non-observed values of the variable are shown with 0 frequency instead of skipped.

Value

Invisibly returns a data frame with values and their frequencies.

Examples

# Simple example
x <- c(1, 1, 2, 2, 2, 5, 5)
plot_freq(x)

# Pass on some common \code{plot()} arguments
plot_freq(x, col = "steelblue", xlab = "Value", ylab = "Frequency",ylim=c(0,7))

# Add to an existing plot
plot_freq(x, col = "dodgerblue")


# Compare two vectors
y1 <- c(1, 1, 2, 2, 2, 5, 5)
y2 <- c(1, 2, 2, 3, 3, 3)
plot_freq(y1, y2)

# Using a data frame with grouping
df <- data.frame(value = c(1, 1, 2, 2, 2, 5, 5), group = c("A", "A", "A", "B", "B", "A", "B"))
plot_freq(value ~ 1, data = df)  # single variable
plot_freq(value ~ group, data = df)  # with grouping

# Control group order in legend and plot
plot_freq(value ~ group, data = df, order = c("B", "A"))  # B first, then A
plot_freq(value ~ group, data = df, order = -1)  # Reverse default order

statuser documentation built on April 25, 2026, 5:06 p.m.