Submission: Rpuck

[PolinaRomanchenko]

Submitting Author: Xugang Zhong (@chuusan ), Jarvis Nederlof (@jnederlo), Polina Romanchenko (@PolinaRomanchenko), Manish Joshi (@ManishPJoshi),
Repository: rpuck Version submitted: v1.1.0 Editor: Varada Kolhatkar (@kvarada) Reviewer 1: Yue Jiang (@YueJiangMDSV) Reviewer 2: Ruidan Ni (@rita-ni) Archive: TBD
Version accepted: TBD

---

• Paste the full DESCRIPTION file inside a code block below:

Package: rpuck
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person(given = "Kirk",
           family = "Zhong",
           role = c("aut", "cre"),
           email = "chuusankirk@hotmail.com",
           comment = c(ORCID = "YOUR-ORCID-ID"))
Description: This package provides wrapper functions to access the publicly available but undocumented NHL.com API.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.0.2
Imports:
    dplyr,
    httr,
    ggplot2,
    jsonlite,
    grid,
    gridExtra,
    glue,
    tidyr,
    testthat,
    scales
Suggests: 
    covr,
    knitr,
    rmarkdown
URL: https://github.com/UBC-MDS/rpuck
BugReports: https://github.com/UBC-MDS/rpuck/issues
VignetteBuilder: knitr

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • [x] data retrieval
  • [x] data extraction
  • [x] data munging
  • [ ] data deposition
  • [ ] workflow automataion
  • [ ] version control
  • [ ] citation management and bibliometrics
  • [ ] scientific software wrappers
  • [ ] database software bindings
  • [ ] geospatial data
  • [ ] text analysis

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

  Our package works to retrieve data from the NHL website into a csv file. Functions within the package wrangle the data into an appropriate form (data frame and ggplot plot objects), and extract relevant insights with which to return to the user.

• Who is the target audience and what are scientific applications of this package?

  Our target audience is sport statisticians, data scientists and NHL enthusiasts who want to gain more insight from available data.

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

  There are some packages written in the R language that are focused on providing a user with convenient tools to access statistics from NHL.com with API calls and helping to make sense of them. Rpuck is landing in its own niche with compared with such libraries as nhlapi, nhlscrape.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Technical checks

Confirm each of the following by checking the box.

• [x] I have read the guide for authors and rOpenSci packaging guide.

This package:

• [x] does not violate the Terms of Service of any service it interacts with.
• [x] has a CRAN and OSI accepted license.
• [x] contains a README with instructions for installing the development version.
• [x] includes documentation with examples for all functions, created with roxygen2.
• [x] contains a vignette with examples of its essential functions and uses.
• [x] has a test suite.
• [x] has continuous integration, including reporting of test coverage using services such as Travis CI, Coveralls and/or CodeCov.

Publication options

• [ ] Do you intend for this package to go on CRAN?
• [ ] Do you intend for this package to go on Bioconductor?
• [ ] Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Options

- [ ] The package has an **obvious research application** according to [JOSS's definition](https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements). - [ ] The package contains a `paper.md` matching [JOSS's requirements](https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain) with a high-level description in the package root or in `inst/`. - [ ] The package is deposited in a long-term repository with the DOI: - (*Do not submit your package separately to JOSS*)

• [ ] Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

