This article describes how to generate tables and R-based calculations 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, 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 below steps 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.
In Displayr, the document's Pages 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;
// 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
reportand data file as
data_fileso they can be used later.
- We then get our Age
questionobject from our data set using
- Next, we append a page to
appendGroupwith the name Demographics.
- Finally, we use the
appendTablefunction to insert a summary table called
ton our page by specifying the primary
questionfor the rows. By default the secondary or columns
questionwill be set to SUMMARY or RAW DATA depending on the data format.
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');
Displayr differentiates between statistics in cells, to the right and below a table. You can see these in the object inspector under Inputs > STATISTICS > Cells/Right/Below.
In QScript theses are referenced as below:
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.
In the below example, 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
getOriginalName only exists in this online library.
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
If we wanted to sum all rows for each column in this crosstab, we could instead 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)