batpigandme
commented
5 years ago So, let me go through some pieces of this, and hopefully we can figure out if this should be split into multiple issues, or if it can be addressed all at once:
The gif
Right now the gif is posted on Twitter, but I'd like to see it in more places where people can find it while they're searching for information about
tidyr::gather().
I think my love for gifs is pretty well established. However, since we use roxygen2, putting this directly into the gather() function reference (and, hence, into the cascade of .R ⇨ .Rd ⇨ .html through pkgdown) would mean putting a gif into the ?gather help in R, which I don't know that the world (or CRAN) is ready for.
With reprex (which begs for explanation by gif, IMHO), we've gotten around this by adding non-vignette articles to the pkgdown site (e.g. Magic reprex, Using datapasta with reprex) to make the giffed-up documentation accessible, without rocking the boat of TPTB.
A complaint
Also, I want to complain that the example in the documentation uses the naked words
stockandpriceinstead of"stock"and"price"as I would have expected.
At least in the development version documentation, this example reads as such:
suppressPackageStartupMessages(library(tidyverse))
stocks <- tibble(
time = as.Date('2009-01-01') + 0:9,
X = rnorm(10, 0, 1),
Y = rnorm(10, 0, 2),
Z = rnorm(10, 0, 4)
)
gather(stocks, stock, price, -time)
#> # A tibble: 30 x 3
#> time stock price
#> <date> <chr> <dbl>
#> 1 2009-01-01 X -1.11
#> 2 2009-01-02 X 0.758
#> 3 2009-01-03 X -0.192
#> 4 2009-01-04 X -2.64
#> 5 2009-01-05 X -0.854
#> 6 2009-01-06 X 1.70
#> 7 2009-01-07 X 1.15
#> 8 2009-01-08 X -1.38
#> 9 2009-01-09 X -0.349
#> 10 2009-01-10 X -1.66
#> # ... with 20 more rows
stocks %>% gather(stock, price, -time)
#> # A tibble: 30 x 3
#> time stock price
#> <date> <chr> <dbl>
#> 1 2009-01-01 X -1.11
#> 2 2009-01-02 X 0.758
#> 3 2009-01-03 X -0.192
#> 4 2009-01-04 X -2.64
#> 5 2009-01-05 X -0.854
#> 6 2009-01-06 X 1.70
#> 7 2009-01-07 X 1.15
#> 8 2009-01-08 X -1.38
#> 9 2009-01-09 X -0.349
#> 10 2009-01-10 X -1.66
#> # ... with 20 more rowsCreated on 2018-11-06 by the reprex package (v0.2.1.9000)
It uses non-standard evaluation (NSE) which is used throughout the tidyverse, and in base R as well. I hear what you're saying in re. it being unexpected if you're anticipating standard evaluation, but it does indeed work. (We also use these semantics for rename(), etc.) This isn't to say it's an ideal example, but perhaps that it deserves more explanation, or illustration that it works whether or not you use quotation marks.
Comparison to melt
Lastly, you might consider whether the documentation for gather() would be enhanced by showing a direct side-by-side comparison [to]…melt(). Personally, I would find it helpful. Others might find this confusing…
There's a nice example of this idea that @jimhester did for plyr and dplyr here. As you point out, this is something that's super helpful to a specific target audience. As such, I'm not sure that the function reference is the best place to document it. Perhaps an article would work for this as well, whether part of the official tidyr documentation or not.
In going through this, I've realised that I need to better-document the one-issue-per-issue paradigm we try to follow in the tidyverse, and that we need to add the repo CONTRIBUTING guide to tidyr! 🙈
I'll wait for someone else to chime in, but if it looks like these are fixes that will go in separate places, then we should probably split it, so that we can easily tie the closing PRs to their matching issues.
slowkow
hadley
apreshill
khailper
cderv
yutannihilation
jimhester
The gif
@apreshill made the best explanation for
tidyr::gather()that I have ever seen:Thank you, Alison! :100:
The fundamental problem this gif solved for me is the confusion caused by the
keyandvaluearguments.Before seeing this gif, I falsely (and instinctively) equated these things:
keyandvaluearguments intidyr::gather()id.varsandmeasure.varsarguments inreshape2::melt()This gif finally opened my eyes to the fact that
keyandvalueintidyr::gather()are analogous tovariable.nameandvalue.nameinreshape2::melt(). So many struggles :sob:Could we include this gif directly in the documentation on this page?
Right now the gif is posted on Twitter, but I'd like to see it in more places where people can find it while they're searching for information about
tidyr::gather().A complaint about magical expressions
Also, I want to complain that the example in the documentation uses the naked words
stockandpriceinstead of"stock"and"price"as I would have expected. This is one of the magical things about R that was always difficult to accept as a beginner (and continues to be a challenge as a more experienced R user). It is difficult to accept that R will just know thatstockshould be turned into"stock"as a column name, instead of throwing an error because there is nostockvariable defined anywhere, and there is nostockcolumn in the input dataframe, either.My expectation is this:
A direct comparison to melt
Lastly, you might consider whether the documentation for
gather()would be enhanced by showing a direct side-by-side comparison of the same operation executed 2 times, once bygather()and again bymelt(). Personally, I would find it helpful. Others might find this confusing if they have never seen either function before, so it might not be a good idea.Something like this: