library(tidyr)library(dplyr,warn.conflicts =FALSE)library(purrr)packageVersion("tidyr")#> [1] '1.3.1'mini_iris<-as_tibble(iris)[c(1,2,51,52,101,102), ]mini_iris#> # A tibble: 6 × 5#>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species#>          <dbl>       <dbl>        <dbl>       <dbl> <fct>#> 1          5.1         3.5          1.4         0.2 setosa#> 2          4.9         3            1.4         0.2 setosa#> 3          7           3.2          4.7         1.4 versicolor#> 4          6.4         3.2          4.5         1.5 versicolor#> 5          6.3         3.3          6           2.5 virginica#> 6          5.8         2.7          5.1         1.9 virginica

Fixed column names

If you know the column names, this code works in the same wayregardless of whether its inside or outside of a package:

mini_iris%>%nest(petal =c(Petal.Length, Petal.Width),sepal =c(Sepal.Length, Sepal.Width))#> # A tibble: 3 × 3#>   Species    petal            sepal#>   <fct>      <list>           <list>#> 1 setosa     <tibble [2 × 2]> <tibble [2 × 2]>#> 2 versicolor <tibble [2 × 2]> <tibble [2 × 2]>#> 3 virginica  <tibble [2 × 2]> <tibble [2 × 2]>

ButR CMD check will warn about undefined globalvariables (Petal.Length,Petal.Width,Sepal.Length, andSepal.Width), because itdoesn’t know thatnest() is looking for the variablesinside ofmini_iris (i.e. Petal.Length andfriends are data-variables, not env-variables).

The easiest way to silence this note is to useall_of().all_of() is a tidyselect helper (likestarts_with(),ends_with(), etc.) that takescolumn names stored as strings:

mini_iris%>%nest(petal =all_of(c("Petal.Length","Petal.Width")),sepal =all_of(c("Sepal.Length","Sepal.Width")))#> # A tibble: 3 × 3#>   Species    petal            sepal#>   <fct>      <list>           <list>#> 1 setosa     <tibble [2 × 2]> <tibble [2 × 2]>#> 2 versicolor <tibble [2 × 2]> <tibble [2 × 2]>#> 3 virginica  <tibble [2 × 2]> <tibble [2 × 2]>

Alternatively, you may want to useany_of() if it is OKthat some of the specified variables cannot be found in the inputdata.

Thetidyselect packageoffers an entire family of select helpers. You are probably alreadyfamiliar with them from usingdplyr::select().

Continuous integration

Hopefully you’ve already adopted continuous integration for yourpackage, in whichR CMD check (which includes your owntests) is run on a regular basis, e.g. every time you push changes toyour package’s source on GitHub or similar. The tidyverse team currentlyrelies most heavily on GitHub Actions, so that will be our example.usethis::use_github_action() can help you get started.

We recommend adding a workflow that targets the devel version oftidyr. When should you do this?

• Always? If your package is tightly coupled to tidyr, considerleaving this in place all the time, so you know if changes in tidyraffect your package.

• Right before a tidyr release? For everyone else, you could add(or re-activate an existing) tidyr-devel workflow during the periodpreceding a major tidyr release that has the potential for breakingchanges, especially if you’ve been contacted during our reversedependency checks.

Example of a GitHub Actions workflow that tests your package againstthe development version of tidyr:

on:push:branches:- mainpull_request:branches:- mainname: R-CMD-check-tidyr-develjobs:R-CMD-check:runs-on: macOS-lateststeps:-uses: actions/checkout@v2-uses: r-lib/actions/setup-r@v1-name: Install dependencies        run:|          install.packages(c("remotes", "rcmdcheck"))          remotes::install_deps(dependencies = TRUE)          remotes::install_github("tidyverse/tidyr")shell: Rscript {0}-name: Checkrun: rcmdcheck::rcmdcheck(args = "--no-manual", error_on = "error")shell: Rscript {0}

GitHub Actions are an evolving landscape, so you can always mine theworkflows for tidyr itself (tidyverse/tidyr/.github/workflows)or the mainr-lib/actionsrepo for ideas.

