ds.changeRefGroup {dsBaseClient}R Documentation

Changes the reference level of a factor


This function is similar to R function relevel.


ds.changeRefGroup(x = NULL, ref = NULL, newobj = NULL,
  reorderByRef = FALSE, datasources = NULL)



a character, the name of a vector of type factor.


the reference level


the name of the new variable. If this argument is set to NULL, the name of the new variable is the name of the input variable with the suffixe '_newref'.


a boolean that tells whether or not the new vector should be ordered by the reference group (i.e. putting the reference group first). The default is to not re-order for the reasons explained in the 'details' section.


a list of opal object(s) obtained after login in to opal servers; these objects hold also the data assign to R, as dataframe, from opal datasources.


In addition to what the R function does, this function allows for the user to re-order the vector, putting the reference group first. If the user chooses the re-order a warning is issued as this can introduce a mismatch of values if the vector is put back into a table that is not reordered in the same way. Such mismatch can render the results of operations on that table invalid.


nothing is returned to the client, the new object is stored on the server side.


Isaeva, J.; Gaye, A.

See Also

ds.cbind Combines objects column-wise.

ds.levels to obtain the levels (categories) of a vector of type factor.

ds.colnames to obtain the column names of a matrix or a data frame

ds.asMatrix to coerce an object into a matrix type.

ds.dim to obtain the dimensions of matrix or a data frame.



  # load that contains the login details

  # login and assign all the stored variables
  # (by default the assigned dataset is a dataframe named 'D')
  opals <- datashield.login(logins=logindata,assign=TRUE)

  # Example 1: rename the categories and change the reference with re-ordering
  # print out the levels of the initial vector

  # define a vector with the new levels and recode the initial levels
  newNames <- c('normal', 'overweight', 'obesity')
  ds.recodeLevels(x='D$PM_BMI_CATEGORICAL', newCategories=newNames, newobj='bmi_new')

  # print out the levels of the new vector

  # by default the reference is the first level in the vector of levels (here 'normal')
  # now change and set the reference to 'obesity' without changing the order (default)
  ds.changeRefGroup(x='bmi_new', ref='obesity', newobj='bmi_ob')

  # print out the levels; the first listed level (i.e. the reference) is now 'obesity'

  # Example 2: change the reference and re-order by the refence level
  # If re-ordering is sought, the action is completed but a warning is issued.
  ds.recodeLevels(x='D$PM_BMI_CATEGORICAL', newCategories=newNames, newobj='bmi_new')
  ds.changeRefGroup(x='bmi_new', ref='obesity', newobj='bmi_ob', reorderByRef=TRUE)

  # clear the Datashield R sessions and logout


[Package dsBaseClient version 4.1.0 ]