- data
A data frame to pivot.
- cols
<tidy-select
> Columns to pivot into
longer format.
- names_to
A character vector specifying the new column or columns to
create from the information stored in the column names of data
specified
by cols
.
If length 0, or if NULL
is supplied, no columns will be created.
If length 1, a single column will be created which will contain the
column names specified by cols
.
If length >1, multiple columns will be created. In this case, one of
names_sep
or names_pattern
must be supplied to specify how the
column names should be split. There are also two additional character
values you can take advantage of:
NA
will discard the corresponding component of the column name.
".value"
indicates that the corresponding component of the column
name defines the name of the output column containing the cell values,
overriding values_to
entirely.
- names_prefix
A regular expression used to remove matching text
from the start of each variable name.
- names_sep, names_pattern
If names_to
contains multiple values,
these arguments control how the column name is broken up.
names_sep
takes the same specification as separate()
, and can either
be a numeric vector (specifying positions to break on), or a single string
(specifying a regular expression to split on).
names_pattern
takes the same specification as extract()
, a regular
expression containing matching groups (()
).
If these arguments do not give you enough control, use
pivot_longer_spec()
to create a spec object and process manually as
needed.
- names_ptypes, values_ptypes
Optionally, a list of column name-prototype
pairs. Alternatively, a single empty prototype can be supplied, which will
be applied to all columns. A prototype (or ptype for short) is a
zero-length vector (like integer()
or numeric()
) that defines the type,
class, and attributes of a vector. Use these arguments if you want to
confirm that the created columns are the types that you expect. Note that
if you want to change (instead of confirm) the types of specific columns,
you should use names_transform
or values_transform
instead.
For backwards compatibility reasons, supplying list()
is interpreted as
being identical to NULL
rather than as using a list prototype on all
columns. Expect this to change in the future.
- names_transform, values_transform
Optionally, a list of column
name-function pairs. Alternatively, a single function can be supplied,
which will be applied to all columns. Use these arguments if you need to
change the types of specific columns. For example, names_transform = list(week = as.integer)
would convert a character variable called week
to an integer.
If not specified, the type of the columns generated from names_to
will
be character, and the type of the variables generated from values_to
will be the common type of the input columns used to generate them.
- names_repair
What happens if the output has invalid column names?
The default, "check_unique"
is to error if the columns are duplicated.
Use "minimal"
to allow duplicates in the output, or "unique"
to
de-duplicated by adding numeric suffixes. See vctrs::vec_as_names()
for more options.
- values_to
A string specifying the name of the column to create
from the data stored in cell values. If names_to
is a character
containing the special .value
sentinel, this value will be ignored,
and the name of the value column will be derived from part of the
existing column names.
- values_drop_na
If TRUE
, will drop rows that contain only NA
s
in the value_to
column. This effectively converts explicit missing values
to implicit missing values, and should generally be used only when missing
values in data
were created by its structure.
- ...
Additional arguments passed on to methods.