Conditional code

Sometimes you’ll be able to write code that works with v0.8.3and v1.0.0. But this often requires code that’s notparticularly natural for either version and you’d be better off to(temporarily) have separate code paths, each containing non-contrivedcode. You get to re-use your existing code in the “old” branch, whichwill eventually be phased out, and write clean, forward-looking code inthe “new” branch.

The basic approach looks like this. First you define a function thatreturnsTRUE for new versions of tidyr:

tidyr_new_interface<-function() {packageVersion("tidyr")>"0.8.99"}

We highly recommend keeping this as a function because it provides anobvious place to jot any transition notes for your package, and it makesit easier to remove transitional code later on. Another benefit is thatthe tidyr version is determined atrun time, not atbuildtime, and will therefore detect your user’s current tidyrversion.

Then in your functions, you use anif statement to calldifferent code for different versions:

my_function_inside_a_package<-function(...)# my code hereif (tidyr_new_interface()) {# Freshly written code for v1.0.0    out<- tidyr::nest(df,data =any_of(c("x","y","z")))  }else {# Existing code for v0.8.3    out<- tidyr::nest(df, x, y, z)  }# more code here}

If your new code uses a function that only exists in tidyr 1.0.0, youwill get aNOTE fromR CMD check: this is oneof the few notes that you can explain in your CRAN submission comments.Just mention that it’s for forward compatibility with tidyr 1.0.0, andCRAN will let your package through.

New syntax fornest()

What changed:

• The to-be-nested columns are no longer accepted as “looseparts”.
• The new list-column’s name is no longer provided via the.key argument.
• Now we use a construct like this:new_col = <something about existing cols>.

Why it changed:

• The use of... for metadata is a problematic patternwe’re moving away from.https://design.tidyverse.org/dots-data.html

• Thenew_col = <something about existing cols>construct lets us create multiple nested list-columns at once(“multi-nest”).

  mini_iris%>%nest(petal =matches("Petal"),sepal =matches("Sepal"))#> # A tibble: 3 × 3#>   Species    petal            sepal#>   <fct>      <list>           <list>#> 1 setosa     <tibble [2 × 2]> <tibble [2 × 2]>#> 2 versicolor <tibble [2 × 2]> <tibble [2 × 2]>#> 3 virginica  <tibble [2 × 2]> <tibble [2 × 2]>

Before and after examples:

# v0.8.3mini_iris%>%nest(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width,.key ="my_data")# v1.0.0mini_iris%>%nest(my_data =c(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width))# v1.0.0 avoiding R CMD checkNOTEmini_iris%>%nest(my_data =any_of(c("Sepal.Length","Sepal.Width","Petal.Length","Petal.Width")))# or equivalently:mini_iris%>%nest(my_data =!any_of("Species"))

If you need a quick and dirty fix without having to think, just callnest_legacy() instead ofnest(). It’s the sameasnest() in v0.8.3:

if (tidyr_new_interface()) {  out<- tidyr::nest_legacy(df, x, y, z)}else {  out<- tidyr::nest(df, x, y, z)}

New syntax forunnest()

What changed:

• The to-be-unnested columns must now be specified explicitly,instead of defaulting to all list-columns. This also deprecates.drop and.preserve.

• .sep has been deprecated and replaced withnames_sep.

• unnest() uses theemergingtidyverse standard to disambiguate duplicated names. Usenames_repair = tidyr_legacy to request the previousapproach.

• .id has been deprecated because it can be easilyreplaced by creating the column of names prior tounnest(),e.g. with an upstream call tomutate().

  # v0.8.3df%>%unnest(x,.id ="id")# v1.0.0df%>%mutate(id =names(x))%>%unnest(x))

Why it changed:

• The use of... for metadata is a problematic patternwe’re moving away from.https://design.tidyverse.org/dots-data.html

