r_plugin collection for MADS

This project provides a Source, a Filter and a Sink plugin for MADS. The plugins provide a way to embed an R interpreter in the MADS network. They works analogously to the MADS Python agent.

Required MADS version: 2.4.0.

Supported platforms

Currently, the supported platforms are:

• Linux
• MacOS
• Windows

Package install

with MADS v2.4.0 or later, install with:

mads package --install r.plugin

NOTE: the pre-compiled package dynamically links to the R shared library: In some cases, your system may have a different version of R installed, and the plugin may not work. In that case, you can build the plugin from source (see below).

Install from binaries

Linux and MacOS:

cmake -Bbuild -DCMAKE_INSTALL_PREFIX="$(mads -p)"
cmake --build build -j4
sudo cmake --install build

Windows:

cmake -Bbuild -DCMAKE_INSTALL_PREFIX="$(mads -p)"
cmake --build build --config Release
cmake --install build --config Release

Multi-driver plugin

This is a multi-driver plugin, which means that the same plugin can be used as a source, a filter or a sink. The driver to use is determined at runtime by the calling MADS agent (mads source, mads filter or mads sink). The plugin's kind() is used to define the INI section name, which is r_source, r_filter or r_sink respectively (can be overridden with the --name CLI option).

INI settings

The plugin supports the following settings in the INI file:

[r_filter]
use_renv = false # use renv for package management
init_script = "/path/to/script.R" # Mandatory path to the R script
r_output_mode = "stdout" # or "buffer"

All settings are optional; if omitted, the default values are used.

R script details

The R script (loaded by the init_script config path), must define a valid R function, whose name and signature depends on the type of plugin:

• a filter: there must be a load_data(list) function that receives a list of values (converted from JSON) and stores them internally, and a process() function that takes no arguments and returns a R list (which is automatically converted to JSON object)
• a source: there must be a get_output() function that takes no arguments and must return a list (automatically converted to JSON)
• a sink: there must be a load_data(list) function that takes a list as a single argument; that list represents the JSON received by the sink agent

Regardless its type, the script may optionally define a set_params(list) function that receives the list corresponding to the JSON ocject passed during plugin startup.

Notes on functions:

• load_data(list): in sinks and filters is the function that loads data from network into the R script; it receives a list (generated from the incoming JSON) and it is expected to store it internally in the script. The returned value might be TRUE (success), FALSE (falure), or a string like success, failure, retry, error, critical
• get_output(): in sources, must return a valid list and takes no arguments. The returned list may contain the field return_type, which may be TRUE (success), FALSE (falure), or a string like success, failure, retry, error, critical.
• process(): in filters, elaborates the data stored by load_data() and returns a valid list as result, taking no arguments. The returned list may contain the field return_type, which may be TRUE (success), FALSE (falure), or a string like success, failure, retry, error, critical.

For the meanings and effects of the return types, see the comments in the source code files src/r_[source|filter|sink].cpp.

---