Category:QScript

Related Online Training modules
Running a QScript
Automate Project Setup with QScripts
Generally it is best to access online training from within Q by selecting Help : Online Training

QScript is an advanced Q feature that can help you to automate repetitive tasks, such as setting up data, cleaning data, recoding data or creating tables and charts. See Rules for tools for manipulating tables and charts.

A QScript is written in JavaScript. QScripts use the same concepts that Q uses, so you need to know how to use Q prior to being able to automate anything with a QScript.

This page provides an overview of QScript. Refer to:

• QScript Reference for detail about how QScript interacts with Q (i.e., the way to work out the properties of the data).
• QScript Examples Library for examples of using QScript.
• Online JavaScript Libraries for functions that have been written to assist with the writing of QScripts and other JavaScript.
• JavaScript for a more general discussion of how the JavaScript programming language works.
• Table JavaScript and Plot JavaScript for tools for using JavaScript to modify the appearance of tables and charts.
• JavaScript Variables for detail on how to create new variables in the Variables and Questions tab using JavaScript.

Running QScripts

QScripts are contained in files with file extension .QScript. There are two ways to run them:

• You can run them from the Online Library using Automate > Online Library. In older versions of Q, instead use Tools > QScripts > Online Library.
• If you have them stored on your computer or network as a file, you can run them using Automate > Run QScript (Macro) From File. In older versions of Q, instead use Tools > Run QScript and Tools > QScript > From File. These files are run in their entirety (i.e., you cannot run just a part of a file).

Creating QScript files

A QScript file can be created in any text editor (a text editor is a word-processor that does not permit formatting). When saving scripts, you must use the ".QScript" file extension.

Q 4.9.4 and onwards

From Q 4.9.4 onwards, there is a in-built editor for QScripts that can be accessed by Automate > Open QScript (Macro) Editor.

Older versions of Q

It is generally not advisable to create QScripts in Word or other Office programs as these programs automatically format text and this automatic formatting can result in difficult-to-find problems.

All Windows computers contain a text editor called Notepad. You can create a QScript in Notepad as follows:

1. Start Notepad and type your QScript into it.
2. Select File > Save as.
3. Type the name for you file as YOUR_FILE_NAME.QScript, replacing YOUR_FILE_NAME with your desired file name.
4. Change Save as type to All Files (*.*).
5. Press Save.

It is easier to write and read scripts when they are created using a text editor that can use different colors to highlight keywords, comments, and the like, as occurs when creating JavaScript Variables and Table JavaScript and Plot JavaScript in Q. See Setting Up a Text Editor for QScript.

Some Q features cannot be used by QScript. Contact support if we have left out something important.

The appropriate use of QScript

Many programs can only be used with scripting (e.g., R). Some programs are most efficiently used via scripting (e.g., SPSS’s syntax). In Q, most things are done faster and easier by selecting multiple tables or variables and dragging-and-dropping and using menus. Furthermore, the most repetitious tasks (e.g., re-computing variables when data is updated) are handled automatically by Q. Most users of Q should never need to use QScripts (and, many uses of QScript are better managed using other tools within Q).

Nevertheless, QScript is useful in the following situations:

• When needing to make the same change to a large number of questions (e.g., creating top 2 box scores, such as combining Agree with Strongly agree, on lots of different questions).
• 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.

Example

This example is designed to illustrate various features of QScript. It

• Starts a new project by reading data in from Q.
• Creates a Banner question.
• Checks for a weight and alerts you that it is not in the file.
• Produces a short report advising you the value used for Don't know.
• Creates some tables and a chart.

To run this example

1. Select Automate > Run QScript (Macro) from File (or Tools > Run QScript in Q versions earlier than Q 4.8).
2. Select QScript Examples.QScript. This example is located in C:\Program Files\Q\Examples or elsewhere if Q has been installed somewhere else on your computer.
3. Press Yes, OK and OK to the different messages.

Worked examples

The following examples from QScript Examples Library contain additional documentation and, if read in order, provide a basic level of training in how to create and use QScript:

1. Checking to See if a Data File Has Been Imported
2. Adding Data Files
3. Hiding a Category of a Question
4. Rebasing a Pick One Question
5. Creating a Banner
6. Setting a Pick Any Question
7. Creating a Frequency Table
8. Creating a Column Chart
9. Creating Diagnostic Messages
10. Recoding Into New Variables