Community Spring Cleaning week is here! Join your fellow Maveryx in digging through your old posts and marking comments on them as solved. Learn more here!

Alteryx Designer Desktop Knowledge Base

Definitive answers from Designer Desktop experts.

A Cheat Sheet of Functions to Use in the R Tool

SydneyF
Alteryx Alumni (Retired)
Created

With the installation of the Predictive Tools comes one of the most versatile tools in the known Alteryx-verse.Behold, the mighty R Tool.

2018-06-29_15-18-43.png

The R Tool can be used to run any R code from Alteryx Designer. The R tool comes with a few Alteryx-specific R packages that allow you to use the R tool seamlessly in a workflow, or even create an R-based macro. To assist you in these endeavors, we've developed the R Tool Cheat Sheet with these functions, which you can download to have as your very own.

2018-07-02_15-27-27.png

In this article, I will review each of functions and information included in the cheat sheet with a little more detail.

R Tool Inputs and Outputs

The most basic component of working with the R Tool is reading in and writing out data to and from the R Tool. This is done, intuitively, with the read.Alteryx() and write.Alteryx() functions. The first argument of the read.Alteryx() function is the connection number you are reading in, written as a string (the quotations are mandatory). Just like how the connection numbers are displayed in the Designer Canvas, the syntax includes a # before the connection number.

2018-06-13_11-25-40.png

You can stream in data it two different modes with the optional mode argument. By default, data will be read in as an R data frame (mode ="data.frame") but you can also stream data in as a list (mode = "list"), which is useful for bringing in spatial objects.

The read.Alteryx.First() and read.Alteryx.Next() functions allow you to “chunk” your input data by providing an argument that specifies the number of rows you want to read in. Reading in the first chunk of data as a data frame would look something like this:

the.data  

You can use a loop with the read.Alteryx.Next() function to read in the remainder of the data. You will need to develop the logic and stopping criteria of the loop. You can read more about this, and bringing data into the R Tool in general, in part one of theConcentra Introduction to the R Toolblog series.

Writing out data from the R Tool is accomplished with the write.Alteryx() function. The two arguments in this function are (1) the object you’d like to write out, and (2) which of the five output anchors you would like it to be written to. The anchor argument is numeric, and should not have quotes around it.

write.Alteryx(data.out, nOutput = 1)

Reading In and Writing Out R Objects

Streaming records in and out is pretty straight forward, but to read in or stream out an R Object (say, a model you developed in R), you will first need to convert the object to a format that can be passed in and out of the Alteryx Engine. To convert a model object to a format that Alteryx can handle, first you need to create a blank list, and then save the object as a part of that list. The code to do this is as follows:

#first, create a blank list with two slots the.obj  

the.obj can now be safely written out using the write.Alteryx() function!

If you want to work with an object that has already been serialized with this method, then you’re looking for the unserializeObject() function. Provide the object as a character type to the unserializeObject function, and it will return a usable R object.

Obj  

Writing Out Plots

Writing out a plot from the R Tool is possible with the AlteryxGraph() function. You can provide detailed specifications on the size and resolution of the plot with the graphWHR() function.

The first argument of graphWHR is inches, which can be set to True or False, depending on what units you would like your graph dimensions to be specified in. Depending on if you set this to True or False, you will use either in.w and in.h or cm.w and cm.h for providing the width and height of the output plot as numeric values. The unused parameters should be set to NULL. The resolution can be set to one of three options, "1x", "2x", or "3x". These options are multiples of 96 ppi(pixels per inch), with 1x = 96 ppi, 2x = 192 ppi and 3x = 288 ppi). When set to equal TRUE, the print.high argument effectively increases 3x to 6x (576 ppi) resolution.

The following code would create parameters for a 4x4 plot with 288 ppi resolution.

WHR  

The output of graphWHR is a list that contains the resulting width, height, and resolution, and can be used as arguments in the AlteryxGraph function, which like the write.Alteryx() function defines the output anchor for the plot to be written to, as well as the target dimensions of the plot.

AlteryxGraph(1, width = WHR [1], height = WHR[2], res = WHR[3], pointsize = 9)

Plot code following this function will be written out to the specified anchor.

plot(c(1,2,3,4), c(1,2,3,4))

To make sure no pesky windows pop up, or irrelevant messages make way to your Results Window, use dev.off() wrapped by invisible().

invisible(dev.off())

Messages

Now that you have the basics of moving data in and out of the R Tool, you can get fancy by writing out messages to the Alteryx result’s window.

AlteryxProgress() is a nifty function that lets you set updates in how close the tool is to finishing running the code in 25% (0.25) increments.

AlteryxProgress(0.25)

AlteryxMessage allows you to write full notes to the Alteryx Results Window. This is handy for passing through errors and warnings. You can set the msg.costs (messages consists) argument to four different settings; msg.costs$INFO for information (written in black), msg.costs$WARNING to send through a warning (written in yellow), msg.costs$FIELD_CONVERSION_ERROR (written in Orange) or msg.costs$ERROR (scary red writing). It is important to note here that none of these settings, even the error, will stop the R code from attempting to execute. This function is just here to deliver messages.

