How to Create a Visualization via QScript

This article describes how to create a visualization using a QScript:

Requirements

• A Displayr Enterprise user license which includes the ability to add custom analysis menu items or use the Displayr API.
• The importdata.zip file which includes the Phone data set that we will use for this article.
• You have read How to Create a Custom QScript, How to Work with Variables via QScript, and How to Add Pages, Folders, and Headings via QScript.
• You are using one of the methods from How to Use QScripts in Displayr.

Method

In Displayr, the document's Pages section is referenced as the project.report object. You can append various objects to your document, including visualizations.

Basic charts

The general workflow for creating a basic chart via QScript is to first add a page and then insert a chart on it. In this example, we will create a Column with Tests visualization based on our Age variable crosstabbed by Gender:

// Declare variables
var report = project.report;
var data_file = project.dataFiles[0];
var age = data_file.getQuestionByName("Age");
var gender = data_file.getQuestionByName("Gender");

// Add page
var page = report.appendGroup();
page.name = "Charts";

// Add chart
var chart = page.appendPlot("Column chart");
chart.primary = age;
chart.secondary = gender;
chart.size = [150, 75];

• We begin by declaring our report and data file as variables that can be used later.
• We then get our Age and Gender question objects from our data set using getQuestionByName.
• Next, we append a page to our report with the name Charts.
• Finally, we use the appendPlot function to insert a column chart on our page by specifying the primary question for the rows, secondary question for the columns, and the size of the chart in pixels.
• An alternative to individually setting the primary and secondary arguments is to feed them within an array inside the function which then allows you to optionally add a further positional argument and set it to true when you wish to place the chart off the page:

var chart = page.appendPlot("Column chart",[age,gender], true);

You can also use the function of appendPlotAutomatic which will select the chart type automatically based on the data structure instead of your having to specify it:

var chart = page.appendPlotAutomatic([age, gender]);

Note, the appendPlot and appendPlotAutomatic methods are only applicable for non-R-based charts. In most cases, these have "with Tests" appended to their name in the Visualization selector. However, for the purposes of this function, they are simply referred to by their common chart-type names, such as Line chart, (Stacked) column chart, (Stacked) bar chart, and Pie chart.

R visualizations

An alternative approach is to create an R-based Column chart by replacing the last section of code with the below:

var chart = page.appendVisualization("Visualization - Column - Column", 
                                           {"formX": age.variables[0].guid});
chart.update();

• Here, we instead use appendVisualization and specify the chart type by entering the menu structure in the Visualization selector separated by a dash.
• We can then reference the Input JavaScript control for storing variables, formX, and pass the unique guid of the Age variable.
• To ensure the underlying code has been run upon loading, we force chart to calculate by using update().
• By default, the visualization will appear on the referenced page. To instead place this off the page, you would add an additional true argument to the end of the second line:

var chart = page.appendVisualization("Visualization - Column - Column", 
                                           {"formX": age.variables[0].guid}, true);

Optionally, you can also select the page with the chart after the above code has run:

project.report.setSelectedRaw([chart]);

Next

How to Modify Tables via QScript

See Also

How to Work with Variables via QScript

How to Add Pages, Folders, and Headings via QScript

How to Create a Custom QScript

How to Use QScripts in Displayr

JavaScript Fundamentals