How to Reference Controls in a Custom Analysis Tool Using R

This article describes how to access input controls using R in custom analysis tools.

Requirements

A custom analysis tool that you created via Calculation > Custom Code.
You have read How to Create a Custom Analysis Tool and How to Create User Input Fields in a Custom Analysis Tool.

Method

Referencing input controls

When input controls on a custom analysis tool are created via JavaScript code, it also makes available variables which may be accessed from R, corresponding to each of these controls.

In most cases, this variable reference will return the label or value of the control selection(s), while checkboxes will naturally return TRUE or FALSE.

Dropbox references, on the other hand, can include more details, as they are often used for selecting variables and variable sets or R items which include attribute metadata. As an example, if you had a control called dropBox1, attributes(dropBox1) would return all the relevant elements that can be extracted. Some of the attributes commonly returned are below:

## For variables
attributes(dropBox1)$name # variable name
attributes(dropBox1)$label # variable label
attributes(dropBox1)$question # combined label (or variable set name)

## For R-based visualizations
attributes(dropBox1)$ChartType # type of chart
attributes(dropBox1)$ChartData # table of charted data

Whenever you reference the name of one of these controls in R, they will appear highlighted in light blue boxes. Note that if you don't explicitly name your controls, they are automatically given names based on the control type and the order it appears. For example, the first combo box will be called "comboBox1", and the second will be called "comboBox2", while the first checkbox will be called "checkBox1".

Substitution functions

A series of special functions are also available for substituting control values into the R code. This is useful when the input format does not match the format that the R code requires.

Let's now look at these functions.

QDataFrame

If we had 2 input controls as an example...

QDataFrame(control1, control2)

...this would be replaced in the code with their respective variables (as values) and labels:

data.frame(label1 = variable1, label2 = variable2)

If a control returns multiple values, the values will be separated by commas. As QDataFrame(...) gets transformed to a data.frame(...), other parameters for data.frame can be passed in as well (i.e. check.names = FALSE).

Note: Since variable sets are not directly suitable as inputs to a data.frame, parameter values for QDataFrame would typically be restricted to variables. This does not prevent users from selecting combined variable sets because variable sets will automatically be replaced by their constituent variables when dropped onto controls that only accept variables.

QFormula

If we had 3 input controls as an example...

QFormula(control1 ~ control2 + control3)

...this would be replaced in the code with their respective labels:

QFormula(label1 ~ label2 + label3)

If a control returns multiple values, the values will be separated by commas.

QInputs

If we had 2 input controls as an example...

QInputs(control1, control2)

...this would be replaced in the code with their respective labels:

QInputs(value1, value2)

If a control returns multiple values, the values will be separated by commas.

Note: Since QInputs does not surround multiple values with brackets, care must be taken when multiple values are allowed to ensure that the generated code makes sense for more than one value.

Now we will look at a real example. The following is from an ordered logit regression output that uses some of these substitution functions.

The corresponding input controls are an Outcome field called formOutcomeVariable (where we select Q27) and a Predictors field called formPredictorVariables (where we select Q28 and Q29):

library(flipMultivariates) 
data <- QDataFrame(formOutcomeVariable, formPredictorVariables) 
ordered.logit <- OrderedLogit(QFormula(formOutcomeVariable ~ formPredictorVariables), data, QCalibratedWeight, QFilter)

Before the R code is executed:

The function calls QDataFrame(formOutcomeVariable, formPredictorVariables) to supply the names of the selected variables (in order to return their values) and their labels as column headers.
The function then calls QFormula(formOutcomeVariable ~ formPredictorVariables) to supply the labels of the items selected in the controls.

The end result will look like below:

library(flipMultivariates) 
data <- data.frame(Q27.Weightconsciousness = Q27, Q28.Exercise.frequency = Q28, Q29.Living.arrangements = Q29) 
ordered.logit <- OrderedLogit(Q27.Weightconsciousness~Q28.Exercise.frequency+Q29.Living.arrangements, data, QCalibratedWeight, QFilter)

How to Create a Custom Analysis Tool

How to Create an Auto-Updating Custom Analysis Tool

How to Create User Input Fields in a Custom Analysis Tool

How to Set Conditional Controls in a Custom Analysis Tool

How to Set Object Types in DropBox Controls in Custom Analysis Tools