Project Setup

Overview

In this series of practicals you will develop the code to calculate diversity measures. You will have to choose the names of functions and variables in your code for yourself, and structure it appropriately, though some small amounts of guidance will be given.

Remember that these practicals constitute the “project” part of the course, which constitutes 50% of the marks, so well-structured and well-commented code, documented functions and demos that also generate clear reports of the results, are very important. Any of the in-course exercises that you decide to continue to work on after the end of the course should be completed in your own time.

R packages and GitHub

Your work must be written as an R package using git and pushed to a GitHub repository in the SBOHVM organisation as the last two practical series. Please make your repository private and for this project don’t add anyone as collaborators – this project is done on your own to assess how much you have learned on the course. You must commit a change at least at the end of each exercise (i.e. Projects 0, 1, 2, 3, 4 and 5) with sensible commit messages stating what you have just done. You are welcome (and indeed encouraged) to do more commits if this is useful to you, and it’s completely okay (and indeed normal) if you go back to earlier exercises and make further edits and commit them after completing later exercises.

Remember a few things:

• Libraries you use in your package (for example the data package) should be correctly added to your package as dependencies;
• Functions should be kept in the R folder inside the package and documented so that the documentation is available through R’s help system;
• Scripts for each project exercise should be stored in the demo folder. They should be available to run through the demo() function when we install the package, and we should be able to compile them into a report which will contain code and text blocks (and whatever else you wish) that tidily explains what is happening in the script.

Tasks

1. Create an initial empty R package called githubusernameDiversity in RStudio (remember to use only letters and numbers though) that uses git and is connected to a private repository in the SBOHVM organisation;
   • You will use this package for all of your remaining work in this project
2. Update the DESCRIPTION file with the correct information about yourself and the package;
3. Create a help file for the package in the R folder, and run devtools::document() and devtools::install() to make sure that the documentation works when you call ?githubusernameDiversity at the console once you have loaded the library by calling library(githubusernameDiversity);
   • Remember you will have to do this again every time you edit a function or demo in the package in subsequent exercises
4. Add our data package (“SBOHVM/soniamitchellBCI”) as a dependency of the package (or yours if you’re using it instead) – the usethis::use_dev_package() function will add the correct entries to the DESCRIPTION file, just like the usethis::use_package() function adds in normal (CRAN) packages;
   • Remember to do this with any subsequent packages that you decide to use later in the project
5. Import the data package into the package by adding the @import command to the package’s help file in the R folder that you made in step 3, above;
6. Add a license. It’s completely up to you what license you use. We probably recommend using the MIT license as it is very permissive in terms of other people reusing your work later for something as (relatively!) unimportant as these exercises. You can add the MIT license to your package by running usethis::use_mit_license() in your console, and you can investigate other licenses more broadly at https://choosealicense.com, and how to select them for your package at https://usethis.r-lib.org/reference/licenses.html.
7. Commit these changes and push them to GitHub.

You will need to much of this again in subsequent project exercises, for instance every time you need to add a new package dependency into your package.

Adding dependencies

A quick note on adding dependencies to your package, though this is also covered in the packaging guide on the RPiR website.

Note that for adding dependencies to your package, if you run this in the console:

usethis::use_package("ggplot2")
usethis::use_dev_package("RPiR", remote = "SBOHVM/RPiR")

it edits your DESCRIPTION file to add the CRAN ggplot2 package to your package’s dependencies and the RPiR package in the SBOHVM organisation on GitHub to your package’s dependencies as a package in development on GitHub. You may need to have already installed development packages in RStudio first to get this second command to work (using devtools::install_github("SBOHVM/RPiR") or devtools::install() locally). If you then add the following to the documentation in the R folder, this will mark the functions and data in those packages as usable by functions in your package:

#' @import ggplot2
#' @import RPiR

NB I am not suggesting you necessarily want to do this with these specific packages.