% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/derive.R
\name{derive_cut}
\alias{derive_cut}
\title{Cut a continuous UKB variable into quantile-based or custom groups}
\usage{
derive_cut(data, col, n, breaks = NULL, labels = NULL, name = NULL)
}
\arguments{
\item{data}{(data.frame or data.table) UKB data.}

\item{col}{(character) Name of the source numeric column.}

\item{n}{(integer) Number of groups. Any integer \code{>= 2} is accepted.
Commonly used values are \code{2}, \code{3}, \code{4}, \code{5}.}

\item{breaks}{(numeric vector or NULL) Interior cut points; length must
equal \code{n - 1}. When \code{NULL} (default), quantile-based equal-
frequency boundaries are computed automatically.}

\item{labels}{(character vector or NULL) Group labels of length \code{n}.
Defaults to \code{"Q1"}, \code{"Q2"}, \ldots, \code{"Qn"}.}

\item{name}{(character or NULL) Name for the new column. Defaults to
\code{"{col}_bi"} / \code{"{col}_tri"} / \code{"{col}_quad"} /
\code{"{col}_quin"} for \code{n} = 2 / 3 / 4 / 5; other values of
\code{n} produce \code{"{col}_g{n}"}.}
}
\value{
The input \code{data} with one new factor column appended. Always
returns a \code{data.table}.
}
\description{
Creates a new factor column by binning a continuous variable into \code{n}
groups. When \code{breaks} is omitted, group boundaries are derived from
quantiles of the observed data (equal-frequency binning). When
\code{breaks} is supplied, those values are used as interior cut points.
}
\details{
Before binning, a numeric summary (mean, median, SD, Q1, Q3, missing rate)
is printed for the source column. After binning, the group distribution is
printed via an internal summary helper.

Only one column can be processed per call; loop over columns explicitly
when binning multiple variables.

\strong{data.table pass-by-reference}: when the input is a
\code{data.table}, the new column is added in-place. Pass
\code{data.table::copy(data)} to preserve the original.
}
\examples{
dt <- ops_toy(n = 100)
derive_cut(dt, col = "p21001_i0", n = 3)

# Custom breaks and labels
derive_cut(dt, col = "p21001_i0", n = 3,
           breaks = c(25, 30),
           labels = c("<25", "25-30", "30+"),
           name   = "bmi_group")
}
