In genexplain/geneXplainR: An R interface for the geneXplain platform

The geneXplainR package provides an R client for the geneXplain platform [1]. The geneXplain platform is an online toolbox and workflow management system for a broad range of bioinformatic and systems biology applications. The platform is well-known for its upstream analysis [2], that has been developed to identify causal signalling molecules on the basis of experimental data like expression measurements.

geneXplainR is based on and extends the rbiouml package. A goal of this project is to add functionality that helps to make building R pipelines that use the geneXplain platform easier.

Basic usage

A typical session with the geneXplain platform consists of signing into a valid user account followed by performing computational analyses in the user workspace.

Login

The platform login is reachable through this web page. It is necessary to create a user account to obtain login credentials. A user account can be created for free here. Through the web interface one can also access the platform as demo user which does not require any registration, but data and analyses results are public.

Having a user account, a session with the geneXplainR client commences with loading the library and submitting login credentials to the server of choice using the gx.login function.

library(geneXplainR)
# Words within placeholders (<...>) need to be replaced.
gx.login("<server>","<user>","<password>")

One can end a session using the gx.logout function. However this may not be so important, because sessions expire after some time.

gx.logout()

Analysis

Two functions invoke analysis tools or workflows, gx.analysis and gx.workflow. In addition, there are functions to obtain a list of available tools or to inspect their parameters, gx.analysis.list and gx.analysis.parameters.

#... after login
# Get the list of available tools
gx.analysis.list()

# Show parameters for a specific tool
gx.analysis.parameters("Convert table")

# Invoke an analysis with the tool
gx.analysis("Convert table", list(sourceTable = "data/Projects/Example/Data/example_table",
                                  species     = "Human (Homo sapiens)",
                                  sourceType  = "Genes: Ensembl",
                                  targetType  = "Genes: Gene symbol",
                                  outputTable = "data/Projects/Example/Data/example_output_table"))

The gx.analysis* functions provide an interface to the platform tools. Those tools are developed to carry out a single type of task such as converting a table or calculating network clusters for a gene set. Usually, a data analysis consists of many steps invoking various tools in sequence, converting output to valid input for the step, and so forth. To replay and automatize sequences of tasks the platform has an important type of functionality called workflows. The geneXplain platform hosts a growing portfolio workflows for various kinds of analyses in the folder analyses/Workflows, but one can also create custom workflows.

An easy way to find out about the available geneXplain workflows is to use the gx.ls function, which lists contents of a specified folder, to browse the folders under analyses/Workflows. The same function can be used to inspect the parameters for a workflow. Since gx.workflow accepts parameter names as they are shown in the web interface, one can also open a workflow in the web interface to find out about the necessary parameters.

#... after login
# Get list of workflows in 'Common'
gx.ls("analyses/Workflows/Common")

# Get parameters for specific workflow
gx.ls("analyses/Workflows/Common/Gene set enrichment analysis (Gene table)")

# Invoke workflow
gx.workflow("analyses/Workflows/Common/Gene set enrichment analysis (Gene table)",
            list("Input table"              = "data/Projects/Example/Data/example_table",
                 "Enrichment Weight Column" = "Column name",
                 "Species"                  = "Mouse (Mus musculus)",
                 "Results folder"           = "data/Projects/Example/Data/example_output"))

Furthermore, we add more and more functions dedicated to specific tools or workflows, so that parameters can be documented and inspected the usual R-ways, e.g. have a look at gx.vennDiagrams which invokes the platform tool Venn diagrams.

library(geneXplainR)
?gx.vennDiagrams

Data import and export

From the R client, table import and export simply works with the functions gx.put and gx.get, respectively. For other data types and formats, the functions gx.import and gx.export apply a specified importer or exporter to upload or download files.

Put and get functions are used as follows:

#... after login
# Words in placeholders (<...>) need to be replaced with suitable values.
gx.put("data/Projects/<project name>/Data/<destination folder>", data)
data <- gx.get("data/Projects/<project name>/Data/<source folder>/<platform table>")

Import

The gx.import function takes as arguments the local file to import, the platform folder to import into (usually starting with data/Projects), the importer to use and a list with parameters for the specified importer.

The list of available importers can be obtained with the gx.importers function and for a specific importer and the platform folder to import into one can inspect the importer parameters using the gx.import.parameters function.

Files for which no dedicated importer exists can still be uploaded using the Generic file importer. Identifying and applying an importer may look like this:

#... after login
# Words in placeholders (<...>) need to be replaced with suitable values.
gx.importers()
gx.import.parameters("data/Projects/<project name>/Data/<destination folder>", "<importer name>")
gx.import("<local file>", "<platform destination path>", "<importer>", list("<parameter>"="<value>"))

Export

Export is possible by specifying the platform item to export, an exporter, parameters of the exporter and the local destination file to the gx.export function.

Available exporters can be listed using the gx.exporters function and parameters for a specific exporter and a platform item to export can be viewed using the gx.export.parameters.

Identifying and applying an exporter may look like this:

#... after login
# Words in placeholders (<...>) need to be replaced with suitable values.
gx.exporters()
gx.export.parameters("data/Projects/<project name>/Data/<item to export>", "<exporter name>")
gx.export("<platform item>", "<exporter>", list("<parameter>"="<value>"), "local file")