% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/varlist.R
\name{varlist}
\alias{varlist}
\alias{vl}
\title{Generate a comprehensive summary of the variables}
\usage{
varlist(
  x,
  ...,
  values = FALSE,
  tbl = FALSE,
  include_na = FALSE,
  factor_levels = c("observed", "all")
)

vl(
  x,
  ...,
  values = FALSE,
  tbl = FALSE,
  include_na = FALSE,
  factor_levels = c("observed", "all")
)
}
\arguments{
\item{x}{A data frame, or a transformation of one.}

\item{...}{Optional tidyselect-style column selectors (e.g.
\code{starts_with("var")}, \code{where(is.numeric)}, etc.). Columns can be selected
or reordered, but renaming selections is not supported.}

\item{values}{Logical. If \code{FALSE} (the default), displays a compact summary
of the variable's values. For numeric, character, date/time, labelled, and
factor variables, all unique non-missing values are shown when there are
at most four; otherwise the first three values, an ellipsis (\code{...}), and
the last value are shown. Values are sorted when appropriate (e.g.,
numeric, character, date).
For factors, \code{factor_levels} controls whether observed or all declared
levels are shown; level order is preserved.
For labelled variables, prefixed labels are displayed via
\code{labelled::to_factor(levels = "prefixed")}.
If \code{TRUE}, all unique non-missing values are displayed.}

\item{tbl}{Logical. If \code{FALSE} (the default), opens the summary in the Viewer
if the session is interactive. If \code{TRUE}, returns a tibble.}

\item{include_na}{Logical. If \code{TRUE}, unique missing value markers
(\verb{<NA>}, \verb{<NaN>}) are explicitly appended at the end of the \code{Values}
summary when present in the variable. This applies to all variable types.
Literal strings \code{"NA"}, \code{"NaN"}, and \code{""} are quoted to distinguish them
from missing markers. If \code{FALSE} (the default), missing values are omitted
from \code{Values} but still counted in the \code{NAs} column.}

\item{factor_levels}{Character. Controls how factor values are displayed
in \code{Values}. \code{"observed"} (the default; \code{\link[=code_book]{code_book()}} uses \code{"all"})
shows only levels present in the data, preserving factor level order.
\code{"all"} shows all declared levels, including unused levels.}
}
\value{
A tibble with one row per selected variable, containing the following
columns:
\itemize{
\item \code{Variable}: variable names
\item \code{Label}: variable labels (if available via the \code{label} attribute)
\item \code{Values}: a summary of the variable's values, depending on the \code{values}
and \code{include_na} arguments. If \code{values = FALSE}, a compact summary is
shown: all unique values when there are at most four, otherwise
3 + ... + last. If \code{values = TRUE}, all unique non-missing values are
displayed. For labelled variables, \strong{prefixed labels} are displayed using
\code{labelled::to_factor(levels = "prefixed")}.
For factors, levels are displayed according to \code{factor_levels}.
Matrix and array columns are summarized by their dimensions.
Missing value markers (\verb{<NA>}, \verb{<NaN>}) are optionally appended at the
end (controlled via \code{include_na}). Literal strings \code{"NA"}, \code{"NaN"}, and
\code{""} are quoted to distinguish them from missing markers.
\item \code{Class}: the class of each variable (possibly multiple, e.g.
\verb{"labelled", "numeric"})
\item \code{N_distinct}: number of distinct non-missing values
\item \code{N_valid}: number of non-missing observations
\item \code{NAs}: number of missing observations
}

If \code{tbl = TRUE}, the tibble is returned. If \code{tbl = FALSE} and the session is
interactive, the summary is displayed in the Viewer pane and the function
returns invisibly. In non-interactive sessions, a message is displayed and
the function returns invisibly.
}
\description{
\code{varlist()} lists the variables of a data frame and extracts essential
metadata, including variable names, labels, summary values, classes, number
of distinct values, number of valid (non-missing) observations, and number
of missing values.

\code{vl()} is a convenient shorthand for \code{varlist()} that offers identical
functionality with a shorter name.
}
\details{
The function can also apply tidyselect-style variable selectors to select or
reorder columns dynamically.

If used interactively (e.g. in RStudio or Positron), the summary is
displayed in the Viewer pane with a contextual title like \code{vl: sochealth}.
If the data frame has been transformed or subsetted, the title will display
an asterisk (\code{*}), e.g. \verb{vl: sochealth*}. Anonymous or ambiguous calls use
\verb{vl: <data>}.

For factor variables, \code{varlist()} defaults to displaying only the levels
observed in the data (\code{factor_levels = "observed"}) — a reflection of what
is actually present. By contrast, \code{\link[=code_book]{code_book()}} defaults to \code{"all"} to
document the declared schema, including unused levels. Pass \code{factor_levels}
explicitly to override either default.
}
\examples{
varlist(sochealth, tbl = TRUE)
sochealth |> varlist(tbl = TRUE)
varlist(sochealth, where(is.numeric), values = TRUE, tbl = TRUE)
varlist(
  sochealth,
  starts_with("bmi"),
  values = TRUE,
  include_na = TRUE,
  tbl = TRUE
)

df <- data.frame(
  group = factor(c("A", "B", NA), levels = c("A", "B", "C"))
)
varlist(
  df,
  values = TRUE,
  include_na = TRUE,
  factor_levels = "all",
  tbl = TRUE
)

vl(sochealth, tbl = TRUE)
sochealth |> vl(tbl = TRUE)
vl(sochealth, starts_with("bmi"), tbl = TRUE)
vl(sochealth, where(is.numeric), values = TRUE, tbl = TRUE)
}
