R scripts created for Data Studio must be written using the Script editor window.
This window is activated from the Script editor button on the main Data Studio toolbar:
The Script editor window has 3 tabs.
The General tab provides information on the script, rather like a script header. Items are:
- Name – This is the unique script name, once created, the name can’t be changed.
- Revision – (optional) Free text used to identify the status of the script (e.g., Draft, version 1.0 etc.)
- Author – (optional) Person or company that wrote the script and who is responsible for it.
- Last modified – (optional) Timestamp showing when the script was last changed. When you click on this box, a calendar widget will appear.
- Description – (optional) Free format text that can be entered to say something about the purpose of the script.
- Suppress warnings – When ticked, this fields will stop any popup warnings appearing (e.g., mismatched units) when the Run button is pressed.
The Parameter tab is used to create and maintain script parameters that map to the input and output variables in the main Data Studio Selection grid. The parameter names and types must match the parameters that the R script uses in its calculations.
Parameters are added with the Add Script Variable button and each is dragged from this window on to the Selection grid to map the input/output data to the R script.
See section on mapping parameters for more detail.
The Code tab allows you to write the actual R script. An existing R script can be pasted in here an modified, but note the following before trying to run it:
- The script must contain any required ‘library’ calls and is responsible for installing any package it needs.
- An R data frame, called ‘df’, is passed into the script. This contains all the input variables. They can be referenced by the prefix df$ (e.g., if the input script parameters are in1, in2, the input data is in df$in1 and df$in2).
The outputs are stored back to the database using a store() call that is part of the Bentley Open Scripting R framework. You can use: help(package="bentleyutils", topic="store") in R or RStudio for further details.
The format of store() is simply:
store(<object to store>, <exact name of mapped script parameter>, <data type>)
If successful, this call will store the results to the database and the framework will display the relevant output data on each tab.
Where the specific file type options are:
image - A .png picture, produced by R specific alternatives: image_png - .png format image file image_jpeg - .jpg format image file text - text data (if this is csv-formatted text, the results will be displayed as a table on the tab). specific alternatives: text_tsv – tab-separated table format text_csv - comma-separated table format timeseries - timestamped real data values xy - scatterplot data