% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/split_var.R
\name{split_var}
\alias{split_var}
\alias{split_var_if}
\title{Split numeric variables into smaller groups}
\usage{
split_var(
  x,
  ...,
  n,
  as.num = FALSE,
  val.labels = NULL,
  var.label = NULL,
  inclusive = FALSE,
  append = TRUE,
  suffix = "_g"
)

split_var_if(
  x,
  predicate,
  n,
  as.num = FALSE,
  val.labels = NULL,
  var.label = NULL,
  inclusive = FALSE,
  append = TRUE,
  suffix = "_g"
)
}
\arguments{
\item{x}{A vector or data frame.}

\item{...}{Optional, unquoted names of variables that should be selected for
further processing. Required, if \code{x} is a data frame (and no
vector) and only selected variables from \code{x} should be processed.
You may also use functions like \code{:} or tidyselect's
select-helpers.
See 'Examples' or \href{../doc/design_philosophy.html}{package-vignette}.}

\item{n}{The new number of groups that \code{x} should be split into.}

\item{as.num}{Logical, if \code{TRUE}, return value will be numeric, not a factor.}

\item{val.labels}{Optional character vector, to set value label attributes
of recoded variable (see vignette \href{https://cran.r-project.org/package=sjlabelled/vignettes/intro_sjlabelled.html}{Labelled Data and the sjlabelled-Package}).
If \code{NULL} (default), no value labels will be set. Value labels
can also be directly defined in the \code{rec}-syntax, see
'Details'.}

\item{var.label}{Optional string, to set variable label attribute for the
returned variable (see vignette \href{https://cran.r-project.org/package=sjlabelled/vignettes/intro_sjlabelled.html}{Labelled Data and the sjlabelled-Package}).
If \code{NULL} (default), variable label attribute of \code{x} will
be used (if present). If empty, variable label attributes will be removed.}

\item{inclusive}{Logical; if \code{TRUE}, cut point value are included in
the preceding group. This may be necessary if cutting a vector into
groups does not define proper ("equal sized") group sizes.
See 'Note' and 'Examples'.}

\item{append}{Logical, if \code{TRUE} (the default) and \code{x} is a data frame,
\code{x} including the new variables as additional columns is returned;
if \code{FALSE}, only the new variables are returned.}

\item{suffix}{Indicates which suffix will be added to each dummy variable.
Use \code{"numeric"} to number dummy variables, e.g. \emph{x_1},
\emph{x_2}, \emph{x_3} etc. Use \code{"label"} to add value label,
e.g. \emph{x_low}, \emph{x_mid}, \emph{x_high}. May be abbreviated.}

\item{predicate}{A predicate function to be applied to the columns. The
variables for which \code{predicate} returns \code{TRUE} are selected.}
}
\value{
A grouped variable with equal sized groups. If \code{x} is a data frame,
  for \code{append = TRUE}, \code{x} including the grouped variables as new
  columns is returned; if \code{append = FALSE}, only the grouped variables
  will be returned. If \code{append = TRUE} and \code{suffix = ""},
  recoded variables will replace (overwrite) existing variables.
}
\description{
Recode numeric variables into equal sized groups, i.e. a
  variable is cut into a smaller number of groups at specific cut points.
  \code{split_var_if()} is a scoped variant of \code{split_var()}, where
  transformation will be applied only to those variables that match the
  logical condition of \code{predicate}.
}
\details{
\code{split_var()} splits a variable into equal sized groups, where
  the amount of groups depends on the \code{n}-argument. Thus, this
  functions \code{\link{cut}s} a variable into groups at the specified
  \code{\link[stats]{quantile}s}.
  \cr \cr
  By contrast, \code{\link{group_var}} recodes a variable into groups, where
  groups have the same value range (e.g., from 1-5, 6-10, 11-15 etc.).
  \cr \cr
  \code{split_var()} also works on grouped data frames
  (see \code{\link[dplyr]{group_by}}). In this case, splitting is applied to
  the subsets of variables in \code{x}. See 'Examples'.
}
\note{
In case a vector has only few number of unique values, splitting into
  equal sized groups may fail. In this case, use the \code{inclusive}-argument
  to shift a value at the cut point into the lower, preceeding group to
  get equal sized groups. See 'Examples'.
}
\examples{
data(efc)
# non-grouped
table(efc$neg_c_7)

# split into 3 groups
table(split_var(efc$neg_c_7, n = 3))

# split multiple variables into 3 groups
split_var(efc, neg_c_7, pos_v_4, e17age, n = 3, append = FALSE)
frq(split_var(efc, neg_c_7, pos_v_4, e17age, n = 3, append = FALSE))

# original
table(efc$e42dep)

# two groups, non-inclusive cut-point
# vector split leads to unequal group sizes
table(split_var(efc$e42dep, n = 2))

# two groups, inclusive cut-point
# group sizes are equal
table(split_var(efc$e42dep, n = 2, inclusive = TRUE))

# Unlike dplyr's ntile(), split_var() never splits a value
# into two different categories, i.e. you always get a clean
# separation of original categories
library(dplyr)

x <- dplyr::ntile(efc$neg_c_7, n = 3)
table(efc$neg_c_7, x)

x <- split_var(efc$neg_c_7, n = 3)
table(efc$neg_c_7, x)

# works also with gouped data frames
mtcars \%>\%
  split_var(disp, n = 3, append = FALSE) \%>\%
  table()

mtcars \%>\%
  group_by(cyl) \%>\%
  split_var(disp, n = 3, append = FALSE) \%>\%
  table()
}
\seealso{
\code{\link{group_var}} to group variables into equal ranged groups,
         or \code{\link{rec}} to recode variables.
}
