Platform tools and parameters
There are three main types of platform applications
- Analysis tools that cover functionality like data preparation, conversion, or data analysis
- Importers that import certain data types into the platform workspace
- Exporters that export data from the platform workspace
The programming and commandline interfaces provide functions to list available analysis tools, importers and exporters for a given platform server and user account and furthermore to retrieve information about their input options/parameters.
In the following, we focus on geneXplainR and commandline utilities provided by the genexplain-api package. Corresponding methods of the Java API are listed here.
We recommend to use genexplain-api commandline tools for tool listings and parameters also when working mainly with geneXplainR.
Listing tools and parameters using geneXplainR
The example code below shows the geneXplainR functions to
list available applications and to get information about parameters
for a platform tool, gx.analysis.list
and gx.analysis.parameters
.
The output of gx.analysis.list
is a table containing tool names in the Name
column and a column with the program group which corresponds to the name
of the analysis tool folder in which a tool can be found in the graphical
web interface.
The gx.analysis.parameters
output, shown below for Annotate table, is
a table with parameter names as row ids and a column with short descriptions.
For importers and exporters, corresponding functionality is implemented by
gx.importers
and gx.exporters
which list available import and export functions,
respectively, and by gx.import.parameters
as well as gx.export.parameters
which
extract parameter information for specified importers and exporters,
respectively.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Listing tools and parameters using the commandline program apps
The commandline program apps can retrieve the list of available platform tools as well as an extended table that additionally contains information about tool parameters.
For a simple listing of tools the input JSON file may look as follows, where server
, user
and password
properties need to be replaced with valid input values.
1 2 3 4 5 6 7 |
|
The corresponding shell command is as follows, assuming the JSON object above is stored in a file named simple_tool_listing.json.
1 |
|
The output consists of a list of analysis tools preceded by the program group to which a tool is assigned, e.g. Statistical analysis. The group name corresponds to the analysis tool folder in the graphical web interface where a tool can be found. Please note that in function calls only the tool name without the program group name is required.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
The output can be extended to Galaxy tools integrated
in the specified platform instance by setting the withGalaxy
property to true
.
Furthermore, the output can include information about tool parameters by setting
the withParameters
property to true
.
An example output with parameters is shown below. The output is a table with the following columns.
Column name | Description |
---|---|
Tool folder/name | String consisting of program group and tool name separated by /. The program group corresponds to the graphical interface folder where the tool can be found. |
API name | The tool name that needs to be specified in API calls, e.g. gx.analysis of geneXplainR |
Parameter name | The parameter name that needs to be specified in API calls, e.g. in a parameter list for gx.analysis |
Short description | Short description of the parameter |
Type | Data type of the input, e.g. data-element-path expects a string which is a platform path of data element |
Class | Java class of a data element, e.g. ru.biosoft.table.TableDataCollection expects a path to refer to a tabular data |
Required | Indicates if a value must be specified |
Description | Possibly longer description of the parameter |
Output from apps including parameters
Tool folder/name | API name | Parameter name | Short description | Type | Class | Required | Description |
---|---|---|---|---|---|---|---|
Data manipulation/Annotate diagram | Annotate diagram | inputDiagram | Input diagram | data-element-path | biouml.model.Diagram | true | Diagram to annotate |
Data manipulation/Annotate diagram | Annotate diagram | table | Annotation table | data-element-path | ru.biosoft.table.TableDataCollection | true | Table with diagram ids and annotations |
Data manipulation/Annotate diagram | Annotate diagram | column | Annotation column | code-string | false | Column with annotations | |
Data manipulation/Annotate diagram | Annotate diagram | outputDiagram | Output diagram | data-element-path | biouml.model.Diagram | false | Path to store annotated diagram |
Data manipulation/Annotate table | Annotate table | inputTablePath | Experiment | data-element-path | ru.biosoft.table.TableDataCollection | true | Table with experimental(test) data |
... | ... | ... | ... | ... | ... | ... | ... |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | miRNAs | miRNAs | data-element-path | ru.biosoft.table.TableDataCollection | true | miRNAs |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | targetGenes | targetGenes | data-element-path | ru.biosoft.table.TableDataCollection | true | targetGenes |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | siteModelCollection | siteModelCollection | data-element-path | ru.biosoft.bsa.SiteModelCollection | true | siteModelCollection |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | ensembl | ensembl | code-string | false | ensembl | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | scoreType | scoreType | code-string | false | scoreType | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | backgroundGenes | backgroundGenes | data-element-path | ru.biosoft.table.TableDataCollection | true | backgroundGenes |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | from | from | code-string | false | from | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | to | to | code-string | false | to | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | targetScanDB | targetScanDB | data-element-path | ru.biosoft.access.SqlDataCollection | true | targetScanDB |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | miRNAPromoterScoreThreshold | miRNAPromoterScoreThreshold | code-string | false | miRNAPromoterScoreThreshold | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | targetGenePromoterScoreThreshold | targetGenePromoterScoreThreshold | code-string | false | targetGenePromoterScoreThreshold | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | miRNATargetScoreThreshold | miRNATargetScoreThreshold | code-string | false | miRNATargetScoreThreshold | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | scoreThreshold | scoreThreshold | code-string | false | scoreThreshold | |
miRNA analysis/miRNA feed forward loops | miRNA feed forward loops | outTable | outTable | data-element-path | ru.biosoft.table.TableDataCollection | false | outTable |
Fetching parameter information for specific tools using the parameters utility
The program parameters of the genexplain-api package extracts parameter information for specified platform tools.
The following example JSON fetches parameter descriptions for Annotate table and
the Galaxy tool variant_effect_predictor. The server
, user
and password
properties need to be set with valid input values.
1 2 3 4 5 6 |
|
The following shell invokes parameters with the JSON object above stored in a file named specific_tool_parameters.json.
1 |
|
The output is printed to standard output (optionally, an additional JSON parameter outfile
can
be provided to specify a local output file) and is (partially) shown below. It consists of a JSON object with
one property for each platform tool that was specified in the tools list.
The input options of a platform tool are contained in a JSON array, each represented by an object describing the input option. The order of input parameters in this array is the same as in the graphical web interface.
The displayName
property shows the parameter title that appears in the graphical web interface. However,
the parameter name that needs to be specified in an API call is the name
property.
E.g. the first parameter of Annotate table with displayName
Experiment has the name
inputTablePath. The latter
needs to be used in function calls.
An input option object provides further valuable information such as the type of data that is expected. E.g.
the Experiment needs to be provided as a type
data-element-path, which means a path for a
data element in the platform workspace and data element on that path must be a table (elementClass
...TableDataCollection).
If an input option expects a value from a predefined list, the available values to select are also listed, see e.g. output and description for Functional classification.
The geneXplainR method to fetch parameter information for platform tools is implemented in the
function gx.analysis.parameters
. However, the parameters commandline tool provides more details
about each input option. Therefore, we recommend its use also for geneXplainR projects.
Output produced by parameters for platform tools
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
|