priority.consts (priority consists) has three options; priority.consts$LOW, priority.consts$MEDIUM, and priority.consts$HIGH. The LOW priority will only be displayed in the results window if the R Tool is visible on the canvas in the workflow currently being run. The MEDIUM priority sends messages to the results window if the R Tool is on the canvas, or if it is within a macro. The HIGH priority will display regardless of the R Tool’s relationship to the workflow.

Here we are just writing a little note – the message is set as info, and the priority as low.

AlteryxMessage("Hi, how are you?",  msg.costs$INFO, priority.consts$LOW)

If you do want to halt executing the script, choose the stop.Alteryx() function instead. Here, we have written to stop the code, with a particularly unhelpful error message.

stop.Alteryx("IT’S BROKEN!")

Which Version of R is Alteryx Using?

The underlying version of R that the Predictive Tools install changes with different Alteryx releases. R version impacts which versions of packages are compatible with your instance of R, which can impact available functions or syntax. It is always best to develop code in the same version that you intend to use it in.

You can check theRversion easily with this slick function:

R.Version()$version.string

Or, refer to the chart included in the Cheat Sheet.

test.png

Interface Tools & Environmental Variables

There are three types of variables you can access from within the R Tool. They are Question Constants, Engine Variables, and User Variables. The syntax to pull in this information to R is the same for all three: %VariableType.% where VariableType is the type of variable (Question Constant, Engine Variable, or User Variables), and is the name of the specific variable being used. The Value is what that specific variable represents.

2018-06-28_16-20-04.png

To get information passed by an Interface Tool, you would use the following code:

%Question.InterfaceToolName%

The name of the interface tool can be found and changed in the Annotation Tab of the Tool’s Configuration Window.

2018-06-25_16-18-56.png

I’ve configured this Check Box Tool to ask the user if the tool Is awesome. Here is the code I wrote to go along with it.

if ('%Question.ThisToolIsAwesome%' == "False"){ stop.Alteryx(“You’re WRONG”)} else { AlteryxMessage(“Proceed”, msg.costs$INFO, priority.consts$MEDIUM)} 

Metadata

You may have run in to this error with the R Tool before.

There is no valid metadata for the outgoing connection 1. Run the workflow to generate valid metadata.

Passing Metadata in and out of the R tool needs to be done separately from reading in or writing out the data. The metainfo functions only work when AlteryxFullUpdate = TRUE, where AlteryxFullUpdate is a global variable for R that indicates if the workflow is being refreshed, or doing something else (like being run, or modified).

If else statements work nicely with the global variable AlteryxFullUpdate to conditionally run the metainfo functions.

if(AlteryxFullUpdate){Code if True}else{Code if False}

