• Part A
  • R-packages – an introduction (10 minutes)
  • Structure and contents of R-packages (30 minutes)
  • From scripts to functions (20 minutes)
• Part B
  • Building a template package the prospective way (10 minutes)
  • Maintaining a package (20 minutes)

• Take some time to think of an arbitrary package.

Alternatively use devtools::create("path/to/package/pkgname")

Alternatively (DON'T) use package.skeleton(). It will create an overloaded package template that needs more modification.

• A new RStudio-project is started (file PACKAGE_NAME.Rproj)
• A template function is opened (the silly Hello World one)
• A minimal amount of package files is generated (see Files browser window)

• The R environment is completely empty

• Close and delete the template function and its documentation straight away.

• Inspect the NAMESPACE and DESCRIPTION file.

• The NAMESPACE contains only: exportPattern("^[[:alpha:]]+"), i.e., every function is exported!

• The DESCRIPTION file contains autogenerated content. Modify it so that it fits your needs.

• Configure the Build tools: Menu Tools > Project Options > Build Tools
  • make sure to check "Generate documentation with Roxygen".

• Click in the upper right section of RStudio at the "Build" tab.
  • "Build & Reload" will compile the package and restart R
  • "Check" will run the R-internal check routines
  • "More" well, will show you the above and some more options
• Click on "Check". See what happens. Are there any warnings? Notes? Errors?

• It is now time to add some functions to the package.

• Write one or two functions. Use all the information discussed before
  • Use roxygen2 tags
  • By the way, think of the DESCRIPTION components in detail
  • If you want, include an imported function
  • Create and document an example data set
  • Play (extensively) with all these text structure tags

• To share the package, you need to build a source version of it
  • Menu Build > Build Source Package
  • You find a PACKAGE_VERSION_tar.gz-file in your R directory
• Packages for Windows-users need to be compiled in a different way
  • The tedious way: CRAN website and Biostat description
  • The shortcut: Winbuilder, but ressources are precious!
• These packages are ready, they can be freely distributed as desired.

• Testing your functions
  • Either write test scripts (apart from the examples)
  • Or be holistic and rigorous
• What if Check stops with an error? See where the error happend:
  • If in the examples, then check the respective function
  • If in the overhead tests before, well, … google for it
• What if a package user reports an error?
  • Fix it and notify all relevant persons (potentially everyone)
  • Thus, use a versioning system (next section)

• Software lives, it evolves, it ages and it gets kicked by changed hardware.

• Thus, software needs to be maintained and updated. But by more than just fixing a bug and raising the version number.

• Maintenance should be handled as open, transparent and coherent as possible.

• Git is a perfect versioning tool, and R and RStudio perfectly align with it.

• Git is the version control system for your code
• GitHub is the online platform to share your code

• SmartGit is a local client software for Git (alternative to Git via console)

• Git and Github are far from being user friendly, but they are powerful

• It is very likely you use only a tiny fraction of the functionality

• GitHub makes sharing up to date software as easy as possible
• GitHub is a pillar of transparent, reproducible science
• GitHub paves the way for collaborative package/software development

• Git(Hub) makes spotting well-hidden coding accidents deliberately easy

• Further information about Git: well, I had not found time for everything :)

• Let us hope you have succesfully installed Git, e.g., via SmartGit
• Register yourself at Git, via console

git config --global user.name "YOUR FULL NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

• To check things;

git config --global --list

• Don't worry, this was only necessary once

• Menu Tools > Project Options > Git/SVN
• Select Git as Version Control Option

• Confirm and let RStudio restart itself

• Note the changes in the restarted version
  • A new icon in the menu bar (green plus, red minus, grey circle)
  • A new tab (Git) in the upper right window of RStudio

• Click on the Git tab in the upper right window

• The Git pane shows all items (files) that have experienced a change
• There are three categories:
  • Untracked (yellow ?)
  • Modified (blue M)
  • Deleted (red D)
• Click on icon Diff shows in-depth view on changes to a file

• That was it! All changes made will now be tracked.

• First things first: account for untracked items
  • Mark all untracked files and check them
  • Then click "Commit"
  • In the new window, you need to add a comment to the commit (Don't comment silly things, commits will be there for eternity)
• After clicking on "Commit" explore the Commit History (click on "History")
  • All changes are listed (green = added, red = deleted)

• So let us make some changes.
  • Add a new function.
  • Modify the silly "Hello World" function.
  • Build the package.
• Explore the Git pane
  • Which files are there?
  • Commit the changes.
  • Explore the history.

• Commits are the fundamental unit of version control in Git (like saving a file under a different name)
• Commit whenever you have solved an isolated issue but not before it is done properly
• Commit comments should allow understanding what was done and why it was done, after years

• Before you committed a change (but after saving the file), rightclick on the file to restore and choose "Revert"
• Use the history to trace back when something was changed longer ago
  • Copy the SHA (secure hash algorith, i.e. unique commit ID)
  • Use the console for restoring this commit (git checkout <SHA> <filename>)
  • Looks clumsy, right? See SmartGit slide for an alternative.

• RStudio covers only a very tiny fraction of the Git functionality
• SmartGit is much more elaborated – and complicated to use

• SmartGit is a powerful GUI for Git. Whatever you cannot do in RStudio, you can do it in SmartGit

• We installed SmartGit mainly for getting access to additional options

• Instead of using RStudio for tracking changes, we can use SmartGit as well

• What packages are and why they are like they are
• Structure/contents of a package

• How to turn a script into a function

• Creating a package from scratch
• Adding functions and their documentations

• Using Git via RStudio to maintain a package

• How to write "good" R-code for functions
• Including low level code and Shiny apps
• Tests and checks, good practice to ensure correct functionality
• How to submit a package to CRAN and GitHub
• Writing Vignettes
• Debugging strategies

It doesn’t matter if your first version isn’t perfect as long as the next version is better. (H. Wickham)