The opaladmin package

The opaladmin package contains a number of useful functions to aid development. It contains functions that allow one to query and manipulate the server-side datashield packages from R (rather than through the opal web interface).

Load package and login

$ R
> library(opaladmin)
> opals <- opal.login('administrator', 'password', url='${OPAL_URL}:8080')

Where $OPAL_URL is the IP address of, for example, one of the test environment VMs such as 192.168.56.100

To logout:

> opal.logout(opals)

Query which server-side DataSHIELD methods are available

You can use the dsadmin.get_methods() function to get information about the methods and packages that are installed on Opal.

Pass either 'assign' or 'aggregate' as the second argument to see information about these two classes of methods. For example:

> dsadmin.get_methods(opals, 'assign')

	name	            type	class	        value	                    package	version
1	as.character        assign	function	base::as.character          dsBase      3.0.1
2	as.null             assign	function	base::as.null               dsBase      3.0.1
3	as.numeric          assign	function	base::as.numeric            dsBase      3.0.1
4	asFactorDS          assign	function	dsBase::asFactorDS          dsBase      3.0.1
5	asListDS            assign	function	dsBase::asListDS            dsBase      3.0.1
6	asMatrixDS          assign	function	dsBase::asMatrixDS          dsBase      3.0.1
7	attach              assign	function	base::attach                dsGraphics  3.0.1
8	c                   assign	function	base::c	                    dsBase      3.0.1
9	cDS                 assign	function	dsBase::cDS                 dsBase      3.0.1
10	cbindDS             assign	function	dsBase::cbindDS             dsBase      3.0.1
11	changeRefGroupDS    assign	function	dsBase::changeRefGroupDS    dsBase      3.0.1
12	complete.cases      assign	function	stats::complete.cases       dsBase      3.0.1
13	dataframeDS         assign	function	dsBase::dataframeDS         dsBase      3.0.1
14	exp                 assign	function	base::exp                   dsBase      3.0.1
15	list                assign	function	base::list                  dsBase      3.0.1
16	listDS              assign	function	dsBase::listDS              dsBase      3.0.1
17	log                 assign	function	base::log                   dsBase      3.0.1
18	recodeLevelsDS      assign	function	dsBase::recodeLevelsDS      dsBase      3.0.1
19	rowColCalcDS        assign	function	dsBase::rowColCalcDS        dsBase      3.0.1
20	subclassDS          assign	function	dsBase::subclassDS          dsBase      3.0.1
21	subsetDS            assign	function	dsBase::subsetDS            dsBase      3.0.1
22	sum                 assign	function	base::sum                   dsBase      3.0.1
23	unlist              assign	function	base::unlist                dsBase      3.0.1

Update server-side packages to a particular git commit

For development you may want to use more up-to-date, but not yet released, versions of the DataSHIELD server packages from github.

For example, DataSHIELD version 3.0.0 was released on July 9 2014 but you may wish to work on the dsBase package and all the modifications that have been made on the master branch up until January 3 2015. You can see the full history of the master branch of dsBase on github. Each commit in the history can be identified by a seven character code (actually, the first seven characters of a SHA1 hash). For the Jan 3 commit this is: 3238776

With this information you can update the dsBase package in Opal:

1. Remove existing package

> dsadmin.remove_package(opals, 'dsBase')

2. Install new package

> dsadmin.install_package(opals, pkg='dsBase', gitref='3238776', silent=TRUE)

3. Publish the package's methods

> dsadmin.set_package_methods(opals, pkg='dsBase')

This can be repeated (using the appropriate commit reference) for each server-side DataSHIELD package.

Below is a simple wrapper function for this process:

dsadminwrapper.update_to_commit <- function(opals=NULL, Base=NULL, Stats=NULL, Graphics=NULL, Modelling=NULL) {

    # load library
    library(opaladmin)

    # get argument options
    gitref.base <- Base
    gitref.stats <- Stats
    gitref.graphics <- Graphics
    gitref.modelling <- Modelling

    # remove package
    dsadmin.remove_package(opals, pkg='dsModelling')
    dsadmin.remove_package(opals, pkg='dsGraphics')
    dsadmin.remove_package(opals, pkg='dsStats')
    dsadmin.remove_package(opals, pkg='dsBase')

    # install new package
    # we wrap this in try() because we want to ignore the errors that are
    # sometimes produced even though the command succeeds.
    try(dsadmin.install_package(opals, pkg='dsBase', ref=gitref.base), silent=TRUE)
    try(dsadmin.install_package(opals, pkg='dsStats', ref=gitref.stats), silent=TRUE)
    try(dsadmin.install_package(opals, pkg='dsGraphics', ref=gitref.graphics), silent=TRUE)
    try(dsadmin.install_package(opals, pkg='dsModelling', ref=gitref.modelling), silent=TRUE)

    # publish package methods
    dsadmin.set_package_methods(opals, pkg='dsModelling')
    dsadmin.set_package_methods(opals, pkg='dsGraphics')
    dsadmin.set_package_methods(opals, pkg='dsStats')
    dsadmin.set_package_methods(opals, pkg='dsBase')
}

Using this, we can update all the DataSHIELD packages in an Opal server to the most recent versions on their respective master branches (as of March 12, 2015) as follows:

> dsadminwrapper.update_to_commit(opals, Base='3238776', Stats='6f7f6da', Graphics='e9cfbe2', Modelling='e9e7848')