ds.coxSLMA: Fit a cox proportional hazard Model (coxph) with pooling via...
In sofack/dsPackagesClient: Performs survival analysis in DataSHIELD

Description Usage Arguments Details Value Author(s) Examples

View source: R/dscoxSLMA.R

Fits a cox proportional hazard Model (coxph) on data from single or multiple sources with pooled co-analysis across studies being based on SLMA (Study Level Meta Analysis).

ds.coxSLMA(
  formula = NULL,
  weights = NULL,
  dataName = NULL,
  checks = FALSE,
  maxit = 30,
  combine.with.mixmeta = TRUE,
  datasources = NULL
)

`formula`	an object of class formula describing the model to be fitted. For more information see Details.
`weights`	a character string specifying the name of a variable containing prior regression weights for the fitting process. `ds.coxSLMA` does not allow a weights vector to be written directly into the coxph formula.
`dataName`	a character string specifying the name of an (optional) data frame that contains all of the variables in the coxph formula.
`checks`	logical. If TRUE `ds.coxSLMA` checks the structural integrity of the model. Default FALSE. For more information see Details.
`maxit`	a numeric scalar denoting the maximum number of iterations that are permitted before `ds.coxSLMA` declares that the model has failed to converge. For more information see Details.
`datasources`	a list of `DSConnection-class` objects obtained after login. If the `datasources` argument is not specified the default set of connections will be used: see `datashield.connections_default`.
`mixmeta`	If TRUE and numstudies > 1, the regression coefficient and Variance-Covariance matrix are pooled across studies using fixed-effects meta-analysis framework.

ds.coxSLMA specifies the structure of a cox proportional hazard Model (coxph) to be fitted separately on each study or data source. Calls the serverside functions coxSLMADS1 (aggregate) and coxSLMADS2 (aggregate).ds.coxSLMA sends a command to every data source to fit the model required but each separate source simply fits that model to completion (ie undertakes all iterations until the model converges) and the estimates (regression coefficients) and their Variance covariance matrices from each source are sent back to the client and are then pooled using SLMA across studies using the mixmeta function (from the mixmeta package) using fixed optimisation method.But once the estimates and Variance-covariances are on the clientside, the user can alternatively choose to use another meta-analysis package in any way he/she wishes, to pool the coefficients across studies. In formula Most shortcut notation for formulas allowed under R's standard coxph() function is also allowed by ds.coxSLMA.

coxph can be fitted very simply using a formula such as:

y~a+b+c+d

which simply means fit a coxph with y as the outcome variable (Survival object calculated separately using ds.Surv and stored in the server) and a, b, c and d as covariates. By default all such models also include an intercept (regression constant) term. The dataName argument avoids you having to specify the name of the data frame in front of each covariate in the formula. For example, if the data frame is called DataFrame you avoid having to write: DataFrame$y~DataFrame$a+DataFrame$b+DataFrame$c+DataFrame$d

The checks argument verifies that the variables in the model are all defined (exist) on the server-site at every study and that they have the correct characteristics required to fit the model. It is suggested to make checks argument TRUE only if an unexplained problem in the model fit is encountered because the running process takes several minutes.

Server functions called: coxSLMADS1, and coxSLMADS2.

The serverside aggregate functions coxSLMADS1 and coxSLMADS2 return output to the clientside. This is precisely the same as the coxph object that is usually created by a call to coxph() in native R and it contains all the same elements (see help for coxph in native R). Because it is a serverside object, no disclosure blocks apply. However, such disclosure blocks do apply to the information passed to the clientside. In consequence, rather than containing all the components of a standard coxph object in native R, the components of the coxph object that are returned by ds.coxSLMA include: a mixture of non-disclosive elements of the coxph object reported separately by study included in a list object called output.summary; and a series of other list objects that represent inferences aggregated across studies.

the study specific items include:

coefficients: a matrix with 5 columns:

First: the names of all of the regression parameters (coefficients) in the model
second: the estimated values
third: the exponentials of the estimated values
fourth: corresponding standard errors of the estimated values
fifth: the ratio of estimate/standard error
sixth: the p-value treating that as a standardised normal deviate

formula: model formula, see description of formula as an input parameter (above).

CoefMatrix: the matrix of parameter estimates.

vcovmatrix: the variance-covariance matrix of parameter estimates.

weights: the name of the vector (if any) holding regression weights.

Nmissing: the number of missing observations in the given study.

Nvalid: the number of valid (non-missing) observations in the given study.

Ntotal: the total number of observations in the given study (Nvalid + Nmissing).

data: equivalent to input parameter dataName (above).

call: summary of key elements of the call to fit the model.

na.action: chosen method of dealing with missing values. This is usually, na.action = na.omit - see help in native R.

iter: the number of iterations required to achieve convergence of the coxph model in each separate study.

Once the study-specific output has been returned, ds.coxSLMA returns a series of lists relating to the aggregated inferences across studies. These include the following:

num.valid.studies: the number of studies with valid output included in the combined analysis

Sofack, Ghislain.(Based on ds.glmSLMA by Paul Burton for DataSHIELD Development Team)

## Not run: 

  require('DSI')
  require('DSOpal')
  require('dsBaseClient')

  # Example 1: Fitting coxph for survival analysis
  # For this analysis we need to load survival data from the server

  builder <- DSI::newDSLoginBuilder()
  builder$append(server = "study1",
                 url = "http://192.168.56.100:8080/",
                 user = "administrator", password = "datashield_test&",
                 table = "SURVIVAL.EXPAND_NO_MISSING1", driver = "OpalDriver")
  builder$append(server = "study2",
                 url = "http://192.168.56.100:8080/",
                 user = "administrator", password = "datashield_test&",
                 table = "SURVIVAL.EXPAND_NO_MISSING2", driver = "OpalDriver")
  builder$append(server = "study3",
                 url = "http://192.168.56.100:8080/",
                 user = "administrator", password = "datashield_test&",
                 table = "SURVIVAL.EXPAND_NO_MISSING3", driver = "OpalDriver")
  logindata <- builder$build()

 # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D")


 # The 'cens' variable should be an interger/ numeric

ds.asInteger(x.name = "D$cens",
             newobj = "CENS",
             datasources = connections)

# Create the serverside survival object
ds.Surv(time = "D$survtime",
        event = "D$cens",
        newobj = "Survobj"
        datasources = connections)


ds.coxSLMA(formula = Survobj ~ noise.56 + pm10.16 + bmi.26 + age.60 ,
           data = "D",
           weights = NULL,
           checks = FALSE,
           maxit = 20,
           datasources = connections)

 # Clear the Datashield R sessions and logout

datashield.logout(connections)


## End(Not run)