RPGM 2.0 Docs

R with RPGM

This is a page with subjects about developing in R within the RPGM software.

Paths and working directory

When the final user loads a program in the Client, a subfolder with the same name as the program’s filename is created. For example, if a user have set its output folder to C:/output, and your program is _insurancev2.pgm, then a folder C:/output/insurance_v2/ will be created, and will be the current working directory within R (you can check it through the R command getwd()).

If you want to access files shipped with your .pgm file (sourcing a R file, accessing images, csv files, etc…), you can do it with rpgm.pgmFilePath(). This also serves as a temporary folder. You can, for example, export an image to rpgm.pgmFilePath("image.png") for displaying it later in a GUI or in a report.

Sequences and steps

For a lot of RPGM R functions like gui.X or report.X, the first argument to pass to the function is the step where the element needs to be added or modified. This is where the rpgm.step() function is needed, it will create a variable representing a step within a sequence. The first parameter is the filename of the sequence and the second parameter is the name of the step.

For example, for hiding a widget with an unique ID nbMultiplier in a step with an unique ID Inputs in the sequence file sequences/main.pseq, the correct code is:

gui.hide(rpgm.step("sequences/main.pseq", "Inputs"), "nbMultiplier");

Also, during On Change event in GUIs, you can use "this" instead of the rpgm.step() function for pointing to the current GUI:

gui.hide("this", "nbMultiplier");

Positions

For gui.add and report.add functions, a position must be provided as a number. This number determines where the widget or the report element will be inserted. If you want your new item to be the first element, you must put 0 as the position parameter. For being second, put 1, and so on. Giving an empty string will append the element at the end. Here a better example with the addreport functions set:

# Our report has only one element: Main title
report.addText(my_step, "", ...);    # Our report is now: main title, text
report.addImage(my_step, 0, ...);    # Our report is now: image, main title, text
report.addEquation(my_step, 2, ...); # Our report is now: image, main title, equation, text
report.addTable(my_step, 2, ...);    # Our report is now: image, main title, table, equation, text

Error management from R

Here is a simple example where we want to import the data included in a selected file in a previous GUI (with a unique ID of _N\nPath).
The user can select a file with a wrong format or type a wrong file path for example, and this will induce a R error. To counter that, we must use the try function of R for testing if read.table failed or not. If it fails, a special error value will be returned, and we go back to the step where we ask the data to the user and tell him that there is a problem in the data.

The script after the GUI is:

N <- try(as.matrix(read.table(N_path, sep = ";")), silent = TRUE)

if(class(N) == "try-error")
{
    gui.showError(rpgm.step("main.pseq", "Input"), "N_path", "Unvalid path or data format");
    rpgm.setNextSequence(rpgm.step("main.pseq", "Input"));
    stop("Cannot import N Data, returning to the GUI")
}

The first line in the if block is the gui.showError() function. This function displays a red error message Invalid path or data format below the widget Npath. We then use rpgm.setNextSequence() to define where in the sequences RPGM should go after this script, so we set it to Input in the main.pseq file for going back to the GUI step. Finally, we immediately stop the R script with stop.

Here is what happens if the user enters a wrong data:

Client

A yellow triangle is shown in the top bar of the Client, meaning that a R error was detected, in this example this is due to the function stop() as it is a managed error.