R Tool
R Tool
Important
The Predictive Tools 2022.1 update is now available and includes R 4.1.3. Install the update to use new R packages from CRAN in your custom code. You don't need this update if your current or new R code makes use of previously installed packages.
The R tool is a code editor for R users. R is an open-source codebase that you can use for statistical analysis. You should be proficient in R before you use this tool.
R in Designer
Designer reads valid R scripts and passes them through the tool. Output from the R tool matches output in R.
R Support
Although Designer accepts customer R code, Alteryx doesn't provide support for customer R code.
Alteryx uses [AlteryxFullUpdate], a global variable for the R script, for metainfo updates. Full metainfo updates occur when you set AlteryxFullUpdate to TRUE. This happens when you 1st open the workflow or refresh it with the F5 key.
You can't use standard read and write functions when AlteryxFullUpdate = TRUE. If an R script contains a function like read.Alteryx or write.Alteryx while AlteryxFullUpdate = TRUE, an error occurs.
Metainfo that you pass to outputs when AlteryxFullUpdate = TRUE may differ from metainfo Designer generates when you run the workflow. This can cause errors to occur.
Configure the Tool
The R tool accepts multiple inputs and labels them in order of connection (#1, #2, and so on.) The tool outputs up to 5 data streams from its anchors, labeled 1 through 5. References in the code should follow the same format differences between inputs and outputs.
Important
In the descriptions below, #1 refers to any input connection label and 5 refers to any output anchor.
The R tool uses the function write.Alteryx(DATA_VARIABLE_TO_WRITE, 5) for output.
Insert Code: List Designer-specific commands that you can inject into the R code editor. You should use those commands with typical R commands. The list isn't comprehensive.
R and interface tools: To access interface tools in the R tool, enter %Question.tool_name% where tool_name is the name of the interface tool, which you can find on the Annotation tab in the Configuration window.
Read Input
Read Input: This function reads in a connected data input. Each connected input creates a separate option listed in order of connection. Select a listed input to insert the connection in the Code Editor. You can use this function regardless of whether you set AlteryxFullUpdate to TRUE or FALSE.
The read.Alteryx() function streams input data into the R environment.
Optional Parameter
Row Names: An optional parameter to include a new column titled RowNames, populated with the first column of data to be treated as row headers. By default, Designer sets this parameter to FALSE.
write.Alteryx(DATA_VARIABLE_TO_WRITE, 5, TRUE)
as Data Frame: This option reads in a data table. It has no other parameters.
read.Alteryx("#1", mode="data.frame")
as Data Frame: Chunked: This option reads in a large data table. Specify the number of records you want it to process at a time.
read.Alteryx("#1", 50000, mode="data.frame")
as List: This option reads in spatial objects.
read.Alteryx("#1", mode="list")
as List: Chunked: This option reads in a large number of spatial records. Specify the number of records you want to process at a time.
read.Alteryx("#1", 50000, mode="list")
Input MetaInfo: This option reads in the metainfo from input rather than data. The function returns a data frame that contains the metainfo. The rows of the data frame represent each column from the input data, while the applicable metainfo displays in 6 columns:
Name: String, the column name.
Type: String, the data type.
Size: Integer, the size of the data type in bytes.
Scale: Integer, the number of decimal places in a FixedDecimal.
Source: String, the metadata about the column type, followed by the starting value.
Description: String, an optional column that you can populate with a description string.
read.AlteryxMetaInfo("#1")
Set Progress
Set Progress: This function reports progress on the tool icon in a workflow. Select 1 of these increment options:
25%
50%
75%
100%
AlteryxProgress(0.25)
Output Message
Output Message: This function displays a message in the Results window. The message priority determines when Designer reports the message. Go to Workflow Configuration to change message-display behavior.
Message Priority
Normal Priority Message: The message displays only when the R tool is visible on the canvas of a running workflow. If the R tool is contained within a macro, Designer doesn't display the message.
AlteryxMessage("message", msg.consts$INFO, priority.consts$LOW)
Normal Priority Transient Message: The message displays in place of an existing message the same tool issues.
AlteryxMessage("message", msg.consts$INFO, priority.consts$LOW, 5)
Medium Priority Warning: The message displays when the R tool is visible on the canvas of the running workflow or is contained within a macro in the running workflow.
AlteryxMessage("message", msg.consts$WARNING, priority.consts$MEDIUM)
Field Conversion Error: The message displays when you can't convert data from one field type to another or when data don't fit in the field specification.
AlteryxMessage("message", msg.consts$FIELD_CONVERSION_ERROR)
High Priority Error: The message displays regardless of the relation of the R tool to the running workflow. Designer treats field-conversion errors as high priority.
AlteryxMessage("message", msg.consts$ERROR, priority.consts$HIGH)
Write Output
Write Output: This option outputs a data stream from an output anchor. All anchors can produce either data or a single graph.
Data Frame
As a best practice, you should convert data to a data frame with the R data.frame() function before you use the write.Alteryx() function. If data is not converted to a data frame, Alteryx attempts to convert to a data frame, but this might not work as expected.
Optional Parameters
Source: This optional parameter adds a string to the Source column in the metadata output.
write.Alteryx(DATA_VARIABLE_TO_WRITE, 5, source="customer data from 2012 repo")
Row Names: This optional parameter includes a new column titled RowNames, populated with the first column of data as row headers. This parameter defaults to FALSE.
write.Alteryx(DATA_VARIABLE_TO_WRITE, 5, TRUE)
Packing Dependencies
Designer doesn't automatically detect extra files that accompany your R code as workflow dependencies. If you need to package your workflow and your R code has its own dependencies, include any additional files using Tool configuration in the Configuration window.
Create Graph
Create Graph: This option outputs a graph of the analysis. Designer treats the output as a reporting snippet that Reporting tools can read. Select 1 of these options for graph size:
6x6 Inches - 96 dpi
8x10 Inches - 300 dpi
AlteryxGraph(5, width=576, height=576) xPoints<- c(1, 2, 3, 4) yPoints <- c(2, 4, 6, 8) plot(xPoints, yPoints) invisible(dev.off())
Update/Metainfo
if(AlteryxFullUpdate)...: This function works with the global variable [AlteryxFullUpdate].
write.AlteryxAddFieldMetaInfo: This function adds the metainfo from a single column to the named output. You can't use this function when AlteryxFullUpdate = FALSE.
Optional Parameters
You can use any combination of the parameters below.
nOutput: Add metadata for a column to the output.
name: Specify the name of the column you want to output. If you provide a name that's invalid, an error occurs.
fieldType: Represent the datatype of a column. If you provide a field type that's invalid, an error occurs. You may need to manually update Size and Scale based on the field type. Designer accepts several field types by converting them into valid field types.
size: Specify the size of the column. Designer automatically assigns this value to many field types.
scale: Specify the number of decimal places for column values. Designer requires that you specify this value for FixedDecimal field types, but not other field types.
Valid FieldType Strings | Size Overridden | Scale Overridden | Converts to Valid FieldType |
|---|---|---|---|
Bool | automatic | logical | |
Byte | automatic | ||
Int16 | automatic | ||
Int32 | automatic | integer | |
Int 64 | automatic | ||
FixedDecimal | manual | manual | |
Float | automatic | ||
Double | automatic | numeric | |
String | manual | ||
WString | manual | ||
V_String | |||
V_WString | factor; character | ||
Date | automatic | ||
Time | automatic | ||
DateTime | automatic | ||
Blob | |||
Spatial Object |
source: Populate this optional column with a string that describes the origins of the column.
description: Populate this optional column with a description string.
write.AlteryxGraphMetaInfo: This function sets the metainfo of the named output to an R Script Graph with AlteryxGraph(). You can't use this function when AlteryxFullUpdate = FALSE.
Optional Parameters
nOutput: Specify the output in which you want to add the metadata of the column.