- [ ] The package is novel and will be of interest to the broad readership of the journal. - [ ] The manuscript describing the package is no longer than 3000 words. - [ ] You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see [MEE's Policy on Publishing Code](http://besjournals.onlinelibrary.wiley.com/hub/journal/10.1111/(ISSN)2041-210X/journal-resources/policy-on-publishing-code.html)) - (*Scope: Do consider MEE's [Aims and Scope](http://besjournals.onlinelibrary.wiley.com/hub/journal/10.1111/(ISSN)2041-210X/aims-and-scope/read-full-aims-and-scope.html) for your manuscript. We make no guarantee that your manuscript will be within MEE scope.*) - (*Although not required, we strongly recommend having a full manuscript prepared when you submit here.*) - (*Please do not submit your package separately to Methods in Ecology and Evolution*)

Code of conduct

• [x] I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[rita-ni]

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• [x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• [x] A statement of need clearly stating problems the software is designed to solve and its target audience in README
• [x] Installation instructions: for the development version of package and any non-standard dependencies in README
• [x] Vignette(s) demonstrating major functionality that runs successfully locally
• [x] Function Documentation: for all exported functions in R help
• [x] Examples for all exported functions in R Help that run successfully locally
• [x] Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

For packages co-submitting to JOSS

• [ ] The package has an obvious research application according to JOSS's definition

The package contains a paper.md matching JOSS's requirements with:

• [ ] A short summary describing the high-level functionality of the software
• [ ] Authors: A list of authors with their affiliations
• [ ] A statement of need clearly stating problems the software is designed to solve and its target audience.
• [ ] References: with DOIs for all those that have one (e.g. papers, datasets, software).

Functionality

• [x] Installation: Installation succeeds as documented.
• [x] Functionality: Any functional claims of the software been confirmed.
• [x] Performance: Any performance claims of the software been confirmed.
• [x] Automated tests: Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
• [x] Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

Final approval (post-review)

• [ ] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing:

• [x] Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.

---

Review Comments

As a person not very familiar with hockey sports, I found your project repo to be very informative and easy to understand. Your README was very well structured, after reading your README I can understand well what your package is intended for, and the usage examples are very helpful to show what each function in your package is trying to achieve. The dependencies are also clearly listed, which is easy for users to check on prior to installing the package. Great work!

Also, the package logo is a nice touch to the project repo!

Some possible room for improvements:

• I cannot find the link to the vignettes but I do see the vignette in place in your repo. It would be nice to include a link to the rendered vignettes for easier access. And you may want to include this link somewhere noticeable on you README.
• Your code for the functions is clean and well documented. But in the function documentation for your functions, there is no description for each argument besides its type. I noticed that the function description is very detailed and I have no problem understanding the meaning of each argument (they are named well). But it would be more straightforward if you can add a short description for your arguments as well, so users don't have to browse through the entire description in case they just need to check what a single argument is. For example, your current documentation for attendance() vs. documentation for mean():

• For the attendance() function, is it possible to arrange the plots vertically instead of displaying them side by side? The plots look good most of the time, but when regular and playoffs are both set to be TRUE, the plot output is very crowded if the time range is relative long. In this case, the plot produced is still readable, but it would be more visually friendly if the bars are not squeezed together. For example, when I tested attendance(regular=TRUE, playoffs=TRUE, start_season= 1980, end_season=2015), the result is like:

• I tried different inputs for the player_stats() function, as stated in its description if no arguments are passed it returns the stats for the current season. But the function does not raise any error when I passed in out-of-range values, in these cases it still returns the stats for the current season. So you may want to consider adding some error for invalid inputs.

• Similar to player_stats() , I also tested some invalid values for the team_stats() function and the function did not raise errors for out-of-range dates or some nonsense inputs like "22222222". I would suggest some error handling here as well.

I played around with your package a bit so perhaps this feedback is a bit long, it is a fun project! I am happy to have the opportunity to try out and review your package. Please feel free to let me know if you have any questions regarding my feedback.

[YueJiangMDSV]

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• [x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• [x] A statement of need clearly stating problems the software is designed to solve and its target audience in README
• [x] Installation instructions: for the development version of package and any non-standard dependencies in README
• [x] Vignette(s) demonstrating major functionality that runs successfully locally
• [x] Function Documentation: for all exported functions in R help
• [x] Examples for all exported functions in R Help that run successfully locally
• [x] Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

For packages co-submitting to JOSS

• [ ] The package has an obvious research application according to JOSS's definition

The package contains a paper.md matching JOSS's requirements with:

• [ ] A short summary describing the high-level functionality of the software
• [ ] Authors: A list of authors with their affiliations
• [ ] A statement of need clearly stating problems the software is designed to solve and its target audience.
• [ ] References: with DOIs for all those that have one (e.g. papers, datasets, software).

Functionality

• [x] Installation: Installation succeeds as documented.
• [x] Functionality: Any functional claims of the software been confirmed.
• [x] Performance: Any performance claims of the software been confirmed.
• [x] Automated tests: Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
• [x] Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

Final approval (post-review)

• [ ] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing:

3 hours

• [x] Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.

---

Review Comments

Hi everyone, below are my comments:

Well done everyone! The package is really one of a kind. It focuses on a niche market and a special group of target users. I do not think there are any existing package that has the same functionality. The package makes query NHL data fast and easy. For people have no idea how to make API calls or how to scrape data from websites, but are interested in analyzing on NHL data, this package would be of great help.

I personally have no experience in the NHL data, but the package is really easy to use.

Here are some highlights:

1. The installation process through devtools is smooth, with no issues or no warnings.
2. I ran check() in R, and it passed all the tests, no warnings, no errors. Really good job!
3. The package is well-designed and well-documented. The doc strings are clear and succinct, and the examples are easy to understand. It does not take me much longer to understand what are the functions, what can they do, and how to use them.
4. In the README, all the dependencies are listed, especially their version number, which is great! Now the users know what packages and which versions they need to use this package.

Here are some suggestions:

1. The REAME includes installation from CRAN, which does not work…. maybe consider deleting that part?
2. There is no link to the pkgdown website, and there is no link to the vignette. However, I do manage to find the pkgdown website and the vignette (I cloned your repo…and find the html file for pkgdown website). The vignette is exactly the same as the README. I don’t think the vignette and the README are the same thing…otherwise, there is no need to have the vignette. The vignette could be more user-friendly, and in a softer tone to go over all the features/functions in the package. There is no need for the vignette to include installation instructions or dependency list I believe.
3. The package currently is on version v1.1.0, but the documentation says version 0.0.0.9. Maybe consider updating the DESCRIPTION file?
4. The error messages could be more informative. For example, I entered draft_pick(pick_number = 0) and draft_pick(pick_number = "w"), the error message is the same, saying “Pick number out of range”. It might be better to say why pick_number cannot be 0, or why it cannot be a string. Same thing applies to round_number and year.
5. Is there a way to improve the aesthetics of the plots for the attendance function? When I tried attendance(regular=TRUE, playoffs=TRUE, start_season= 2000, end_season=2018), or even longer time range, the labels for the x-axis is hard to read. In might be a good idea to put the two plots vertically, instead of being side-by-side. Additionally, when the time range is short, say 2014 to 2018, the attendance for regular season is almost flat. It is hard to see the changes with attendance is more than 20 million each.
6. If I just type player_stats(start_date = "2019-10-02", end_date = "2020-02-28") in the R console, it does not return anything. I have to assign the function to a variable, and then call that variable to view the results. I looked at the code of the function, and find that the function indeed does not return anything. Same as team_stats() function. It does not return anything if I just type team_stats() in the R console.
7. It may be a good idea to do some pre-wrangling for the returned player_stats() data frame and team_stats() data frame? It is hard for me to find the players’ names or the teams’ names in the current output. The result has many columns that cannot be displayed in one line, and it runs multiple lines. The columns are arranged in alphabetical order, and the players’ names are listed in the last but one column. Thus, for someone not that familiar with the data frame, it may be a little hard to find the players’ names. It may also be a good idea to add the players’ names in the query, so the user can pass the players’ names as an input in the function, and get the results directly, instead of do the wrangling on their own.
8. There seems to be a small typo in test-attendance.R, line 27 to 30:

   test_that("Error message should be expected if regular is set to non_logical value", {
   expect_error(attendance(regular = TRUE, playoffs = 1, start_season = 1996, end_season = 2000),
                regexp = "Regular and playoffs must be logical values!")
   })

Here, clearly, regular is set to logical value, and playoffs is set to non-logical value. But the test_that message is “Error message should be expected if regular is set to non_logical value”

9. In the README, under Usage Example, for the team_stats() function,

attendance <- team_stats(start_season = "19801981", end_season = "19891990")
head(attendance)

Although it is free of choice to assign the value to any variable, assigning the result to a variable called attendance seems confusing, especially when there is a function called attendance()…

Above are just minor suggestions. Overall, I think this is a great package and can be really useful for people analyzing NHL data. I really enjoyed reviewing your package and I am really impressed by the functionalities of the package. Please let me know if you have any questions on my feedbacks. I am happy to discuss.

[chuusan]

@YueJiangMDSV First of all, thank you for the suggestions. In terms of the link to the pkgdown website, we put it on the top of repo as Tiffany's demo. Regarding to the vignette link, we did successfully build it and the link was accidentally missing from our README. Gonna update the README in our final work.

Thank for the suggestions!

[YueJiangMDSV]

@YueJiangMDSV First of all, thank you for the suggestions. In terms of the link to the pkgdown website, we put it on the top of repo as Tiffany's demo. Regarding to the vignette link, we did successfully build it and the link was accidentally missing from our README. Gonna update the README in our final work.

Thank for the suggestions!

Oops! Missed that...Sorry about that! Thanks for pointing out!

[PolinaRomanchenko]

Hi @YueJiangMDSV and @rita-ni! Thank you all for spending time and looking into our package so precisely! We went through and addressed all of the suggestions that didn't introduce new features as those can/should be addressed in future major releases. To specifically summarize what we addressed:

• everything that was missing, wrongfully inputted or out of date in README and DESCRIPTION files (@rita-ni: Bullet point № 3; @YueJiangMDSV Suggestion № 1, 2, 3, 9)
• added user input checks for player_stat() function (@rita-ni : Bullet point №4)
• updated documentation for attendance() function and also other functions (@rita-ni : Bullet point №2)
• fixed typo in function test(@YueJiangMDSV Suggestion 8)
• package version in vignette is updated (was addressed as a part of couple of suggestions)

Regarding other suggestion's not addressed in this release team believes that those can/should be addressed in future major releases or were intentional choices we made for our project. You can view these changes as part of release v1.2.0.