R-tools

This page is a knowledge crystal of subtype method. The page identifier is Op_en5247
Moderator:Ehac (see all)
Upload data {{#opasnet_base_link:Op_en5247}}

R-Tools is a MediaWiki extension that allows registered Opasnet users to run R code directly from a wiki page.

Question

How should R-based modelling be performed in a MediaWiki environment?

Answer

Examples and help

• op_fi:Psykologikysely
• Help:Drawing graphs
• op_fi:Mikrobien määrä pohjavedessä

Libraries

Opasnet R software has some additional libraries installed e.g. for plotting and connecting to external databases. More libraries can be installed on request with proper reasons. List of currently installed libraries:

• OpasnetUtils
• OpasnetUtilsExt
• soRvi
• ggplot2
• xtable
• distr [1]

Usage

R-tools uses <rcode> tags. Any R code written between these tags can be run from wiki page using the "Run code"-button. Press the button and new window (or tab) opens up showing the status and the results of the run in real time. An example code that counts one plus one using R:

<rcode>
1+1
</rcode>

Parameters

Some optional parameters can be given to <rcode> tag as described below.

• name - Code block can be identified by giving some name for it. This is mandatory in some situations and therefore recommendable practice.
• embed - By default run results are shown in a new browser window. If 'embed' is defined as '1' then results are shown next to variable inputs and "Run code" button.
• live - Define as '1' to get live embedded results. This means absence of the "Run code" button in favor of running code instantly when any of the inputs get changed.
• label - Label for the "Run code" button.
• graphics - If the code is meant to draw any graphs then define graphics to '1'.
• showcode - By default the code is hidden under 'Show code'-link (value 0). If this parameter is defined as '1', then the code is shown when the page is entered. If the value is '-1', then the code cannot be shown by any means (no visible link).
• variables - Allows user to input values for named variables in R code. Inputs will be displayed in a box below the actual R code in wiki page. Variables syntax is described in its own chapter on this page.
• include - Includes external <rcode> block to code. Code needs to be identified by "name" parameter before it can be included. More than one code blocks can be included. The syntax is "page:<wiki page>|name:<code name>|...".
• store - Run results might get erased from the server after some time, unless this parameter is set to '1'. In other words; by default the run results are temporary in nature.
• recall_inputs - Define this as '1' and inputs of the code will be "autocompleted" with latest run values whenever page is visited. Input values are Opasnet user specific and will not be stored or retrieved if user has not logged into wiki.

Variables syntax (legacy way)

Each variable needs three attributes separated with | (pipe) character. These attributes (in correct order) are variable name in code,variable description in wiki page and default value. Variable triplets must also be separated with pipe. An example R code with two defined attributes calculates the area of a rectangle:

<rcode variables="width|Width of the rect|10|height|Height of the rect|10">
# The area of the rect is
width *  height
</rcode>

Note that variable default value can also be a string or even an array (e.g. c(1,2,3) or 'Some name').

Variables syntax (new way with more possibilities)

Each variable can have a set of attributes. Attributes must be given as name/value pairs, separated with colon (:). Each variable must have at least one attribute, which is called "name" (variable name in R code). Optionally "description" attribute can be defined to give users more information about the variable, and "default" can be used for giving variable some predefined input. Order in which the attributes are given is not relevant. All variables are considered as text type by default, providing users a input field for writing. There are other possible types too (date, select, checkbox...) and the list of possibilities may grow longer in future. Each type of a variable have custom set of attributes. Variable type can be defined by giving it "type" attribute. Different types for variables are described in their own chapter on this page. Each attribute must be separated with a vertical bar (aka pipe) character. Example code of two variables with default values:

<rcode variables="name:width|default:10|name:height|description:Rect height|default:10">
# The area of the rect is
width *  height
</rcode>

Categories and conditional categories

It is also possible to assign variables to categories. Just define "category" attribute for desired name and variable will be in its own input box with that title. Categories can also be conditional if "category_conditions" attribute is set. Syntax is <variable name>;<value1>;<value2>;...;<value3> where <variable name> is the variable to be checked for given conditions <value1..n>. If any of the conditions are met (OR logic) then the category box will be shown, otherwise it will be hidden. Following example has conditional categories "Fruits" and "Cars" which can be hidden or visible, depending on the value selected for the variable "sel1":

Select type: - select - Fruits Cars Fruits and Cars Fruits Select fruits: Banana Orange Pineapple Cars Select cars: Porsche Ferrari Lamborghini + Show code- Hide code # Print selected variable values sel1 sel2 sel3

<rcode embed=1 name='cond_test' variables="
name:sel1|
description:Select type|
type:selection|
options:;- select -;'fruits';Fruits;'cars';Cars;'fruits_and_cars';Fruits and Cars|
name:sel2|
description:Select fruits|
type:checkbox|
options:'banana';Banana;'orange';Orange;'pineapple';Pineapple|
category:Fruits|
category_conditions:sel1;'fruits';'fruits_and_cars'|
name:sel3|
description:Select cars|
type:checkbox|
options:'porsche';Porsche;'ferrari';Ferrari;'lamborghini';Lamborghini|
category:Cars|
category_conditions:sel1;'cars';'fruits_and_cars'">
# Print selected variable values
sel1
sel2
sel3
</rcode>

Variable types

This chapter describes all the implemented variable types.

default

This is the default type if "type" attribute is not present. Renders a text field where users can input any text. Given input will be assigned to R variable as is, making it possible to use this type for inputting strings, numbers, vectors etc. Optionally "default" attribute can be given to insert predefined value to text field.

text

Otherwise equal to the default type but the given value will be encapsulated with quotes when assigned. This forces the variable to be string in R code.

textbox

Like the text type, but renders a text area element which allows several lines of text to be inputted instead of just one.

password

Like the text type but user input is masked and the line defining the variable is excluded from the run results.

date

Renders three select-elements and calendar icon (pops up a calendar window) for choosing a day, month and year. Given date will be assigned to R variable as date (as.Date). Optionally "default" attribute can be used for setting default date and "options" to give range (from and to dates separated by semicolon). Dates must be given in ISO 8601 format (YYYY-MM-DD).

datetime

Like the date type but extended with three select-elements (hours, minutes and seconds) for time. Default must be given in ISO 8601 format (YYYY-MM-DD hh:mm:ss).

select

Renders a drop down element with options defined by "options" attribute. Options must be given as value/name pairs separated with semicolon ('value1';Name one;'value2';Name two...). Selected value will be assigned into R variable. NOTE: values can be strings, numbers or even vectors. Default selection can be defined with "default" attribute.

slider

Renders a slider element to select a number from a user defined range. Use "options" attribute to define min, max and step (in this order, separated with semicolon). Default selection can be defined with "default" attribute.

filelist

Renders a drop down element with wiki-uploaded file names as options. Options can be narrowed down by using the "options" attribute, which takes a regular expression. E.g. "options:^test.*png$" would populate a selection of file names which start with "test" and end to "png". Default selection can be defined with "default" attribute.

checkbox

Renders a group of checkbox elements defined by "options" attribute. Options must be given as value/name pairs separated with semicolon ('value1';Name one;'value2';Name two...). Selected values will be assigned into R variable as vector. NOTE: values can be strings, numbers or even vectors. Default selections can be defined with "default" attribute (separate multiple values with semicolon).

table

Renders a text area element where table from excel (or equivalent) can be pasted into. Pasted table will be shown in table form after a second or two from pasting. R automatically assigns pasted table into a data.frame object.

hidden

Renders nothing, but still assigns "default" attribute's value to variable. This kind of variables can be very helpful when there is need to assign variables for included code blocks.

location

Renders a small Google Maps -window where the location of the Opasnet user will be pinpointed. This input is meant to be used via mobile device with GPS and HTML5 capable browser (iPhones and most of the Android devices should work at least). Location coordinates will be passed to R as vector, where the first value is latitude and the second is longitude.

Example code

The example code below prints out the user selected values for variables a,b,c and d. Press the 'Run code'-button to execute.

a: b: 12345678910111213141516171819202122232425262728293031.123456789101112.203420332032203120302029202820272026202520242023202220212020201920182017201620152014 Fruit: Banana Orange Kiwi Cars: Ferrari Porsche Lamborghini Slaider: + Show code- Hide code # Print out the variable values a b c d e

Live example code

The code below demonstrates the live mode where code runs automatically whenever input is changed.

Breaks: + Show code- Hide code hist(faithful$eruptions, probability = TRUE, breaks = as.numeric(breaks), xlab = "Duration (minutes)", main = "Geyser eruption duration")

Giving parameters in an URL

For an R code, you can give parameter values in an URL. In other words, you can create auto-filled forms where the possible default values are overwritten with your inputs. The syntax is the following:

http://en.opasnet.org/w/<Page name>?<code_name>[variable_name]=<value>&<code_name>[variable_name]=<value>&...#<Subheading>

Examples:

• As a clickable URL: [2]
• The same content as text. It can be copied to a browser:

  http://en.opasnet.org/w/Handprinter?add[email]=1&add[phone]=2&add[actionname]=3&add[actioncontext]='Home'&add[category]='Infrastructure change'&add[actiondescription]=4&add[benefits]=5&add[quantification]=6&add[activity]='A'&add[subactivity]='A01'#Calculations

• If the url has scandinavian characters, the browser should understand it. However, if you want to use tag <a> to create a nice link, this is how you should show the characters. The url contains value 'Tilinpäätös' for variable työ:

  <a href="http://fi.opasnet.org/fi/Kohdistamo/Pikaleima?auto[ty%C3%B6]='Tilinp%C3%A4%C3%A4t%C3%B6s'">Tilinpäätös</a>

  Tilinpäätös

Notes:

• The format of the value given must relate to the variable type, for example 7 for a text field in an URL means '7' but in a default field it means 7.
• You can input values into several variables and also into several R codes on that page. Inputs are separated by & in the URL.
• Typical special characters [, ], space, and ' in the URL may be replaced with %5B, %5D, %20, and %27, respectively. Other characters in hexadecimal format may be used as well. See eg. [3].
• Optionally, there may be the subheading. It is placed at the end of the URL, preceded by #.
• By making the R code live (parameter live=1), i.e. activating by itself when the page is downloaded, it is possible to make an URL that automatically uploads the data into Opasnet Base. This can be used to create APIs where the API is designed to produce an URL with the content needed and browse the URL.
• You can create complex URLs and then make QR codes out of them. This way, you can create pre-filled forms that are activated semi-automatically by reading the QR code with a mobile phone.

Related files

<mfanonymousfilelist></mfanonymousfilelist>