Successfully reported this slideshow.
Your SlideShare is downloading. ×

Everything you wanted to know about making an R package but were afraid to ask

Ad

Everything you wanted to know
about making R packages but
were afraid to ask
Emily Robinson
@robinson_es

Ad

Five Topics
Motivating
Making
Documenting
Improving
Marketing

Ad

Why make a
package?

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Check these out next

1 of 41 Ad
1 of 41 Ad

Everything you wanted to know about making an R package but were afraid to ask

Download to read offline

Why should you make a package? What tools can help you? How can you make your package better? How do you let people know about it? In this talk, given at NY R Conference 2019, I cover my answers to all these questions.

Why should you make a package? What tools can help you? How can you make your package better? How do you let people know about it? In this talk, given at NY R Conference 2019, I cover my answers to all these questions.

More Related Content

Everything you wanted to know about making an R package but were afraid to ask

  1. 1. Everything you wanted to know about making R packages but were afraid to ask Emily Robinson @robinson_es
  2. 2. Five Topics Motivating Making Documenting Improving Marketing
  3. 3. Why make a package?
  4. 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. 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. 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. 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. 8. How do you make a package?
  9. 9. Two helper packages
  10. 10. Create the package structure, add a function library(usethis) create_package(“~/Desktop/nyrconf”) use_r(“i_love_nyrconf”)
  11. 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. 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
  13. 13. View your documentation devtools::document() ?i_love_nyrconf
  14. 14. How do you document your package?
  15. 15. DESCRIPTION File
  16. 16. The Package Documentation Pyramid Name Title (one sentence) Description (one paragraph) README Vignette
  17. 17. What’s in a name?  Not taken on CRAN  Not too long  Is easy to google  Evokes what it does
  18. 18. Other considerations … https://twitter.com/hadleywickham/status/1008799676533964800
  19. 19. Title • Describes what the package does • One sentence, ideally < 65 characters
  20. 20. Description • One paragraph focused on the value of your package Summary sentence Benefits Main functions
  21. 21. README – Overview
  22. 22. README – Installation instructions
  23. 23. README – Examples
  24. 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. 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. 26. How can you improve your package?
  27. 27. “This worked fine before …”
  28. 28. Solution: Unit Tests
  29. 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. 30. How do you market your package?
  31. 31. Marketing is not a bad word
  32. 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. 33. Make a website with pkgdown • pkgdown::build_site()
  34. 34. Blog and tweet about it! • Use #rstats • Give a one line motivation • Can remix your README and Vignette
  35. 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. 36. If you’re successful …
  37. 37. Resources
  38. 38. Drum roll please …
  39. 39. There’s a new R packages book in the works!! https://r-pkgs.org/
  40. 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
  41. 41. Thank you! bit.ly/nyrconf19 @robinson_es hookedondata.org

Editor's Notes

  • 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.

×