This article describes how to create a visualization using a QScript:
- 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.
In Displayr, the document's Pages section is referenced as the
project.report object. You can append various objects to your document, including visualizations.
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;
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
questionobjects from our data set using
- Next, we append a page to our report with the name Charts.
- Finally, we use the
appendPlotfunction to insert a column chart on our page by specifying the primary
questionfor the rows, secondary
questionfor the columns, and the size of the chart in pixels.
An alternative to specifying the chart type is to use
appendPlotAutomatic which will select the chart type automatically based on the data structure. In this case, we can add the
secondary arguments within an array inside the function:
var chart = page.appendPlotAutomatic([age, gender]);
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.
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",
- Here, we instead use
appendVisualizationand specify the chart type by entering the menu structure in the Visualization selector separated by a dash.
formX, and pass the unique guid of the Age variable.
- To ensure the underlying code has been run upon loading, we force
chartto calculate by using
Optionally, you can also select the page with the chart after the above code has run: