How To Create a QScript To Add a Custom Analysis Tool

Introduction

This article describes how to convert your custom analysis tool into a QScript that allows you to add it to a page in any of your documents. While this can be more easily shared by saving it to the Displayr Cloud Drive directly as an RScript, this method is intended for situations where you wish to include this in a QScript that performs further actions.

Requirements

• A Displayr Enterprise user license which includes the ability to add custom analysis menu items.
• Here, we will use a simplified version of the example outlined in How to Create a Custom Analysis Tool which allows the user to select the input table and set the colors of the row and column headers. The example code is as follows:

R code:

# get table
tab = data
#create custom table
custom.table = flipFormat::CreateCustomTable(tab,
col.header.fill = headercolor,
row.header.fill = headercolor,
banded.rows = TRUE,
row.header.pad = 5)

Input JavaScript:

// Add drop box to select your input table
form.dropBox({name: "data",
label: "Input table",
types: ["Table"],
prompt: "Please select your input table"})
// Add color picker for headers
form.colorPicker({name: "headercolor",
label: "Select your header color",
default_value: "#357EC7",
prompt: "Please select your header color"})

Method

Once you have created your custom analysis tool, there are several main steps:

• Open the QScript editor from the toolbar via Anything > [Company name] > Open QScript Editor.
• Format your custom R code as a string.
• Format your custom JavaScript code as a string.
• Create the QScript to add the custom analysis tool to your document.

Format your code as string blocks

The code for the analysis tool needs to be added as a string for each language (that is, JavaScript and R) within the code for the QScript. This means that the entire block of R code must be placed within backticks ` ` with several modifications. The properly-formatted string to use for the example code above is as follows:

includeWeb("QScript R Output Functions");
let output_name = generateUniqueRObjectName("custom.table");
// R code
let r_expression = `# get table
tab = data
#create custom table
${output_name} = flipFormat::CreateCustomTable(tab,
col.header.fill = headercolor,
row.header.fill = headercolor,
banded.rows = TRUE,
row.header.pad = 5)`;

In this code:

• We begin by creating the output_name using the generateUniqueRObjectName function from the QScript R Output Functions library. This will ensure the output will always have a unique name in your document.
• The original code has been assigned into a JavaScript variable called r_expression.
• The entire block of code is enclosed in backticks ` ` to denote a template literal string. 
• The last line of the string is ended with a ; to indicate the end of the instruction (just like any other line of JavaScript).
• Lastly, we have replaced custom.table in our original R code with ${output_name} as this will instead be generated by the code we added at the start.

We now do similar for the JavaScript block of code by assigning it as j_expression. This time we don't need to worry about the output_name as this code only adds the controls.

// Input JavaScript
let j_expression = `// Add drop box to select your input table
form.dropBox({name: "data",
label: "Input table",
types: ["Table"],
prompt: "Please select your input table"})
// Add color picker for headers
form.colorPicker({name: "headercolor",
label: "Select your header color",
default_value: "#357EC7",
prompt: "Please select your header color"})`;

Create the QScript to add the custom analysis tool

The QScript for adding the analysis tool needs to do several things:

• It needs to create a new page in the document. This is done using the QScript function called appendPage().
• It needs to create a new R calculation. This is done using the function appendR().
• It needs to set the GUI controls in this calculation. This is done using the function setCodeForGuiControls().

The QScript below will add the analysis tool to a new page when the script is run:

includeWeb("QScript R Output Functions");
let output_name = generateUniqueRObjectName("custom.table");
// R code
let r_expression = `# get table
tab = data
#create custom table
${output_name} = flipFormat::CreateCustomTable(tab,
col.header.fill = headercolor,
row.header.fill = headercolor,
banded.rows = TRUE,
row.header.pad = 5)`;

// Input JavaScript
let j_expression = `// Add drop box to select your input table
form.dropBox({name: "data",
label: "Input table",
types: ["Table"],
prompt: "Please select your input table"})
// Add color picker for headers
form.colorPicker({name: "headercolor",
label: "Select your header color",
default_value: "#357EC7",
prompt: "Please select your header color"})`

// Create page and title
let page = project.report.appendPage("Blank");
page.name = "My Custom Analysis Tool";

// Create R object
let output = page.appendR(r_expression);
output.setCodeForGuiControls(j_expression);
output.update();
project.report.setSelectedRaw([output]);

In this code:

• The expressions for the analysis tool need to be defined above the rest of the code, which then adds the tool to the document.
• A page must first be created to add the tool to. Here, we add a blank page layout to the document's project.report object called page and set the page name.
• Next, we append our R calculation to this page with the contents of r_expression and declare it as a variable called output.
• We then set the GUI controls for output with the contents of j_expression.
• To ensure the underlying code has been run upon loading, we force output to calculate by using update().
• Finally, we use project.report.setSelectedRaw() to select our analysis tool within the document.

Save and run your QScript

1. Once you have entered your code, press OK.

2. Enter a name for the script to be saved to your Displayr Cloud Drive.
3. In the toolbar go to Anything > [Company name] and choose your QScript.

See Also

How to Create a Custom Analysis Tool

How to Share a Custom Analysis Tool Between Documents

How to Create a Custom QScript

How to Use QScripts in Displayr

JavaScript Fundamentals