Recommandé
Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à Everything you wanted to know about making an R package but were afraid to ask
Similaire à Everything you wanted to know about making an R package but were afraid to ask (20)
Dernier
Dernier (20)
Everything you wanted to know about making an R package but were afraid to ask
- 1. Everything you wanted to know about making R packages but were afraid to ask Emily Robinson @robinson_es
- 4. Isn’t making packages for “real programmers”? Can you open and run R / RStudio? Can you install a package? Can you write R code? Can you write an R function? Can you learn to write an R function? Excellent, you can write a package! From Susan Johnston, as used in Jim Hester’s RStudio 2018 conference talk https://resources.rstudio.com/rstudio-conf-2018/you-can-make-a-package-in-20-minutes-jim-hester
- 5. Does making a package take a lot of time? “It took me such little time that I was hit with that familiar feeling of the joy of optimization combined with the regret of past inefficiencies (joygret?). I wish I could go back in time and create the package the first moment I thought about it” - Hilary Parker https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/
- 6. When is it time to write a package? If you’ve copied and pasted code three times, write a function If you’ve used the same function across three analyses, write a package
- 7. Benefits of making a package Yourself Your company or team Public • Saves yourself time • Reduces the risk of error • Helps you share your code • Includes documentation with your functions • Give back to your community • Builds your brand
- 8. How do you make a package?
- 10. Create the package structure, add a function library(usethis) create_package(“~/Desktop/nyrconf”) use_r(“i_love_nyrconf”)
- 11. Add function documentation use_roxygen_md() • Write documentation early, soon after you finish a function • It’s useful not just for other people, but for your own future self
- 12. Add function documentation use_roxygen_md() • Write documentation early, soon after you finish a function • It’s useful not just for other people, but for your own future self
- 14. How do you document your package?
- 15. DESCRIPTION File
- 16. The Package Documentation Pyramid Name Title (one sentence) Description (one paragraph) README Vignette
- 17. What’s in a name? Not taken on CRAN Not too long Is easy to google Evokes what it does
- 19. Title • Describes what the package does • One sentence, ideally < 65 characters
- 20. Description • One paragraph focused on the value of your package Summary sentence Benefits Main functions
- 22. README – Installation instructions
- 24. Vignette • It’s a case study • Use real and interesting data • If it’s statistics package, make a model; if it’s visualization package, make a graph
- 25. Vignette • It’s a case study • Use real and interesting data • If it’s statistics package, make a model; if it’s visualization package, make a graph
- 26. How can you improve your package?
- 27. “This worked fine before …”
- 29. Write tests with testthat • Write tests early and often so then you can safely develop • Whenever you fix a bug, put in a test that would have caught it use_testthat() use_test(“i_love_nyrconf”)
- 30. How do you market your package?
- 31. Marketing is not a bad word
- 32. Publish it on GitHub • GitHub lets you easily share your package • If you’ve never used GitHub, check out Jenny Bryan’s Happy Git and GitHub for the useR https://happygitwithr.com/
- 33. Make a website with pkgdown • pkgdown::build_site()
- 34. Blog and tweet about it! • Use #rstats • Give a one line motivation • Can remix your README and Vignette
- 35. Submit your package to CRAN “If you want your package to have significant traction in the R community, you need to submit it to CRAN. Submitting to CRAN is a lot more work than just providing a version on GitHub, but the vast majority of R users do not install packages from GitHub, because CRAN provides discoverability, ease of installation and a stamp of authenticity.” - Hadley Wickham http://r-pkgs.had.co.nz/release.html
- 36. If you’re successful …
- 37. Resources
- 38. Drum roll please …
- 39. There’s a new R packages book in the works!! https://r-pkgs.org/
- 40. Other resources • Hilary Parker on writing an R package from scratch • Jim Hester: “You can make a package in 20 minutes” • Karl Broman’s tutorial • Sharla Gelfand on usethis for reporting • usethis website • Maëlle Salmon on developing good R packages for open science • Julia Silge’s beginner’s guide to TravisCI
Notes de l'éditeur
- Maybe cut?
- What are things you do over and over again that should be easy that are hard? Notice the problem you’re solving with this function is not specific to this one analysis – it’s generalizable. You might think “this would have been helpful last month”
- Usethis is magic. And it’s newer
- Function documentation – you know it exists, you sort of know what it does, you just forget details Package documentation – explaining the value of the package and introducing you to the main functions
- That goes in the R file – and it goes on the top of github page and shows in the preview on google results.
- If you can’t fit a description in one paragraph, maybe package is too broad Could be the abstract of a talk or paper If you have a few main functions, can mention there
- Point people where to start, where to go next If you have a package down site, link to it Many people will only see this Don’t have it be too long
- For example, here’s a vignette I wrote for forcats during tidyverse developer day Don’t create objects a, b, and c and add them together.
- Not just getting famous, want other people to get use out of it and contribute to it.
- When something you’ve counted on to work suddenly gives out on you. How can you prevent these cases?
- Not just getting famous, want other people to get use out of it and contribute to it.
- Marketing is equally important even if it’s something you only use within your company; people should know what use they can get out of your package Helps them! Not a selfish thing.