How to Create a QScript for Importing Data into a New Document via the Displayr API

Introduction

This article describes how to write a QScript for creating a new document and uploading a data set that can be used in conjunction with the Displayr API.

Requirements

• An Enterprise Displayr license with purchased View hours.
• The importdata.zip file which includes the data file and QScript we will use for this article.
• The process outlined in How to Import Data via the Displayr API using Python.

Method

There are two main steps that are included in the example QScript:

• Create the document.
• Import the data file.

In QScript, the project variable represents the document. We can tell the QScript to create a new document by referencing its newProject() property:

project.newProject();

Next, we need to apply the addDataFile method to our project variable. The basic arguments are as follows:

addDataFile(data_file, override_file_name, options)

• The data_file argument assumes that the data file is in the same location as the QScript file so only requires the data file's name and extension. Note, that the accompanying Python script specifies the format of <<<Filename.ext>>>. This argument will also be the ID returned by the Displayr API's /API/Upload command after you upload your data file.
• The override_file_name must be entered particularly when using the /API/ImportUpdatedData command, as there is no file name in the upload ID. This will be the folder name that appears in the Data Sets tree.
• The options argument lets you optionally tell Displayr to do the following:
  • auto_tidy_labels - Automatically clean up variable labels.
  • auto_detect_questions - Automatically identify and combine multiple-response and grid variable sets.
  • strip_labels_html - Strip HTML from variable labels.
  • Note, these are all set to false by default.

Now let's look at our example:

var data_file = project.addDataFile("<<<Phone.sav>>>", "phone.sav", { auto_tidy_labels: true,
                                                                   auto_detect_questions: true,
                                                                   strip_labels_html: true });

• In this case, we will import the Phone.sav file as a data set called phone.sav and allow Displayr to tidy the data set using all 3 cleaning options.
• By additionally declaring this as data_file, we can then perform other QScript functions on this data set where necessary.
• Note, this addDataFile QScript method is designed only for when you need to upload a new data set to your document. It is not necessary for simply updating an existing data set via the Displayr API.

See Also

How to Get Started with the Displayr API

How to Import Data via the Displayr API

How to Create a Custom QScript