Showing results for 
Search instead for 
Did you mean: 

Alteryx Designer Knowledge Base

Definitive answers from Designer experts.

Guide to Creating Your Own R-Based Macro - Polish the Macro

Created on

This post is part of the "Guide to Creating Your Own R-Based Macro" series.


In the case of this macro, polishing involves several elements, adding error checking, adding a reporting capability to the macro, documenting the workflow of the macro, making the connections for the interface tools "wireless", and providing the macro with its own icon. In terms of error checking, a lot of what typically would need to be addressed is handled in Alteryx's interface tools by limiting user input to only appropriate data types. The are two other possible user input errors for this macro, the user may neglect to select any potential predictor fields, or may not have selected any of the three entropy measures.


Adding error checking involves adding Error Message tools and connecting them to the appropriate interface tools (in this case the List Box tool to select predictors, and the three Checkbox tools to select importance measures). What the Error Message tools do is determine whether predictors and/or predictor importance measures have been selected by the user, and return a error message if one or both of them has not been provided by the user. Examining the Error Message tools in the macro accompanying the introductory post in this series is the best way to see how this is done.


Adding a report requires both the addition of some additional lines of code in the R tool, and some additional tools in the macro's canvas. One construct that is very common in the R code used in the predictive macros packaged in Alteryx is the use of what are really key-value pair tables. One common one is often labeled grp_out in the R code, and contains the fields grp (the labels) and out (the values), which is used to bundle report elements together in a way that allows them to be easily sent from R to Alteryx, and easily manipulated within Alteryx to create a report. To assist in accomplishing these objectives, there are R "helper functions" that are included in the AlteryxRDataX package (an open source R package that is part of the Alteryx predictive installer) to quickly format data in a convenient way. In addition, there are a set of "supporting macros" that help format the data from R quickly in Alteryx. Often these tools help address differences in the "dimensionality" of outputs. In this case, we want to include the name of the target field that is the focus of the analysis in the report, which is only a single data item. In contrast, the number of reported measures depends on both the set of potential predictors specified by the user (which needs to be one or more), and the set of measures to report (which can range from one to three).


Ultimately, R data frames (or certain types of lists) are passed as tables to Alteryx, resulting in all the data elements needing to have the same number of fields when passed as a single data frame / table. The use of the grp_out table allows this to be accomplished. To make things more concrete, the target field name is passed in the first row of the R data frame, with its label being "table name" (the value in the "grp" field) and the actual name contained in the "out" field. The header row and the data rows of the table require a bit more processing. Each row of values is converted into a string, which consists of a (numerically rounded) set of table values in a pipe ("|") delimited string. There is a R helper function to accomplish this, which is named matrixPipeDelim. The pipe delimited string is the value of "out" for each row of the table, and the label contained in the "grp" field is "table header" for the table header, and "table data" for each row (potential predictor) in the data. The code used in the Macro's R tool to create the grp_out table is given below, and shows the use of the matrixPipeDelim function as part of a character string manipulation operation:


## Create a grp_out key-value pair table for creating a report
## using Alteryx's reporting tools
# The grp (key) field
grp <- c("target field", "table header", rep("table data", length(names(the_data)) - 1))
# The out (value) field
out <- paste(as.character(the_output[[1]]), matrixPipeDelim(as.matrix(the_output[-1])), sep = "|")
out <- c(the_target, paste(names(the_output), collapse = "|"), out)
grp_out <- data.frame(grp, out)
write.Alteryx(grp_out, nOutput = 2)


The portion of the macro that creates the report is shown in Figure 1. The Filter tool makes use of the "grp" field to split the target name from the table of importance weight measures. The name of the target variable is sent to the a Report Text tool to create a report title, while the table of importance weight measures is sent to the Pipe to Table Rows supporting macro to convert the pipe delimited strings into an actual table. The Pipe to Table Rows macro is located in the directory C:\Program Files\Alteryx\bin\RuntimeData\Macros in a standard Alteryx installation.


report_creation.PNGFigure 1: The reporting portion of the macro

There are three ways comments can be inserted into an Alteryx macro to document the underlying process: the Text Comment tool, the Tool Container tool, and the annotation capability of standard Alteryx tools. The ways in which these tools are used reflects personal taste to some extent. Personally, I'm inclined to make use of the annotation capability of Alteryx tools, since I can restructure a workflow without having to move a number of Text Comment tools around as well. Other people make heavy use of Text Comment tools. To get to the annotation panel of a standard Alteryx tool, press on the "pencil" icon in the tool's configuration window, as show in Figure 2.


2019-04-22_11-41-22.pngFigure 2: The annotation panel of an Alteryx tool

By right clicking on input and output nodes of the interface tools, a context menu will appears that allows the user to make the connection to or from that tool wireless.


The final bit of polishing is giving the macro a new icon. By default, the icon a new macro receives is a blue circle. You can either use this or other generic icons provided with Alteryx, create a completely new icon from scratch, or use clip art images from the Internet or other sources. Ideally, the icon has some connection to the tool. In this case, we are creating a macro to provide entropy based measures, so something that conveys entropy seems like a good choice. An image that always conveyed entropy to me is the artist Salvador Dali's melting pocket watches from the painting The Persistence of Memory. After a bit a search, I found an image of a melting pocket watch that works well as an icon. To use the icon, go to the Interface Designer for the macro, and press the wrench icon, from there, you can change the macro's icon, as shown in Figure 3.


2019-04-22_11-44-45.pngFigure 3: Using the "Cog" panel of an Alteryx macro to select an icon

The workflow of the completed macro is shown in Figure 4.


complete_macro.PNGFigure 4: The completed Entropy Importance macro

It took me about one hour and 20 minutes to create the base version of the macro, and a little over an hour to polish it, for a total time of around two and half hours from start to finish.