QScript Project
Jump to navigation
Jump to 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_file | The 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_name | The 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. |
| options | An 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 | |
| options | An 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 an output is selected or 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.
| obj | The 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].
| id | The 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].
| name | The 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(use_son)
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.
| use_son | If current group is a single output: FALSE returns parent of single output, TRUE returns single output |
| 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.
| path | The 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' |
| abort | How 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_path | The 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'.