[Maturing]

`pivot_longer()` "lengthens" data, increasing the number of rows and decreasing the number of columns. The inverse transformation is [pivot_wider()]

Learn more in `vignette("pivot")`.

Arguments

data

A data frame to pivot.

cols

<[`tidy-select`][tidyr_select]> Columns to pivot into longer format.

names_to

A string specifying the name of the column to create from the data stored in the column names of `data`.

Can be a character vector, creating multiple columns, if `names_sep` or `names_pattern` is provided. In this case, there are two special values you can take advantage of:

* `NA` will discard that component of the name. * `.value` indicates that component of the name defines the name of the column containing the cell values, overriding `values_to`.

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_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.

names_transform, values_transform

A list of column name-function pairs. Use these arguments if you need to change the type of specific columns. For example, `names_transform = list(week = as.integer)` would convert a character week variable to an integer.

names_ptypes, values_ptypes

A list of column name-prototype pairs. 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 to confirm that the created columns are the types that you expect.

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.

...

Additional arguments passed on to methods.

Value

A Seurat object or a tibble depending on input

Details

`pivot_longer()` is an updated approach to [gather()], designed to be both simpler to use and to handle more use cases. We recommend you use `pivot_longer()` for new code; `gather()` isn't going away but is no longer under active development.

Examples

# See vignette("pivot") for examples and explanation

library(dplyr)
#> 
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:tidyseurat’:
#> 
#>     add_count, bind_cols, bind_rows, count
#> The following objects are masked from ‘package:stats’:
#> 
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#> 
#>     intersect, setdiff, setequal, union
data("pbmc_small")
pbmc_small %>%  pivot_longer(c(orig.ident, groups), names_to = "name", values_to = "value") 
#> tidyseurat says: A data frame is returned for independent data analysis.
#> # A tibble: 160 × 29
#>    .cell     nCount_RNA nFeature_RNA RNA_snn_res.0.8 letter.idents RNA_snn_res.1
#>    <chr>          <dbl>        <int> <fct>           <fct>         <fct>        
#>  1 ATGCCAGA…         70           47 0               A             0            
#>  2 ATGCCAGA…         70           47 0               A             0            
#>  3 CATGGCCT…         85           52 0               A             0            
#>  4 CATGGCCT…         85           52 0               A             0            
#>  5 GAACCTGA…         87           50 1               B             0            
#>  6 GAACCTGA…         87           50 1               B             0            
#>  7 TGACTGGA…        127           56 0               A             0            
#>  8 TGACTGGA…        127           56 0               A             0            
#>  9 AGTCAGAC…        173           53 0               A             0            
#> 10 AGTCAGAC…        173           53 0               A             0            
#> # … with 150 more rows, and 23 more variables: PC_1 <dbl>, PC_2 <dbl>,
#> #   PC_3 <dbl>, PC_4 <dbl>, PC_5 <dbl>, PC_6 <dbl>, PC_7 <dbl>, PC_8 <dbl>,
#> #   PC_9 <dbl>, PC_10 <dbl>, PC_11 <dbl>, PC_12 <dbl>, PC_13 <dbl>,
#> #   PC_14 <dbl>, PC_15 <dbl>, PC_16 <dbl>, PC_17 <dbl>, PC_18 <dbl>,
#> #   PC_19 <dbl>, tSNE_1 <dbl>, tSNE_2 <dbl>, name <chr>, value <chr>