Skip to content

RGG XML

Jump to bottom Edit New page
Antje Janosch edited this page Nov 7, 2022 · 15 revisions

RGG stands for "R GUI Generator" and is a definition of a xml-file made to wrap an R script, expose it's parameter in a graphical user interface (configuration dialog) and make it a such available as template. This work has been published in BMC.

Table of Contents

Documentation

Detailed information about the concept, description of the xml-tags and examples are available on the official rgg web-page.


RGG for KNIME

The RGG model was adapted to fit into KNIME and is stored in it's own git repository.

Header

The header is extracted by KNIME's template utilities. The cathegory allows to arrange the templates in a meaningful directory tree. The preview allows to see the user an example in the template selection tab of the nodes configuration dialog. Some of the elements defined in the header can be referred to later in the actual rgg-xml by using the following key words:

  • name: $$$TEMPLATE_NAME$$$
  • description: $$$TEMPLATE_DESC$$$ 
 #########################################################################
 # name: Bar Plot
 # author: Holger Brandl
 # category: basic/barplots
 # preview: simplebarplot.png
 Creates a barplot. This can be used to visualize zscores, CVs, etc.<br>
 ######

Tags

Most of the xml tags are described in the official rgg web-page. However, to fit KNIME's default dialog components, there are a few special tags:

panellistbox 

 <panellistbox label="Numerical attributes" items="$$$NUM_ATTRIBUTES$$$" span="full"/>

It's options are the the standard ones.

filechooser

Tag for file choosing GUI is: 

  <filechooser label="CSV" description="Csv files" extensions="csv" fileselection-mode="files-only"/>

If you want to choose a directory use "directories-only" as mode: 

  <filechooser label="Image Folder" description="Folder with images" fileselection-mode="directories-only"/>

Key words (column chooser)

embedding one of the following keywords in the template allows referring to different content:

description key word deprecated (old) key word
all numeric table columns $$$NUM_ATTRIBUTES$$$
all string table columns $$$STR_ATTRIBUTES$$$ $$$FACTORS$$$
all table columns $$$ALL_ATTRIBUTES$$$ $$$PARNAMES$$$
template name $$$TEMPLATE_NAME$$$
template description $$$TEMPLATE_DESC$$$

Flow variables

Flow variables from KNIME can be used within templates. To accesss the variable use:

  • FLOWVAR(variable_name)
The template could look like this: 
 <textfield label="template text:" var="my_flow-variable" data-type="text" default-value= "" size="10" />

If you type FLOWVAR(variable_name) in the GUI, then the R Code would look like this: 

 my_flow-variable <- "FLOWVAR(variable_name)"

Finally the FLOWVAR(variable_name) will be replaced with the variable value. 

 my_flow-variable <- "variable_value"

Currently only certain characters are allowed as variable name:

  • alphabetic characters, numbers, spaces, and underscores
Currently the RexEx that searches for flow variable expressions looks like this:
  • FLOWVAR[(][\w\d\_]*[)]
  • ...in other words: use only characters, numbers and under scores
Dont use:
  • minus, spaces, dots, brackets, etc. (e.g. -, ,.,(,),+,... dont work)
The flow variables of KNIME can be also used in the same way in the Output tab of the Plot and Snippet nodes. As file name for the output you could define e.g.
  • ...path/MyPlot_FLOWVAR(variable_name)_beautiful.png
Please make sure that no strange characters within the variable values cause the node to fail:
  • e.g. variable value = my "cool" data, (the " will cause the R code to fail)
  • e.g. variable value = Count*(objects) , (the * will cause the R code to fail if used as a file name)

Python Specifics

The XML tag "checkbox" from RGG sends back a "TRUE" or "FALSE", which is the way booleans are expressed in R. However, in python booleans are expressed as "True" or "False" which leads to errors in the python script. Here are two workarounds for usage of the checkbox tag in python templates:

  • 1. The template could look like this (set the XML in "" to handle it as text):
 show_legend = "<checkbox label="show legend" selected="true" span="full"/>"

...and your python code should look like this: 

 if show_legend == "TRUE":
  • 2. Use the extended attributes of the checkbox tag:
 show_legend = <checkbox label="show legend" selected="true" return-value-by-selected="True" return-value-by-notselected="False"/>

Template example

Bellow is a simple example of a R-template and the resulting configuration dialog. Once the template is written and referenced in the KNIME preferences of your KNIME installation (Preferences > KNIME > R-Scripting), the template is loaded when the Plot node is dragged from the node repository to the workbench.


screenshot of a rgg template file partitioned with colored rectangles: red: rgg-tags, blue: configuration dialog, green: script



template tab of the R-plot node configuration dialog



Script Editor tab of the R-plot node configuration dialog



How to Develop a template?

The KNIME team host a server with example workflows. When connected in the group "99_Community" you can find R-Scripting, Python-Scripting or R-Scripting workflows. Downloading one of those gives you the bases to work through the instructions bellow.

  1. open a workflow containing some example data
  2. get the "Open in *" node from the node repository and and connect it with the node delivering the test data.
  3. Execution of the "Open in *" node should open a console of the scripting language framework.
  4. The data from the input table is stored as variable "kIn". Play around with it until you have a working version of the code performing the task you want.
  5. Use and existing template and modify it to fit your task at hand (copy past the code in it and modify and add the xml tags for the interface.
  6. Save the template somwhere in a text file and add the url to it in the KNIME Preferences > KNIME > * Scripting. Don't forget to put a ";"after the last entry.
  7. pull a new scripting node (plot or snippet) on the workbench and connect it for input.
  8. Open the configuration dialog.
  9. If the elements from the template are displayed correctly in the "script editor" tab, the xml was correct. Otherwise there will be an error message in the window.
  10. Configure the inputs.
  11. Execute the node.
If the node throws error messages this is a way to localize the error:
  1. Use an "Open in *" node with the same input as the plot/snippet node
  2. open the configuration dialog of the plot/snippet node
  3. in the "script editor" tab click on the "Unlink from Template" button.
  4. Now you should see pure script code (no xml) where all the xml-stuff has been replaced by the inputs from the dialog.
  5. copy paste this code into the console started by the "Open In *" node and see if it executes.
  6. Once sources of errors are detected, the "Edit Template" button can be used to modify and test further.
If the configuration of the node throws error after loading/editing a template: 
 ERROR! The given template is not a valid rgg-xml document
 or
 Invalid settings: java.lang.NullPointException
  1. Then your RGG code has bugs! Check these things:
  2. Typos! <.../> or <hbox>...</hbox> correct? use any program that does syntax high-lighting
  3. The best way of trouble shooting is to take an old/working template and copy/paste step-by-step the new RGG-code and find out where it fails
  4. Check that quotation is correct:
    1. " is ok, ” doesn't work (SmartQuotes substitution by TextEdit/MAC)
    2. but, ” is allowed e.g. as text in separator and label area expressions and in commented code
  5. Some special characters are forbidden in RGG:
    1. even in commented code(#)!
    2. or in column names in KNIME
e.g.: 
 <,>,&

If you really have to use these characters within the RGG code, this is the right way of using them: 

 &lt;, &gt;, &amp;

Further information: http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

Check that quotation is correct: " is ok, ” doesn't work (SmartQuotes substitution by TextEdit/MAC).
These characters are ok to use: 

 -,+,=,_,(,),[,],?,!,",',.,,,;,:,$,/,\ ...and all other numbers and letters (both character lists are not complete!)
Add a custom footer
Add a custom sidebar
Clone this wiki locally