• The changes to details arguments relate to features rolling outacross multiple packages in the tidyverse. For example,ptype exposes prototype support from the newvctrs package.names_repair specifies what to do about duplicated ornon-syntactic names, consistent with tibble and readxl.

Before and after:

nested<- mini_iris%>%nest(my_data =c(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width))# v0.8.3 automatically unnests list-colsnested%>%unnest()# v1.0.0 must be told which columns to unnestnested%>%unnest(any_of("my_data"))

If you need a quick and dirty fix without having to think, just callunnest_legacy() instead ofunnest(). It’s thesame asunnest() in v0.8.3:

if (tidyr_new_interface()) {  out<- tidyr::unnest_legacy(df)}else {  out<- tidyr::unnest(df)}

nest() preserves groups

What changed:

• nest() now preserves the groups present in theinput.

Why it changed:

• To reflect the growing support for grouped data frames, especiallyin recent releases of dplyr. See, for example,dplyr::group_modify(),group_map(), andfriends.

If the fact thatnest() now preserves groups isproblematic downstream, you have a few choices:

• Applyungroup() to the result. This level ofpragmatism suggests, however, you should at least consider the next twooptions.

• You should never have grouped in the first place. Eliminate thegroup_by() call and specify which columns should be nestedversus not nested directly innest().

• Adjust the downstream code to accommodate grouping.

Imagine we usedgroup_by() thennest() onmini_iris, then we computed on the list-columnoutsidethe data frame.

(df<- mini_iris%>%group_by(Species)%>%nest())#> # A tibble: 3 × 2#> # Groups:   Species [3]#>   Species    data#>   <fct>      <list>#> 1 setosa     <tibble [2 × 4]>#> 2 versicolor <tibble [2 × 4]>#> 3 virginica  <tibble [2 × 4]>(external_variable<-map_int(df$data, nrow))#> [1] 2 2 2

And now we try to add that back to the datapost hoc:

df%>%mutate(n_rows = external_variable)#> Error in `mutate()`:#> ℹ In argument: `n_rows = external_variable`.#> ℹ In group 1: `Species = setosa`.#> Caused by error:#> ! `n_rows` must be size 1, not 3.

This fails becausedf is grouped andmutate() is group-aware, so it’s hard to add a completelyexternal variable. Other than pragmaticallyungroup()ing,what can we do? One option is to work inside the data frame, i.e. bringthemap() inside themutate(), and design theproblem away:

df%>%mutate(n_rows =map_int(data, nrow))#> # A tibble: 3 × 3#> # Groups:   Species [3]#>   Species    data             n_rows#>   <fct>      <list>            <int>#> 1 setosa     <tibble [2 × 4]>      2#> 2 versicolor <tibble [2 × 4]>      2#> 3 virginica  <tibble [2 × 4]>      2

If, somehow, the grouping seems appropriate AND working inside thedata frame is not an option,tibble::add_column() isgroup-unaware. It lets you add external data to a grouped dataframe.

df%>%  tibble::add_column(n_rows = external_variable)#> # A tibble: 3 × 3#> # Groups:   Species [3]#>   Species    data             n_rows#>   <fct>      <list>            <int>#> 1 setosa     <tibble [2 × 4]>      2#> 2 versicolor <tibble [2 × 4]>      2#> 3 virginica  <tibble [2 × 4]>      2

nest_() andunnest_() are defunct

What changed:

• nest_() andunnest_() no longer work

Why it changed:

• We are transitioning the whole tidyverse to the powerful tidy evalframework. Therefore, we are gradually removing all previous solutions:
  • Specialized standard evaluation versions of functions, e.g.,foo_() as a complement tofoo().
  • The older lazyeval framework.

Before and after:

# v0.8.3mini_iris%>%nest_(key_col ="my_data",nest_cols =c("Sepal.Length","Sepal.Width","Petal.Length","Petal.Width")  )nested%>%unnest_(~ my_data)# v1.0.0mini_iris%>%nest(my_data =any_of(c("Sepal.Length","Sepal.Width","Petal.Length","Petal.Width")))nested%>%unnest(any_of("my_data"))