How to Create Tables and Calculations via QScript

This article describes how to generate tables and R-based calculations 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 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, How to Modify Variables and Value Attributes 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.
• This assumes you have also performed the steps below from How to Modify Variables and Value Attributes via QScript:
  • Set a regrouped variable set called Q5 as per the steps in the Combine section.
  • Set Q5 as a set of filters as per the steps in the Variable and variable set properties section.
  • Set Gender as a weight as per the steps in the Variable and variable set properties section.

Method

In Displayr, the document's Report section is referenced as the project.report object. You can append various objects to your document, such as pages, tables, calculations, and visualizations.

Here, we will focus on tables and calculations.

Summary tables and crosstabs

The general workflow for creating a table via QScript is to first add a page and then insert a table on it. In this example, we will create a summary percentage table based on our Age variable:

// Declare variables
var report = project.report;
var data_file = project.dataFiles[0];

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

// Add table
var t = page.appendTable();
t.primary = data_file.getQuestionByName('Age');

• We begin by declaring our document as report and data file as data_file so they can be used later.
• We then get our Age question object from our data set using getQuestionByName.
• Next, we append a page to report using appendGroup with the name Demographics.
• Finally, we use the appendTable function to insert a summary table called t on our page by specifying the primary question for the rows. By default, the secondary or columns question will be set to SUMMARY or RAW DATA depending on the data format.
• By default, the table will also appear on the referenced page. To instead place this off the page, you would change the second-to-last line to var t = page.appendTable(true);.

Further arguments can be added to our example. Let's add Work status in the columns to create a crossbreak and apply the Optus (Q5_4) filter we previously created in How to Modify Variables and Value Attributes via QScript:

t.secondary = data_file.getQuestionByName('Work status');
t.groupedFilters = [data_file.getVariableByName('Q5_4')];

Note, that filters are stored in an array (represented by square brackets) and are referenced by variable name. In order to use groupFilters with multiple filter variables that are checked as Usable as a filter, such as both Q5_4 (Optus) and Q5_6 (Telstra), we would do the below:

t.groupedFilters = [data_file.getVariableByName('Q5_4'), data_file.getVariableByName('Q5_6')];

Note, if the included filter variables are grouped as a combined variable set, they will produce an OR condition, otherwise, the condition will use AND.

Adding a weight, on the other hand, is simply a matter of referencing a variable that is checked as Usable as a weight by name:

t.weight = data_file.getVariableByName('q35');

Table statistics

Displayr differentiates between statistics in cells, to the right and below a table. You can see these in the object inspector under Data > Statistics > Cells/Right/Below.

In QScript, these are referenced as follows:

• cellStatistics - statistics shown in the cells of a table.
• rowStatistics - statistics shown to the right of each table row.
• columnStatistics - statistics shown below a table.

One thing to note here is that these properties use the original statistic name, that is, the name from Displayr's sister product, Q. To avoid having to know the Q statistic name when different, you can instead use the Table JavaScript Utility function getOriginalName.

In the example below, we return the original name for Column Sample Size (which is Column n) and set this instead below the table as an array:

var stat = getOriginalName("Column Sample Size");
t.columnStatistics = [stat];

Note, you must include includeWeb('Table JavaScript Utility Functions'); at the top of the script as getOriginalName only exists in this online library.

Calculations

Appending R Calculations is just as easy as adding a table, except we use the appendR function. For example, we could add a calculation to our Demographics page by using the referenceName of our table or t:

page.appendR(t.referenceName);

By default, the calculation will appear on the referenced page. To instead place this off the page, you would add an additional true argument:

page.appendR(t.referenceName, true);

If we wanted, on the other hand, to sum all rows for each column in this crosstab, we could include our table reference name in a formula:

page.appendR("table.average = rowSums(" + t.referenceName + ", na.rm=T)");

This would then paste the following R code in our calculation:

table.average = rowSums(table.Age.by.Work.status, na.rm=T)

If you're appending large blocks of code with multiple lines, the entire block of R code needs to be contained within backtick characters: 

page.appendR(`############ R CODE FROM QSCRIPT ############ 
mytables <- list(${tabnames}) 
#get report structure from QScript 
report.structure="${folder_structure}" 
#turn into a vector for easier processing 
report.structure <- trimws(strsplit(report.structure, ",")[[1]])')

Next

How to Create a Visualization via QScript

Later

How to Modify Tables via QScript

See Also

How to Work with Variables via QScript

How to Modify Variables and Value Attributes 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