QScript Project

From Q
Jump to: navigation, search

Project

Represents your project. To find your plots and tables, use report. To find your questions and variables, find your DataFile object (see dataFiles) and ask it.

addDataFile(data_file, override_file_name, options)

Imports a data file into the project. Scripts that create a project will generally start with a call to this method.
data_fileThe path to the data file to load. If this is a relative path then it is relative to the location of the script file. If you are running the script on Displayr then this should be the ID returned by /API/Upload after you uploaded the data file, and you must also supply override_file_name.
override_file_nameThe name to use to refer to this file, particularly when using /API/ImportUpdatedData. If omitted (null) the filename and extension (but not path) from data_file will be used. If you are running the script on Displayr then you must supply this, because there is no file name in the upload ID.
optionsAn object that (if not null) specifies extra options for the new data file, as follows:
auto_tidy_labels: whether to clean up variable labels, as prompted by Q when creating a new project (default: false).
auto_detect_questions: whether to automatically identify multiple-response and grid questions, as prompted by Q when creating a new project (default: false).
strip_labels_html: whether to strip HTML fragments included in labels, as prompted by Q when creating a new project (Q will only prompt if it finds HTML; eg. "<b>Coke</b>" would become "Coke"; default: false).
Returns:The new DataFile object.
Example:
project.addDataFile('c:\\Users\\oliver\\Desktop\\phone.sav', 'phone.sav',
                             {auto_tidy_labels: true, strip_labels_html: true});

addDataFileDialog(title, options)

Presents a dialog box which allows the user to select a data file to import into the project. This function is not intended to be run in Displayr.
title
optionsAn object that (if not null) specifies extra options for the new data file, as follows:
auto_tidy_labels: whether to clean up variable labels, as prompted by Q when creating a new project (default: false).
auto_detect_questions: whether to automatically identify multiple-response and grid questions, as prompted by Q when creating a new project (default: false).
strip_labels_html: whether to strip HTML fragments included in labels, as prompted by Q when creating a new project (Q will only prompt if it finds HTML; eg. "<b>Coke</b>" would become "Coke"; default: false).
Returns:The new DataFile object.
Example:
project.addDataFileDialog("Select New Data File", {auto_tidy_labels: true, strip_labels_html: true});

currentPage()

Returns the current selected page (or NULL if there are no pages in the report).
Returns:The ReportGroup object.
Example:
var group;
if (project.currentPage()) {
    var parent = project.currentPage().parentGroup();
        group = parent.appendGroup();
    parent.moveAfter(group, project.currentPage());
} else
    group = project.report.appendGroup();

dataFiles

Gets an array containing all DataFile objects. The first (and often only) data file is project.dataFiles[0].

equals(obj)

Whether two objects are the same.
objThe object to compare against.
Returns:true or false
Example:
data_file.getQuestionByName('Q2').equals(data_file.questions()[0])

getDataFileById(id)

Finds a data file by its internal id. If you know you have just one then use dataFiles[0].
idThe id of the data file (see the DataFile object.
Returns:A DataFile object.

getDataFileByName(name)

Finds a data file. If you know you have just one then use dataFiles[0].
nameThe name of the data file (see the DataFile object.
Returns:A DataFile object.

getDataInsertingAtItem()

Returns the data tree question at which the insert hover button is showing (or null if this script was not run from the insert hover button). Use isInsertingAbove to know if the insert point is above or below this item. This is only available in Displayr.
Returns:The Question in the data tree currently showing the insert hover button.
Example:
var question = project.getDataInsertingAtItem();
var inserting_at = project.getDataInsertingAtItem();
var data_file = inserting_at.dataFile;
var question = data_file.newRQuestion("as.numeric(Q2)", "Q2 (numeric)", "Q2N", null);
var variables = question.variables
if (!project.isInsertingAbove()) {
    data_file.moveAfter(variables, inserting_at.variables[0]);
} else {
    // find question before the insert-at question
    var questions = data_file.questions;
    var index = questions.indexOf(inserting_at);
    if (index > 0)
        data_file.moveAfter(variables, questions[index - 1].variables[0]);
}

getReportInsertingAtItem()

Returns the report group at which the insert hover button is showing (or null if this script was not run from the insert hover button). Use isInsertingAbove to know if the insert point is above or below this item. This is only available in Displayr.
Returns:The ReportGroup object showing the insert hover button.
Example:
var group = project.getReportInsertingAtItem();
var parent = group.parentGroup();
var new_page = parent.appendGroup();
if (!project.isInsertingAbove()) {
    parent.moveAfter(new_page, group);
} else {
    // find group before the insert-at group
    var sub_items = parent.subItems;
    var index = sub_items.findIndex(si => si.guid === group.guid);
    if (index > 0)
        parent.moveAfter(new_page, sub_items[index - 1]);
    else if (index === 0)
        parent.moveAfter(new_page,null);
}

isInsertingAbove()

Returns true if the insert hover button is showing above the item, false if below, null if this script was not run from the insert hover button. This property is for both the data and report tree insert hover buttons, since you can only get here from one or the other. This is only available in Displayr.

newProject()

Closes any existing project and starts a new one. You won't be able to do anything with the project until you add a DataFile object (see addDataFile()). This function will discard any changes in any open project, without prompting.

open(path, abort)

Opens an existing project. Unsaved changes in any already-open project will be lost.
pathThe path to the file to open. If this is a relative path then it is relative to the location of the script file. You will need to double any back slashes. e.g. 'c:\\Users\\bob\\Project.Q'
abortHow to handle any differences in data file(s). 'Never': Any problems that can be ignored will be ignored. 'OnError': Serious problems will abort the script (e.g. missing variables and other data differences that normally display in red on Q desktop). 'OnWarning': Warnings will abort the script (e.g. new categories, new variables).

report

Returns the root of the report tree, which is a ReportGroup object.

rules

Provides an object you can use to create, reorder and edit Rules.
Example:
var f = project.rules.newBuiltIn("VersusAverage", { "aboveBelow": "1 std dev above" });

save()

Saves the project to the file it was loaded from.

saveAs(new_path)

Saves the project to a new file. This will silently replace any file with the same name.
new_pathThe path to the new file. If this is a relative path then it is relative to the location of the script file. You will need to double any back slashes. e.g. 'c:\\Users\\bob\\Project2.Q'

translations

Gets the Translations object for the whole project, allowing you to override the names used for (for example) statistics, NET, SUM, etc. Translations set here will be overridden if also set for individual tables, plots, etc.
Example:
log(project.translations.get('Column n'));

type

Returns 'Project'.