% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/collapse_levels.R
\name{collapse_levels}
\alias{collapse_levels}
\title{Collapse the levels of a dataset}
\usage{
collapse_levels(x, freq = "Freq", ...)
}
\arguments{
\item{x}{The dataset to be collapsed.}

\item{freq}{Supply only if your data is in frequency form AND your frequency
column differs in name from the default ("Freq").}

\item{\dots}{A collection of one or more assignments of dataset variables to
a list of levels in the format
\code{new_level = c("old_level_1", "old_level_2", ..., "old_level_n")}.}
}
\value{
The collapsed dataset in its original form (i.e., the initial form of
\code{x}).
}
\description{
Collapses the levels of a dataset (of any form) into those specified. May
also be used to re-name levels. Ensure argument \code{freq} is supplied
should your data be in frequency form (and the frequency column differs in
name from default, "Freq").
}
\details{
First converts the object \code{x} into a frequency form data frame. Then,
\code{\link[forcats]{fct_collapse}} is used to collapse variable levels.
Next, duplicate rows (an artefact of collapsing) are aggregated via
\code{\link[dplyr]{summarise}}. Last, the frequency form data frame is
converted back into the initial form of object \code{x}.

The exceptions to this are objects in case form, which are passed directly
to \code{\link[forcats]{fct_collapse}} (and duplicate rows are not aggregated).
}
\examples{
data("HairEyeColor") # Table form data
str(HairEyeColor)

collapse_levels(
  HairEyeColor,                 # Dataset
  Hair = list(                  # List of arguments for first variable
    Dark = c("Black", "Brown"), # Collapse "Black" and "Brown" -> "Dark"
    Light = c("Blond", "Red")   # Collapse "Blond" and "Red" -> "Light"
  ),
  Eye = list(                   # List of arguments for second variable
    Common = c("Brown"),        # Collapse (rename) "Brown" -> "Common"
    Uncommon = c("Blue", "Green", "Hazel")
  )
) |> str()

# To illustrate `freq` argument usage, convert Hoyt dataset to frequency form 
# (ff) and then rename frequency column to "n"

data("Hoyt", package = "vcdExtra")
ff_Hoyt <- as_freqform(Hoyt)
names(ff_Hoyt)[length(ff_Hoyt)] <- "n"
str(ff_Hoyt)

collapse_levels(
  ff_Hoyt,
  
  # Ensure to supply if data is in frequency form and frequency column name
  # differs from "Freq"
  freq = "n",
  
  Occupation = list(
    High = c(1, 2),
    Middle = 3,
    Low = 4,
    VeryLow = c(5, 6, 7)
  )
) |> str()


}
\seealso{
\code{\link[forcats]{fct_collapse}}, \code{\link{collapse.table}}

Tidy conversion functions:
\code{link{as_table}}, \code{link{as_freqform}}, \code{link{as_caseform}},
\code{link{as_matrix}}, \code{link{as_array}},
}
\author{
Gavin M. Klorfine
}