To stream in a connected input’s metadata, use the read.AlteryxMetaInfo() function, with the connection string value (e.g., “#1”) of interest.

To write out metadata from the R Tool, use the write.AlteryxAddFieldMetaInfo() function. By default, this function only writes out metadata for a single column. The first argument for this function is the number of the output anchor you want to pass out metadata to. This function has a bunch of optional arguments that allows you to pass different pieces of metadata downstream. Any combination of name, fieldType, size, scale, source, and description can be used. Please see the R Tool Help Documentation Update/MetaInfo > Optional Parameters for full details.

write.AlteryxGraphMetaInfo() Streams out plot metadata from R Tool to the specified anchor.

A super basic use of this functionality might look something like this:

if(AlteryxFullUpdate){  write.AlteryxAddFieldMetaInfo(nOutput = 1, name = "One", fieldType = "Double")  }else{  One  

This code will conditionally push out metadata or write out the actual output data, depending on AlteryxFullUpdate is True or False.

If you would like to see more, there is a great Interworks Blog Post on MetaInfo in the R Tool.

Installing Packages

One of the very cool things about R are the community developed packages. R packages are a user created collection of functions. If you need a specific statistical functionality (or really any type of functionality), there is most likely already an R package that does what you need. When installing packages from the R Tool, be sure to specify the repository option, or the install will fail.

install.packages("pkg", repos = "http://cran.rstudio.com")

As a bonus, the following function will conditionally install packages, depending if they are already present in the R library or not. This is useful for building macros or workflows you intend to share that use R code, because it will only install the package the first time the tool is used.

cond.install  

Now all you need to do is call this function for whatever packages are needed for your script.

cond.install("dplyr")

Developing R Code for Alteryx

Developing code within the R Tool can be challenging, and I know that many people prefer to develop in the IDE of their choice. There is an R package, called jeeves, than can help you develop code destined for the Alteryx R Tool, outside of Alteryx. The documentation can be found on Github: https://github.com/alteryx/jeeves

The following code is here to help you install it! You can either install the package binary from Github.

install.packages("jeeves",  repos = 'http://Alteryx.github.io/jeeves’)

Or download the package and build it from source.

devtools::install_github("Alteryx/jeeves")

We hope you find this cheat sheet useful for all of your future R Tool adventures!

Attachments
Comments
AshishBhavnani
8 - Asteroid

Hi @SydneyF,

 

Thanks for writing this article. It's very helpful and informative!!

 

While going through this article, I was also trying a couple of the commands that you have captured here. I wasn't able to use the R version command on Alteryx in an R tool.

 

I pasted the command as is in an R tool in Alteryx and was hoping to write the read the output via a Browse Tool. However, I am getting the following error after I run this simple workflow - 

 

Could not find function "R.version"

 

Could you please confirm if this command can be used as-is or any R-version specific changes are required to this command?

 

Thanks,

Ashish

 

 

Ken_Black
9 - Comet
9 - Comet

Hi SydneyF,

 

Your work is so Awesome that I had to place it on my reference materials page!  I hope this is OK with you! Congrats on having the vision to do this work. Your work will save many people a lot of time!

 

Thanks,

 

Ken

 

NeilR
Alteryx Alumni (Retired)

@AshishBhavnani that first V should be upper case - R is case sensitive.

MatthewYoung
5 - Atom

Hi @SydneyF

 

I'm having issues when I am trying to use the Interface tools to update different parts of my R script.

 

For instance, I have the user selecting from a Drop Down what action to perform (i.e. DROP, TRUNCATE, etc).

I have the Action node set to Update Value (Default) and Replace a specific string ... matching that string to what is in the R script.

 

However, when I run it, the input from the Drop Down / Action is not updating the R script.

 

Thanks,

Matt

 

 

SydneyF
Alteryx Alumni (Retired)

Hi @MatthewYoung

 

Instead of updating your code directly with an Action Tool, have you tried using a question constant to feed the selected value from the Input Tool into your code?

 

You might find the article Create and Test a Basic Macro from Dr.Dan's series: Guide to Creating your Own R-Based Macro helpful. 

 

Thanks!

 

Sydney

rmelchiotti
7 - Meteor

Thanks a lot for the post, this is very useful.

How do we import an R model in the R tool? load does not seem to work (it throws no error but the object does not get loaded) and I cannot figure out how to use the Input Tool because there is no file type that fit an R model.

 

Any help would be greatly appreciated

SydneyF
Alteryx Alumni (Retired)

Hi @rmelchiotti,

 

 An R Object cannot be brought directly into Alteryx, it needs to first be converted to a format that can safely pass through the Engine. When R objects are passed out of an R Tool in Designer, they are serialized using R code. For help troubleshooting loading the model object directly into the R Tool with code, please post to the Designer Discussion Forum with a sample model object, and the code/workflow you have developed so far. 

 

Thanks!

rmelchiotti
7 - Meteor

I don't have a workflow for Alteryx yet because I don't know where to start. Our idea was to develop the model in R (using standard libraries like caret, without any Alteryx involvement), save the object with save and then use the score tool in Alteryx. From what you mentioned above it does not seem as if models can be imported using the Input Tool so I would not know where to start.

SydneyF
Alteryx Alumni (Retired)

Hi @rmelchiotti,

 

To start, try loading your R object from your machine into an R tool with load(), and then serialize the model object using the code provided with the Cheat Sheet before sending the model object to an output anchor. If you provide the full file path to the load() function, you should be able to bring an R object into the R tool the same way you would in RStudio, and serialize it so that it can be pushed out to other tools in Alteryx Designer.

 

That being said, the Score tool will only work for certain model types. These types are: glm, svyglm, negbin, randomForest.formula, rpart, gbm, lm, rxLogit, rxGlm, rxLinMod, rxDTree, rxDForest, earth, naiveBayes, svm.formula, nnet.formula, coxph, elnet, glmnet, cv.glmnet, and C5.0. If the model you have built in RStudio is not one of these types, you will receive an error when attempting to pass your model to the Score tool. To create estimates with your model in Alteryx, you will likely need to create your own "Score tool" with custom code and an R Tool. 

 

Thanks,

 

 

Sydney

rmelchiotti
7 - Meteor

Thanks a lot for your insight. Load did not seem to work for me but readRDS worked fine and I was able to serialize the object as suggested above. As you mentioned I will have to build my own score tool to deal with the model I have but that should be feasible by looking at the Score tool macro code.

 

Many thanks for your help

yasser
5 - Atom

Excellent, thanks a lot,

I would like to add one thing to save time:

avoid clearing variables at the beginning of your R script, it's a common practice that we do usually using rm(list = ls()), but it will cause AlteryxFullUpdate object not found error when running the control and trying to read or write 

apathetichell
18 - Pollux
read.Alteryx("#1") 

 

I believe this works without mode parameter when reading R code between R tools (even those which are off the shelf ie predictive tools). 

 

You can also use the model export/import strategy as discussed on the R cheat sheet above to go beyond the 5 output R Too limit. This is useful with various R predictive tools as it allows  moving the model to a new tool and taking the output you need (ie as data and not as report formatted).

dbmurray
8 - Asteroid

Thanks so much for this great post @SydneyF ! I'm about to jump into using R in alteryx and this will surely come in very handy.