User guide

Author Guideline

Outline of steps:

1. Uploading the Executable Research Compendium (ERC)
2. Create an R package in RStudio
3. Edit the UI bindings (connect ERC with R package)

1. Uploading the Executable Research Compendium (ERC)

1. Sign in on the platform
2. On the main page, upload a new ERC
   Note: To create an ERC, please follow the instructions on the o2r platform website.
3. Add usual metadata (Required, Optional, Spacetime tabs) and click SAVE

2. Create an R package in RStudio

Figure 1: a) Create a new package in RStudio b) Naming the R package

Note: The RStudio Server instance is running on localhost/rstudio.

1. In the RStudio Server Interface create a new blank package with package name ErcId (Fig. 1)
2. Go to the Files pane and navigate to the folder named R and open the file hello.R
3. Copy the contents of the script over to hello.R and make sure following requirements are met:
   • All the code that is required to be used to generate one output MUST be contained in a single function.
   • The function MUST return the object which represents the required output.
   • In the R script inside the new package, if there are external dependencies, the library() function MUST NOT be used. Instead, use the function requireNamespace().
   • If there are extra resources or data files required for the script to function it should be uploaded in a directory named inst which is to be placed in the root directory of the package.
     In order to access these files from the R script in the folder R, the system.file() function may be used in the following manner: system.file(“data_file_name”, package = “ERC_ID”). The argument package takes the name of the package as the value which in this case is the same as the ERC ID.
   • Use relative paths within the package to reference other files
   • It is a good practice to fill up the file DESCRIPTION with metadata related to the R package such as package version, author, description, license etc.
4. Define the parameter to manipulate in the function header as well as within the script.
5. Note down the name of the function that is used.
6. Navigate to the root folder of the package and open the file NAMESPACE.
   • In this file, use the function import() to list external packages used on separate lines.
   • The function defined in the R script has to be exported too. For this, use the function export()
7. Install the R package by clicking on Install & Reload (Fig. 2) in the Build pane or from the Build menu option.

Figure 2: OpenCPU RStudio environment

3. Edit the UI bindings (connect ERC with R package)

1. In the UI Bindings tab you can add a figure that shall allow interaction
2. Insert following information:
   • Figure title
   • Figure type (map or time series)
   • Function name for creating figure (name of the function of the R package uploaded to rstudio)
   • x-axis-label (text that should appear next to the x-axis)
   • y-axis-label (text that should appear next to the y-axis)
   • x-axis-parameter (column name containing x-values)
   • y-axis-parameter (column name containing y-values) (Fig. 3)
     Figure 3: Add figure metadata in UI Bindings
3. For a widget (e.g. a slider that allows the user to manipulate the figure) insert following information:
   • Default Value (original value used for computation)
   • Min Value (minimum value allowed)
   • Max Value (maximum value allowed)
   • Step size (intervals between min and max value)
   • Param Name (parameter name as defined in function header in R package)
   • Widget Type (only slider supported so far)
   • Widget description (description that will be shown to the reader) (Fig. 4)
     Figure 4: Add metadata to create a widget that will be used to manipulate the figure
4. Click ADD FIGURE TO BINDINGS
5. Click UPDATE

You can add multiple widgets for a single figure.
You can add multiple figures for an ERC.

Reader Guideline

Interact with visualisations:

1. On the o2r platform: Go to the paper page of the paper you would like to examine
2. On the right part of the screen select the tab MANIPULATE (Fig. 5)
3. Use the slider to set parameter value(s) that shall be used to recompute the visualisation
4. Press RUN WITH NEW PARAMETER(S) to recompute the visualisation and show the result (this might take some time as the visualisation needs to be computed before it can be shown)
5. Depending on the figure type you can select different visualisation types for comparison using the corresponding circular buttons on the right

• Time series
  Side-By-Side: The original time series and the changed will be shown in two graphs next to each other
  Combined: The original and changed time series will be shown together in one graph
• Maps
  Side-By-Side: The original and changed map will be shown next to each other (Fig. 5)
  Overlay: The original and changed map will be shown on top of each other. You can use a slider to expand or shorten the map shown at the top so that you are able to compare the maps.
  Peephole: The original map is shown completely while the changed map is only partly visible in a rectangular window laid on top of the original map. You move the window over the map using your mouse. The border colour of the map indicates how much difference is between the original and changed map in the movable window. The moving window is resizable.

You can switch between different figures clicking on the corresponding figure tab (underneath the main tab bar containing the MANIPULATE button).
If you want to download the manipulated figure click DOWNLOAD. A download of the time series or map images and a text file containing info about the parameters used will be provided.

Figure 5: Manipulate tab providing the comparison user interface