In the user tutorial and in the code examples in the documentation of each datashield function, logging in to VMs or remote servers can be accomplished using the
data() function to access the required login details. For example:
logindata object is available because it is part of the (in this case) dsBaseClient package.
In the source code, it is stored as a .rda file in the
data/ folder of the package. See the dsBaseClient code on GitHub.
Creating new data objects to be bundled with a client package is a three step process:
1. Create the object in R
For example, construct a dataframe containing datashield login details:
> server <- c("study0", "study1")
> url <- c("192.168.56.100:8080", "192.168.56.101:8080")
> user <- "administrator"
> password <- "password"
> table <- c("DASIM.DASIM", "DASIM.DASIM")
> DASIM_logindata <- data.frame(server,url,user,password,table)
2. Save the object as a .rda file
> save(DASIM_logindata, file='DASIM_logindata.rda', ascii=TRUE)
ascii=TRUE creates a text file, rather than a binary file.
3. Add to the client package
Move the .rda file into dsBaseClient/data, add and commit the file, then push to GitHub.
Documenting packages and data
Documentation for datashield functions is written as a header to the function itself. That is to say, as a header within files like
roxygen2 package is used to turn these headers into the
.Rd files found in the
man/ folder for each package. Those
.Rd files can be (re)generated by the
devtools::document() function or equivalently by the
When a package is installed, this documentation is available from
?<function name> or
What if you want to write documentation for something other than a function?
- The whole package.
- Some data that is included with the package (such as the 'logindata' for the VMs).
.R file in the
R/ folder. But instead of documenting a function, document
To illustrate, consider the file
#' The base DataSHIELD client package
#' This packages contains the basic client functions for using DataSHIELD
#' For a list of all functions available in dsBaseClient, run:
@docType package indicates that this documentation refers to the dsBaseClient package itself, rather than a function within it.Alternatively, you could use the tag
@docType data to indicate that the documentation refers to some data bundled with the package.