% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_freq.R
\name{plot_freq}
\alias{plot_freq}
\title{Plot frequencies for a variable (histogram without binning)}
\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{
\item{formula}{Two possible uses (similar to \code{t.test()}):
\itemize{
  \item {Single Variable (possibly by subgroup)}: \code{plot_freq(y)} or \code{plot_freq(y~x)}
  \item {Contrast Two Variables}: \code{plot_freq(y1, y2)}
}}

\item{y2}{optional second variable when contrasting two variables \code{plot_freq(y1,y2)}}

\item{data}{An optional data frame containing the variables in the formula.}

\item{freq}{Logical. If TRUE (default), displays frequencies. If FALSE, displays percentages.}

\item{order}{Controls the order in which groups appear in the plot and legend. 
Use \code{-1} to reverse the default order. Alternatively, provide a vector specifying
the exact order (e.g., \code{c("B", "A", "C")}). If \code{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.}

\item{col}{Color for the bars.}

\item{lwd}{Line width for the frequency bars. Default is 9.}

\item{width}{Numeric. Width of the frequency bars. If NULL (default), width is automatically calculated based on the spacing between values.}

\item{value.labels}{Controls value labeling. If numeric, shows labels for the \code{value.labels}
highest-frequency values (including ties). Use \code{-1} or \code{"all"} to show all labels and
\code{0} to show none. Use \code{"auto"} to label all values when there are 30 or fewer
unique values; otherwise label the single most frequent value. For backward compatibility, \code{TRUE}
is treated as \code{-1} and \code{FALSE} as \code{0}.}

\item{ticks.max}{Integer. Maximum number of unique x values to label on the x-axis. If there are more
than \code{ticks.max} unique values, \code{pretty()} ticks are used instead of labeling every value.}

\item{show.x.value}{Either \code{"auto"} (default), \code{TRUE}, or \code{FALSE}. If enabled, draws a
small \code{x=<value>} label just above each frequency value label. When \code{"auto"}, x labels are
shown only when plot_freq is not already labeling all x values on the x-axis.}

\item{show.legend}{Logical. If TRUE (default), displays a legend when \code{group} is specified. If FALSE, no legend is shown.}

\item{legend.title}{Character string. Title for the legend when \code{group} is specified. If NULL (default), no title is shown.}

\item{col.text}{Color for the value labels. If not specified, uses \code{col} for non-grouped plots or group colors for grouped plots.}

\item{...}{Pass on any argument accepted by \code{plot()} e.g., \code{xlab='x-axis'} , \code{main='Distribution of X'}}
}
\value{
Invisibly returns a data frame with values and their frequencies.
}
\description{
Creates a frequency plot showing the frequency of every observed value, optionally by group. 
Most frequent values are labeled by default.
}
\details{
This function creates a frequency plot where each observed value is shown
with its frequency. Unlike a histogram (no binning) and unlike a barplot
(which omits unobserved levels), unobserved values are shown at frequency 0.
}
\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

}
