Getting started

Introduction

This is a tutorial outlining how to develop functions for DataSHIELD. DataSHIELD is released under a GPL3 license, and we will accept contributions of new functionality to be included in our software base giving due credit to DataSHIELD function/package authors. New developments are done on your own computer, checks are made and then these are pushed to your branch on Github. 

DataSHIELD developers are expected to have some basic knowledge on how to create R functions as well as sound understanding of the statistical methods being implemented.

 Instructions for Windows

Git.exe location

Ensure that Git installs in C:\Program Files\Git or write down the filepath to the default location of installation. On managed university computers Git normally installs somewhere like C:\Users\USERNAME\AppData\Local\Programs\Git\bin

  • Keep default settings and tick the box for daily for Git Windows updates

  • Keep default settings but select Use Git from Windows Command Prompt

  • use default options e.g. Use the OpenSSL Library , Checkout Windows-style; Use MinTTY, enable file system caching, enable Git Credential Manager
  • Create a GitHub account for Windows.
  • generate a new ssh key 
    • windows requires ssh keys to be here: C:\Users\USERNAME\.ssh\id_rsa
    • you can choose to set a password to access this key (you will need this each time you develop in R studio, or you can choose to set no passphrase (so won't need to enter a passphrase each time in R Studio). Remember the passphrase.

Install R Studio

Configuring R Studio

R Version

  • Ensure you are using the latest version of R by going to the menu Tools > Global options > General and browse to ensure you are using the latest version of R.

Sync with Git

Once Git is installed you need to activate it in R Studio:

  • Go to menu ToolsGlobal Options 
  • Click the Git/SVN tab from the left hand side.
  • Click Enable version control interface for RStudio projects
  • If necessary:
    • enter the path for your Git.exe file (the location where Git was installed)
    • add the filepath to the key you created (typically located at C:\Users\USERNAME\.ssh\id_rsa)

Setting up default R libraries

  • Check where R libraries are installed
.libPaths()
[1] "C:/Users/USERNAME/Documents/R/win-library/RVERSION"
[2] "C:/Program Files/R/R-VERSION/library"
  • Set R to use local libraries only
.libPaths("C:/Users/USERNAME/Documents/R/win-library/RVERSION")
  • You can check you have access to all the DataSHIELD libraries by clicking the Rstudio lower right quadrant tab packages and you should be able to see DataSHIELD packages there e.g. dsBaseClient.

Installing developer dependancies

  • Install the dsBetaTest packages
#R
install.packages("dsBetaTestClient", repos='http://cran.obiba.org', type='source')
library(dsBetaTestClient)

  • Use default settings until you get to the select additional tasks. Make sure add rtools to system path is ticked. 


  • Ensure the following filepath is added to the top
C:\Rtools\bin;
  • check the following lines are somewhere, or add them at the bottom. 
C:\Program Files\Git\cmd;
C:\Program Files\R\R-3.5.1\bin
  • REMOVE any lines containing the following if they occur:  mingw_32 or mingw_64 in it 

Ensure each filepath has a  at the end of it except the last line.

  • Verify that Rtools can be used in R by restarting R Studio and opening it again. 
  • Run a check to ensure that C:\\Rtools\\bin  appears in PATH (there will be other stuff here too). 
#R
Sys.getenv('PATH')

> Sys.getenv('PATH')
[1] "C:\\Program Files\\R\\R-3.5.1\\bin\\x64;C:\\Rtools\\bin;C:\\WINDOWS\\system32;C:\\WINDOWS;C:\\WINDOWS\\System32\\Wbem;C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\;C:\\WINDOWS\\System32\\OpenSSH\\;C:\\Program Files\\GLEAMviz-6.7\\libs;C:\\Program Files\\Git\\cmd;C:\\Program Files\\R\\R-3.5.1\\bin;C:\\Users\\Dimitris Avraam\\AppData\\Local\\Microsoft\\WindowsApps;"


  • Install the pkgbuild R package if you do not already have it and check it believes Rtools is installed

#R
install.packages("pkgbuild")
pkgbuild::has_build_tools(debug = TRUE)
  • If this returns FALSE, go to C:\Rtools and use the uninstaller unins000.exe to uninstall Rtools and reinstall following the instructions carefully. 
  • Verify that your toolchain works by executing the code below in R:
  • Install the package devtools and roxygen by running the below command in R or Rstudio.
install.packages("devtools", dependencies = TRUE)
install.packages("roxygen2", dependencies = TRUE)


Instructions for Linux

  • Install Git 
  • GitHub account for Windows or for Linux
  • The DataSHIELD training environment is already installed. 
  •  by following the guide here including installation of R Studio. 
    • Linux users will need to install the following libraries in the Unix Shell, for example using the Ubuntu Terminal command:
    sudo apt install  libssl-dev, libgit2-dev, libxml2-utils,  libxml2-dev
  • If you are a Windows user follow this guide to install Rtools
  • Install the package devtools and roxygen by running the below command in R or Rstudio.
install.packages("devtools", dependencies = TRUE)
install.packages("roxygen2", dependencies = TRUE)
install.packages("Rtools", dependencies = TRUE)

Prerequisites

  • Install Git 
  • GitHub account for Windows or for Linux
  • The DataSHIELD training environment is already installed. 
  •  by following the guide here including installation of R Studio. 
  • Linux users will need to install the following libraries in the Unix Shell, for example using the Ubuntu Terminal command:
sudo apt install  libssl-dev, libgit2-dev, libxml2-utils,  libxml2-dev
  • If you are a Windows user follow this guide to install Rtools
  • Install the package devtools and roxygen by running the below command in R or Rstudio.
install.packages("devtools", dependencies = TRUE)
install.packages("roxygen2", dependencies = TRUE)
install.packages("Rtools", dependencies = TRUE)

Get set up, get set up, get set up ...before anything

It is important to ensure your computer is fully set up before embarking into any developments. Otherwise you are most likely going to face some errors at some stage and the support team might not be able to help because it is often very difficult to identify the sources of errors originating from wrong settings. If you faced with difficulties in getting set up please contact the support team at datashield@newcastle.ac.uk

Welcome to DataSHIELD development!