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

Pass either 'assign' or 'aggregate' as the second argument.

> 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:

> # Remove existing package
> dsadmin.remove_package(opals, 'dsBase')
>
> # Install new package
> dsadmin.install_package(opals, pkg='dsBase', gitref='3238776', silent=TRUE)
>
> # 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 server-side DataSHIELD package to the most recent versions on the respective master branches (as of 2015-03-12) as follows:

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