ds.make {dsBaseClient}R Documentation

ds.make

Description

Makes (calculates) a new object in the R environment on the server side. ds.make is equivalent to ds.assign, but runs slightly faster. It defines a datashield object via an allowed function or an arithmetic expression hence creating a new object in the server side R environments. The function is a wrapper for the 'opal' package function 'datashield.assign'.

Usage

ds.make(toAssign = NULL, newobj = "newObject", datasources = NULL)

Arguments

toAssign

a character string specifying the function call or the arithmetic expression that generates the newObject. In general the string should be reasonably simple to avoid blocking by the parser and complex (many brackets) expressions can always be broken down into a series of simple steps - e.g. see example 1 below. If toAssign is a simple pre-existing data object, it will simply be copied and assigned as having a second name as specified by the newobject argument - e.g. see example 1 below. One bug identified

newobj

the name of the new object

datasources

specifies the particular opal object(s) to use, if it is not specified the default set of opals will be used. The default opals are always called default.opals. This parameter is set without inverted commas: e.g. datasources=opals.em or datasources=default.opals If you wish to specify the second opal server in a set of three, the parameter is specified: e.g. datasources=opals.em[2]. If you wish to specify the first and third opal servers in a set specify: e.g. datasources=opals.em[2,3]

Details

If no newobj name is provided, the new object is named 'newObject' by default, otherwise the name can be specified using the newobj argument. If the newObject is created successfully, the function will verify its existence on the required servers. Please note there are certain modes of failure where it is reported that the object has been created but it is not there. This obviously reflects a failure in the processing of some sort and warrants further exploration of the details of the call to ds.make and the variables/objects which it invokes. TROUBLESHOOTING: please note we have recently identified an error that makes ds.make fail and DataSHIELD crash. The error arises from a call such as ds.make('5.3 + beta*xvar', 'predvals'). This is a typical call you may make to get the predicted values from a simple linear regression model where a y variable is regressed against an x variable (xvar) where the estimated regression intercept is 5.3 and beta is the estimated regression slope. This call appears to fail because in interpreting the arithmetic function which is its first argument it first encounters the (length 1) scalar 5.3 and when it then encounters the xvar vector which has more than one element it fails - apparently because it does not recognise that you need to replicate the 5.3 value the appropriate number of times to create a vector of length equal to xvar with each value equal to 5.3. There are two work-around solutions here: (1) explicitly create a vector of appropriate length with each value equal to 5.3. In order to do this there is a useful trick. First identify a convenient numeric variable with no missing values (typically a numeric individual ID) let us call it indID equal in length to xvar (xvar may include NAs but that doesn't matter provided indID is the same total length). Then issue the call ds.make('indID-indID+1','ONES'). This creates a vector of ones (called 'ONES') in each source equal in length to the indID vector in that source. Then issue the second call ds.make('ONES*5.3','vect5.3') which creates the required vector of length equal to xvar with all elements 5.3. Finally, you can now issue a modified call to reflect what was originally needed: ds.make('vect5.3+beta*xvar', 'predvals'). Alternatively, if you simply swap the original call around: ds.make('(beta*xvar)+5.3', 'predvals') the error seems also to be circumvented. This is presumably because the first element of the arithmetic function is of length equal to xvar and it then knows to replicate the 5.3 that many times in the second part of the expression. The second work-around is obviously easier, but it is worth knowing about the first trick because creating a vector of ones of equal length to another vector can be useful in other settings. Equally the call: ds.make('indID-indID','ZEROS') to create a vector of zeros of that same length may also be useful.

Value

the object specified by the newobj argument (or default name newObject) is written to the serverside and a validity message indicating whether the newobject has been correctly created at each source is returned to the client. If it has not been correctly created the return object return.info details in which source the problem exists and whether: (a) the object exists at all; (b) it has meaningful content indicated by a valid class.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

##EXAMPLE 1
##CONVERT PROPORTIONS IN prop.rand TO log(odds) IN logodds.rand
#ds.make("(prop.rand)/(1-prop.rand)","odds.rand")
#ds.make("log(odds.rand)","logodds.rand")



##EXAMPLE 2
##MISCELLANEOUS ARITHMETIC OPERATORS: ARBITRARY CALCULATION
##USE DEFAULT NEW OBJECT NAME
#ds.make("((age.60+bmi.26)*(noise.56-pm10.16))/3.2")



##EXAMPLE 3
##MISCELLANEOUS OPERATORS WITHIN FUNCTIONS (female.n is binary 1/0 so female.n2 = female.n
##and so they cancel out in code for second call to ds.make and so that call is
##equivalent to copying log.surv to output.test.1)  
#ds.make("female.n^2","female.n2")
#ds.make("(2*female.n)+(log.surv)-(female.n2*2)","output.test.1") 
#ds.make("exp(output.test.1)","output.test")

## End(Not run)


[Package dsBaseClient version 5.0.0 ]