What is a package?
An R package is a collection of functions that are bundled together in a way that lets them be easily shared. Usually these functions are designed to work together to complete a specific task such as analyzing a particular kind of data. You are probably familiar with many packages already, for example ggplot2 or dplyr.
Packages can take various forms during their life cycle. For more details have a look at the “What is a package?” section of Hadley Wickham’s “R packages” book (http://r-pkgs.had.co.nz/package.html#package)
Why write a package?
Packages are the best way to distribute code and documentation, and as we are about to find out they are very simple to make. Even if you never intend to share your package it is useful to have a place to store your commonly used functions. You may have heard the advice:
If you find yourself reusing code then you should wait anymore to turn it into a function so that you don’t have to keep rewriting it (along with other benefits…).
The same applies to functions. If you have some functions you reuse in different projects then it probably makes sense to put those in a package. It’s a bit more effort now but it will save you a lot of time in the long run.
Of course often you will want to share your package, either to let other people use your functions or just so people can see what you have done (for example when you have code and data for a publication). If you are thinking about making a software package for public use there are a few things you should consider first:
Is your idea new or is there already a package out there that does something similar? If you have an idea, raise an issue to start the discussion asap!
If there is does your package improve on it in some way? For example is it easier to use or does it have better performance? Maybe check the existing packages and see if you can improve first the existing solution before starting a new one from scratch. UNHCR package developers are open to collaboration and you may be able to achieve more by working together.
How to develop packages?
We DO RECOMMEND to use fusen package to develop packages as it facilitates a lot peer review and enforces a series of good practices (example, unit testing..)
In addition, there are plenty of resources available to learn how to develop packages. See a list below:
- Writing an R package from scratch (Hilary Parker) https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/
- Writing an R package from scratch (Updated) (Thomas Westlake) https://r-mageddon.netlify.com/post/writing-an-r-package-from-scratch/
- usethis workflow for package development (Emil Hvitfeldt) https://www.hvitfeldt.me/blog/usethis-workflow-for-package-development/
- R package primer (Karl Broman) https://kbroman.org/pkg_primer/
- R Package Development Pictorial (Matthew J Denny) http://www.mjdenny.com/R_Package_Pictorial.html
- Building R Packages with Devtools (Jiddu Alexander) http://www.jiddualexander.com/blog/r-package-building/
- Developing R packages (Jeff Leek) https://github.com/jtleek/rpackages
- R Package Tutorial (Colautti Lab) https://colauttilab.github.io/RCrashCourse/Package_tutorial.html
- Instructions for creating your own R package (MIT) http://web.mit.edu/insong/www/pdf/rpackage_instructions.pdf
- How to Create and Distribute an R Package (Shian Su) https://medium.com/@shiansu/how-to-create-and-distribute-an-r-package-a296217435dc
- R Forwards Package Workshop (Chicago, February 23, 2019) https://github.com/forwards/workshops/tree/master/Chicago2019
- Write your own R package (UBC STAT 545) http://stat545.com/packages00_index.html
- R package workshop https://combine-australia.github.io/r-pkg-dev/
‘Stable-enough’ packages within {unhcrverse}
The list of mature projects includes set of packages to ease the production of statistical evidence and data stories. Even if not installable throught the main CRAN repository, those Packages are expected to follow the standards outlined in the CRAN policies.
However as those packages heavily relies on the benevolent time of the maintainers and, while wiating for for systematic third-party code review process set up, each those package might not be (yet!) fully CRAN-Check compliant…
unhcrverse includes packages related to
Design and branding such as unhcrdown: UNHCR templates for R Markdown, unhcrthemes: UNHCR branded theme for ggplot2 and data visualization colour palettes,
Data Access such as unhcrdatapackage: Use UNHCR Open data, ridl: API to connect to internal data source, robotoolbox: API to connect to Kobo Data Collection Server, rhdx: API to connect to Humanitarian Data Exchange and popdata: API to connect to the system for official statistic curation
Survey Data Processing such as HighFrequencyChecks: Perform High Frequency Check or kobocruncher: Process data crunching for survey dataset or XlsFormUtil: to work with multiple xlsform
You can install them all with the following:
install.packages("pak")
pak::pkg_install("unhcRverse/unhcRverse")
unhcrverse::unhcrverse()Deprecated projects
Any stable project where there is no maintainer working with UNHCR, or when the scope got filled by other better packages will be placed in the list of deprecated packages.
For instance:
koboloader got deprecated by kobocruncher
unhcrstyle got deprecated by unhcrdown and unhcrthemes