review of first draft

[beanumber]

I really like what you are trying to do here. Your work on this topic has been really well-received, and I think a lot of people will appreciate the kind of nuts-and-bolts how-to that you present here. The concept of starting with the raw data, discussing some of the wrangling challenges, briefly discussing previously-published models, creating interesting visualizations, and discussing results, is perfect. I do have comments on the implementation. :)

• Since you have included so much code in the paper (roughly half of the content) you should think carefully about what you show here and what you hope to accomplish. I think there is too much code. While the functions are well-documented, many of them are too long and not that interesting. The code itself is also written in a non-R style with lots of for loops and indexing. I wonder whether much of this code could be greatly shortened by using a dplyr approach. For example, the first function you present is add_possession_columns_to_moments(), and this occupies more than a full page. Can't this be written as a single call to mutate() with some ifelse() statements? If all you are doing is defining two new columns based on the corresponding values of existing columns, then I think this should work. Similarly, in get_moments_w_possession_cols() I wonder if an appeal to dplyr::do() would be a conceptually simpler way to go here.

  This raises the larger question of what you hope to accomplish by including the code for these functions. If the goal is simply to be explicit about exactly what you have done, then you have certainly achieved this. However, I don't know how many people will want to sit down and read this code. You might reach a wider audience by putting the code in an R package, documenting the functions there, and then using the space you free up to illustrate how the functions work and how another analyst might use them. You would also have more room for discussing interesting findings. [A sportVU package for R would be pretty exciting!]

  I'll leave it to the @jennybc and @hadley to decide whether adding two derivative columns to a data frame is an operation that will be interesting to readers. As a data scientist, I think it's cool, but then it invites me to examine your code and think that it could be done more simply. As a basketball fan, it's not really that interesting.

• I like the way that you included the first row of data at the beginning, but the way that this prints out in R makes it very hard to read. I'd suggest using a table with xtable. Since the variables relating to the 10 players are all the same, you could condense this by just showing the non-player related variables, and one set of the four variables describing the i-th player.
• I would suggest focusing more on the interpretable results. I found the discussion at the end about the differences in the acceleration patterns of LeBron, Drummond, and Curry to be the most compelling part of the paper. In my opinion this is the "wow" moment when the reader is convinced that they too can learn about basketball through these data. The section on "Movement and Simluation Functions" ends abruptly with no discussion of the results. What did we learn from this?
• Can a reader get the SportVU data other than the sample you posted on GitHub? I think a discussion of the availability is warranted.
• I strongly recommend including a short section near the beginning that orients the reader to the units and coordinates of these data. For example, are the x's and y's measured in feet? Where is (0,0)? Later you mention that the coordinates are in a [0,47] x [0,50] grid, which I recognize since the court is 94 feet by 50 feet, but most readers will not pick up on that. I'd suggest including a graphic very early in the paper that makes this clear.
• There are some moments of non-academic phrasing (e.g. "Let's back it up", "all we have to do", "boils down to", "gridding up"), that could be easily corrected.
• If you're going to stick with the "shoulders of past giants" line, I'd suggest weaving in an NBA joke (since the players are so tall!)

In summary, I think this is a really worthwhile effort, but that it would work better as a vignette about what the sportVU package can do and how it works, as opposed to an annotated description of your code.

[lukebornn]

I think we've now addressed the majority of the issues you raise -- it's definitely cleaned up relative to the first draft. Let us know if anything still stands out to you.

[beanumber]

First of all, I'm embarrassed that it has taken me this long to respond. Please accept my apologies!

The revision is certainly an improvement. In particular, I think the end is much stronger with the concluding paragraphs. I still think there is too much code, but I guess that decision should be made by @jennybc and @hadley.

A few general comments:

• I see that you have R-ified the code by replacing a few for loops with calls to apply(), which is good. I still see places where further clarity could be achieved. For example, in plot_distribution_of_movement_distances() couldn't the for loop be replaced by a call to lag()? Anyway, I realize it's ridiculous to expect a full code re-write, but others may spot similar things.
• The language in the Conclusion, especially in the On-ball Plots section, is not appropriate IMHO. While I share the authors' enthusiasm for NBA basketball, I don't think we as academics should be passing judgement on Steph Curry's body development. Phrases like "almost unstoppable" are similarly appropriate in the media but I don't think in a serious professional discussion. Do you think that the Cavs' sports analytics group---who may read this paper---would agree that Curry is "unstoppable"?

Some minor comments:

• "data" is plural
• pg. 2: put the variables in the same order that they appear in the R output. Also, clarify that a and h stand for away and home.
• I would use open and closed parentheses to denote function names (e.g. add_possession_columns_to_moments()
• pg. 4: It wasn't clear to me what $TEAM_ID means.
• pg. 8: Is $\delta$ in the units of feet per second? If so, state that.
• pg. 9: Spell out "Histogram" at the top of Figure 1.
• I still think you need to say something at the end of the section on Movement Simulation Functions. There is a long block of code, then a figure, and then another long block of code, and then a new section! Can you remind us why we are reading this and what the point of the section is?
• pg. 10: "one-hot"?? Is that a typo?
• pg. 13: Please refer to the Figures by number in the text. All of the Figures should be referenced in the text.
• pg. 14: "quickly" instead of "quick"
• pg. 14: "most unique": I believe that uniqueness cannot be qualified -- something either is or is not unique. Also, do you mean unique among the three players you have listed? Or among all players? In any case, I'm not sure that uniqueness is really what you are trying to highlight here.
• pg. 14: I don't really follow the argument about Steph Curry's off-ball movement. Can you clarify?

Thanks for contributing this paper -- it was my pleasure to read!

[jennybc]

Thanks @beanumber for the continuing review!

[nicholasjhorton]

I couldn't resist chiming in here. I've been a big proponent that data are plural. But I should note that the Wall Street Journal and others think differently:

http://blogs.wsj.com/economics/2012/07/05/is-data-is-or-is-data-aint-a-plural/

One of my New Year's resolutions is to be more relaxed about English grammar.

Just my $0.02.

On Jan 31, 2017, at 3:42 PM, Ben Baumer notifications@github.com wrote:

• "data" is plural

Nicholas Horton Professor of Statistics Department of Mathematics and Statistics, Amherst College PO Box 5000, AC #2239 Amherst, MA 01002-5000

[stevenwu4]

Thanks for the detailed review! I'm working on addressing your comments right now.

RE: one-hot encoding, I've seen it used in the literature with a hyphen. Looking it up online I see some with it (like the Wiki page) and some without.