1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/pivot-long.R
3\name{pivot_longer}
4\alias{pivot_longer}
5\title{Pivot data from wide to long}
6\usage{
7pivot_longer(
8  data,
9  cols,
10  names_to = "name",
11  names_prefix = NULL,
12  names_sep = NULL,
13  names_pattern = NULL,
14  names_ptypes = list(),
15  names_transform = list(),
16  names_repair = "check_unique",
17  values_to = "value",
18  values_drop_na = FALSE,
19  values_ptypes = list(),
20  values_transform = list(),
21  ...
22)
23}
24\arguments{
25\item{data}{A data frame to pivot.}
26
27\item{cols}{<\code{\link[=tidyr_tidy_select]{tidy-select}}> Columns to pivot into
28longer format.}
29
30\item{names_to}{A string specifying the name of the column to create
31from the data stored in the column names of \code{data}.
32
33Can be a character vector, creating multiple columns, if \code{names_sep}
34or \code{names_pattern} is provided. In this case, there are two special
35values you can take advantage of:
36\itemize{
37\item \code{NA} will discard that component of the name.
38\item \code{.value} indicates that component of the name defines the name of the
39column containing the cell values, overriding \code{values_to}.
40}}
41
42\item{names_prefix}{A regular expression used to remove matching text
43from the start of each variable name.}
44
45\item{names_sep, names_pattern}{If \code{names_to} contains multiple values,
46these arguments control how the column name is broken up.
47
48\code{names_sep} takes the same specification as \code{\link[=separate]{separate()}}, and can either
49be a numeric vector (specifying positions to break on), or a single string
50(specifying a regular expression to split on).
51
52\code{names_pattern} takes the same specification as \code{\link[=extract]{extract()}}, a regular
53expression containing matching groups (\verb{()}).
54
55If these arguments do not give you enough control, use
56\code{pivot_longer_spec()} to create a spec object and process manually as
57needed.}
58
59\item{names_ptypes, values_ptypes}{A list of column name-prototype pairs.
60A prototype (or ptype for short) is a zero-length vector (like \code{integer()}
61or \code{numeric()}) that defines the type, class, and attributes of a vector.
62Use these arguments if you want to confirm that the created columns are
63the types that you expect. Note that if you want to change (instead of confirm)
64the types of specific columns, you should use \code{names_transform} or
65\code{values_transform} instead.}
66
67\item{names_transform, values_transform}{A list of column name-function pairs.
68Use these arguments if you need to change the types of specific columns.
69For example, \code{names_transform = list(week = as.integer)} would convert
70a character variable called \code{week} to an integer.
71
72If not specified, the type of the columns generated from \code{names_to} will
73be character, and the type of the variables generated from \code{values_to}
74will be the common type of the input columns used to generate them.}
75
76\item{names_repair}{What happens if the output has invalid column names?
77The default, \code{"check_unique"} is to error if the columns are duplicated.
78Use \code{"minimal"} to allow duplicates in the output, or \code{"unique"} to
79de-duplicated by adding numeric suffixes. See \code{\link[vctrs:vec_as_names]{vctrs::vec_as_names()}}
80for more options.}
81
82\item{values_to}{A string specifying the name of the column to create
83from the data stored in cell values. If \code{names_to} is a character
84containing the special \code{.value} sentinel, this value will be ignored,
85and the name of the value column will be derived from part of the
86existing column names.}
87
88\item{values_drop_na}{If \code{TRUE}, will drop rows that contain only \code{NA}s
89in the \code{value_to} column. This effectively converts explicit missing values
90to implicit missing values, and should generally be used only when missing
91values in \code{data} were created by its structure.}
92
93\item{...}{Additional arguments passed on to methods.}
94}
95\description{
96\code{pivot_longer()} "lengthens" data, increasing the number of rows and
97decreasing the number of columns. The inverse transformation is
98\code{\link[=pivot_wider]{pivot_wider()}}
99
100Learn more in \code{vignette("pivot")}.
101}
102\details{
103\code{pivot_longer()} is an updated approach to \code{\link[=gather]{gather()}}, designed to be both
104simpler to use and to handle more use cases. We recommend you use
105\code{pivot_longer()} for new code; \code{gather()} isn't going away but is no longer
106under active development.
107}
108\examples{
109# See vignette("pivot") for examples and explanation
110
111# Simplest case where column names are character data
112relig_income
113relig_income \%>\%
114  pivot_longer(!religion, names_to = "income", values_to = "count")
115
116# Slightly more complex case where columns have common prefix,
117# and missing missings are structural so should be dropped.
118billboard
119billboard \%>\%
120 pivot_longer(
121   cols = starts_with("wk"),
122   names_to = "week",
123   names_prefix = "wk",
124   values_to = "rank",
125   values_drop_na = TRUE
126 )
127
128# Multiple variables stored in column names
129who \%>\% pivot_longer(
130  cols = new_sp_m014:newrel_f65,
131  names_to = c("diagnosis", "gender", "age"),
132  names_pattern = "new_?(.*)_(.)(.*)",
133  values_to = "count"
134)
135
136# Multiple observations per row
137anscombe
138anscombe \%>\%
139 pivot_longer(everything(),
140   names_to = c(".value", "set"),
141   names_pattern = "(.)(.)"
142 )
143}
144