Introduction
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 and 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 the toolbar via Anything > [Company name] > Open QScript Editor. This Editor allows you to write JavaScript code.
2. Once you have entered your code, press 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 your Profile icon > Displayr cloud drive > + Upload.
Run or Edit a QScript
- You can run a script saved in your Displayr Cloud Drive from the toolbar via Anything > [Company name] and choosing the appropriate script.
- If you wish to view or edit an existing script, you can load it in the QScript Editor via Anything > [Company name] > Open QScript from Displayr Cloud Drive.
Limitations
As Displayr is stored on a server, QScripts run via the Editor cannot access your computer's local disk (C:). Unlike with 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