UPCOMING WEBINAR: The Roadmap for Market Researchers in the Age of AI This article describes how to create, share, edit, and run QScripts in Displayr. QScript is an Enterprise feature that can help you to automate repetitive tasks, such as setting up data, cleaning data, recoding data, or creating tables and charts.
Many programs can only be used with scripting (e.g., R) or are more efficiently used via scripting (e.g., SPSS’s syntax). In Displayr, most things are done faster and easier by selecting multiple tables or variables, dragging and dropping, and using menus. Furthermore, many advanced functions are already pre-built or are done automatically, so most users would not need to use QScripts.
Nevertheless, QScript is useful in the following situations:
- When needing to make the same change to a large number of variable sets (e.g., creating top 2 box scores, such as combining Agree with Strongly agree, on lots of different variable sets).
- When needing to follow a similar process to the creation and formatting of a large number of tables or charts.
See QScript Examples Library for examples.
Requirements
- For Method 1: A Displayr Enterprise user license, which includes the ability to add custom analysis menu items.
- For Method 2: A Displayr Enterprise user license with purchased View hours.
Method 1 – QScript Editor
Create a QScript
1. You can create a new QScript from + in the Report menu via Calculation > QScript > New. You can also access this menu from the Data Sources tree by hovering over any variable and then clicking + > Custom Code > QScript > New.
The QScript editor allows you to write JavaScript code.
2. Once you have entered your code, press Play and then click OK.
3. You will now be prompted to enter a name for the file so it can then be saved to your Displayr Cloud Drive:
4. If you create a QScript in a text editor outside of Displayr, you can instead upload it to the Displayr Cloud Drive from your document by clicking on the initials icon and selecting Displayr Cloud Drive > + Upload.
Run or Edit a QScript
- You can run a script saved in your Displayr Cloud Drive from the Report tree by clicking + > Calculation > QScript or hovering in the Data Sources tree and clicking + > Custom Code > QScript, and choosing the appropriate script.
- If you wish to view or edit an existing script, you can load it in the QScript Editor from the Report tree by clicking + > Calculation > QScript > Open or hovering in the Data Sources tree and clicking + > Custom Code > QScript > Open.
Limitations
As Displayr is stored on a server, QScripts run via the Editor cannot access your computer's local disk (C:). Unlike Displayr's sister product, Q, which is a desktop app, the relevant files must be stored in the Displayr Cloud Drive. This also means any function designed to write data locally will not work.
Method 2 – Displayr API
QScripts can also be run via the Displayr API. This method is useful for automating the initial setup of documents, especially when you have data files with a similar structure. It relies on a QScript to tell the API what actions to perform within the document. These could include automatically importing data sets, setting up and combining variables, and adding pages, basic charts, and tables.
Run a QScript via the Displayr API and Python
The API itself requires using another program, such as Python, to connect to the API and run the QScript and any accompanying data files locally.
If importing a data set into a document, for example, this would include the following files within the same local folder:
- A data set.
- A QScript that references this data set.
- A Python (.py) script that references both QScript and data set.
The Python script is then run from a Windows Command Prompt.
This method is outlined in detail in How to Get Started with the Displayr API and includes a template for the script. Please note that the documentation is designed and written to be used by computer programmers. See Displayr API and Technical Reference for further details on the API.
Limitations
When running QScripts via the Displayr API, prompt functions that allow you to, for example, select the variables to run a script on cannot be used. The QScript must contain all the necessary code without requiring user intervention as it runs.
See Also
How to Work with JavaScript in Displayr
How to Create a Custom QScript